For agents & developers

Send a physical letter via API or MCP

Updated July 13, 2026

Connect your agent (MCP)

Postbot is a remote MCP server over Streamable HTTP. initialize andtools/list work without a token, so any MCP client can discover the tools before deciding to authenticate.

claude mcp add --transport http postbot https://postbot.cz/mcp

Settings → Connectors → Add custom connector
URL: https://postbot.cz/mcp

Settings → MCP → Add new MCP server
URL: https://postbot.cz/mcp (Streamable HTTP)

Settings → Connectors → Advanced → Developer mode
Add connector: https://postbot.cz/mcp
# needs a plan with developer mode; may be admin-gated in workspaces

The tools

How payment works — no spending without your setup

A valid unauthenticated send doesn't fail dead: it returns402 with rails — a ready Stripe pay link for that exact letter. The agent hands the link to its human; once paid, the letter mails automatically. For repeat sends, top up prepaid CZK credit with an API key or authorize an interactive MCP client via OAuth 2.1.

you: send a registered letter to Jan Novák, Dlouhá 5, Praha
agent → send_letter_cz({...})
postbot → 402: rails.oneoff.payUrl (110 CZK)
agent: “Letter's ready — pay here: …”
you: [click, pay by card]
postbot → ✉ dispatched · tracking RR1234567CZ

• Without your click or prepaid credit, the agent can't spend a single koruna. (With prepaid credit, sends debit the balance autonomously — that's what the top-up authorizes.)
• Every letter has a firm price computed up front from the rendered PDF.
• Everything sent is visible on your account — including the tracking number.

REST API — no MCP client needed

Quote and pay for a single letter without an account:

curl -X POST https://postbot.cz/api/oneoff \
  -H "content-type: application/json" \
  -d '{
    "to": {
      "name": "Jan Novák",
      "street": "Dlouhá",
      "houseNumber": "5",
      "zip": "110 00",
      "city": "Praha"
    },
    "document": { "markdown": "# Notice\n\nDear Mr. Novák, ..." },
    "service": "obycejne"
  }'

# → { "payUrl": "https://checkout.stripe.com/...", ... }
# Open payUrl, pay by card — the letter mails automatically.

Preview first — the exact PDF and a firm price, no side effects:

curl -X POST https://postbot.cz/api/preview \
  -H "content-type: application/json" \
  -d '{
    "to": {
      "name": "Jan Novák",
      "street": "Dlouhá",
      "houseNumber": "5",
      "zip": "110 00",
      "city": "Praha"
    },
    "document": { "text": "Dear Mr. Novák, ..." },
    "service": "obycejne"
  }'

# → { "pdfBase64": "...", "sheets": 1, "payCzk": 50 }
# The exact PDF that will be printed + a firm price. No side effects.

Funded sends: POST /api/send with Authorization: Bearer pb_…(prepaid credit). Registered letters ("service": "doporucene") require afrom sender address.

Pricing

The firm price is computed from the rendered PDF (sheet count) before any payment — what the preview shows is what you pay.

Coverage and formats

• Delivery: Czech Republic only — the carrier is Česká pošta (DopisOnline). The agent and payer can be anywhere.
• Content: pdfBase64, markdown, or text — rendered to A4 with Czech-capable fonts.
• Anonymous endpoints accept inline content only; pdfUrl is rejected there (SSRF protection).

Machine-readable docs

• llms.txt — the whole service in one plain-text page
• mcp.json — MCP server metadata
• openapi.json — REST schema
• auth.md — auth flows for agents