For developers

REST API, CLI, and MCP server for mailing physical letters in the Czech Republic — three interfaces, one core.

REST API

Four JSON endpoints under /api. The request body for sending and previewing is the same as the MCP send_letter_cz tool's input.

POST /api/send

Send a letter

Prints, envelopes, and mails a letter via Česká pošta. Charged against the account's prepaid CZK credit; the price is computed from the rendered PDF (postage band + print).

POST /api/preview

Preview + firm price

Renders the exact PDF that would be printed and returns it with the firm price. No side effects — use before /api/send or /api/oneoff to show a human what will mail.

POST /api/topup

Top up credit

Funds the account's prepaid CZK balance via Stripe. Returns a Stripe Checkout URL.

POST /api/oneoff

Pay for one letter, no account

One-off card payment for a single letter. Prices the rendered PDF and returns a pay URL.

Authentication and payment (401 / 402)

A missing or invalid API key on an invalid letter returns 401.
A valid but unfunded letter (no key, or insufficient credit) returns 402 with a body carrying both funding rails: rails.oneoff.payUrl (a ready pay-link for that exact letter) and rails.credit.topupUrl (prepaid-credit top-up).
/api/preview never charges or sends anything — it only renders the PDF and computes the firm price.

CLI

The @postbotcz/cli terminal client calls the same core as REST and MCP.

Install

npm i -g @postbotcz/cli
# or: bun add -g @postbotcz/cli

Usage

posta send letter.md --to-name "Jan Novák" --to-street "Dlouhá" --to-house "5" --to-city "Praha" --to-zip "110 00"
posta status 201007091003

MCP self-host

Hosted server (no install)

Add https://postbot.cz/mcp to your agent as a remote MCP server (Streamable HTTP) — nothing to install.

Self-host (stdio)

bunx @postbot/mcp

For the full 3-step agent-connection recipe (install, first letter, credit), see For agents.

Agent discovery

Machine-readable entry points for agents that discover Postbot on their own.

Pricing

Current live minimums and the price formula live on the Pricing.