# Courio

> Courio (courio.si) is a REST API and MCP server that prints a PDF and mails it as a real postal letter (standard, tracked, registered, or registered with proof of delivery) to supported destinations worldwide. No account, no plugin. Get a free quote, have the user approve and pay (Stripe Checkout link, or x402 USDC on Base for agents allowed to pay), then track the letter.

Payment is the point of no return: the letter is mailed right after payment and cannot be cancelled. Always show the user the price, the recipient, the document and the terms of sale before payment.

Terms of sale: https://courio.si/terms (paying accepts them; no right of withdrawal once the letter is mailed). Privacy policy: https://courio.si/privacy. Quote and letter-creation responses repeat them as terms_url and privacy_url.

## Pages

- [Send a PDF (web form, works in an agent-driven browser)](https://courio.si/send-pdf)
- [Instructions for AI agents](https://courio.si/agents)
- [Supported countries and services](https://courio.si/countries)
- [Pricing](https://courio.si/pricing)
- [Track a letter](https://courio.si/tracking)
- [Full documentation in one file](https://courio.si/llms-full.txt)
- [Installable agent skill](https://courio.si/skill.md)
- [Terms of sale](https://courio.si/terms)
- [Privacy policy](https://courio.si/privacy)
- [Legal notice](https://courio.si/legal)

## Machine interfaces

- MCP server (streamable HTTP, no auth): https://api.courio.si/mcp
  Tools: get_coverage, quote_letter, send_letter (returns a Stripe link for the user; you cannot pay over MCP), get_letter_status
- REST API: https://api.courio.si/v1
- OpenAPI 3.1: https://api.courio.si/openapi.json
- Live coverage and prices: https://api.courio.si/v1/coverage

## REST flow

1. GET /v1/coverage?country=DE (optional): services, from price, delivery days per country.
2. POST /v1/letters/quote with { service, sender, recipient, document } -> quote_id, price (cents, VAT incl.), legal_product, valid 24 h.
   document is one of { "pdf_base64" }, { "pdf_url" }, { "text", "format": "plain" | "markdown" }. PDF <= 15 MB, <= 20 pages.
3. POST /v1/letters with { quote_id, payment_method: "stripe" | "mpp" | "x402", webhook_url? }
   - stripe: 201 awaiting_payment with payment.checkout_url for the user.
   - mpp (card paid by the agent itself with a Stripe Shared Payment Token, Machine Payments Protocol): 402 with WWW-Authenticate: Payment (method stripe, EUR price), then resend the same request and Idempotency-Key with Authorization: Payment <credential> (or Payment-Authorization when Authorization carries your API key) -> 201 submitted or paid, Payment-Receipt header. 3-D Secure asked by the bank -> 402 authentication_required: use stripe. May be disabled (422 payment_method_unavailable).
   - x402: 402 with PAYMENT-REQUIRED, then resend the same request and Idempotency-Key with PAYMENT-SIGNATURE -> 201 submitted or paid. May be disabled (422 payment_method_unavailable).
4. GET /v1/letters/{letter_id}: status, timeline, tracking number, proof links. Or receive webhooks signed with Courio-Signature: t=<unix>,v1=<hex HMAC-SHA256(webhook_secret, "<t>.<body>")>.

Every POST needs an Idempotency-Key header. Errors are application/problem+json with a stable code and a hint saying what to do next. Optional header X-Agent-Id: your-agent/version.

## Service levels

- standard: ordinary mail, no proof
- tracked: tracking number
- registered: proof of mailing
- registered_ar: proof of delivery (terminations, formal notices, legal deadlines)

## Coverage

- FR: standard (Lettre verte) from €2.00 VAT incl., 4-5 days; tracked (Lettre suivie) from €11.60 VAT incl., 5-15 days; registered (Lettre recommandée) from €9.20 VAT incl., 3-5 days; registered_ar (Lettre recommandée avec AR) from €25.30 VAT incl., 5-15 days
- DE: standard (Standardbrief) from €1.80 VAT incl., 2-4 days; tracked (Einschreiben Einwurf) from €5.50 VAT incl., 2-4 days; registered (Einschreiben) from €19.10 VAT incl., 5-15 days; registered_ar (Einschreiben Rückschein) from €25.30 VAT incl., 5-15 days
- AT: standard (Brief) from €2.20 VAT incl., 2-4 days; registered (Einschreiben) from €19.10 VAT incl., 5-15 days; registered_ar (Einschreiben mit Rückschein) from €25.30 VAT incl., 5-15 days
- CH: standard (B-Post Brief) from €2.50 VAT incl., 3-4 days; tracked (A-Post Plus) from €11.60 VAT incl., 5-15 days; registered (Einschreiben) from €9.90 VAT incl., 2-3 days; registered_ar (Einschreiben mit Rückschein) from €25.30 VAT incl., 5-15 days
- NL: standard (Brief) from €2.60 VAT incl., 2-3 days; registered (Aangetekende brief) from €19.10 VAT incl., 5-15 days; registered_ar (Aangetekend met ontvangstbevestiging) from €25.30 VAT incl., 5-15 days
- BE: standard (Lettre non prioritaire) from €2.10 VAT incl., 3-4 days; registered (Envoi recommandé) from €13.50 VAT incl., 2-3 days; registered_ar (Recommandé avec accusé de réception) from €25.30 VAT incl., 5-15 days
- LU: standard (Lettre) from €2.30 VAT incl., 2-3 days; registered (Envoi recommandé) from €19.10 VAT incl., 5-15 days; registered_ar (Recommandé avec avis de réception) from €25.30 VAT incl., 5-15 days
- GB: standard (Second Class) from €2.40 VAT incl., 3-4 days; tracked (Tracked 48) from €11.60 VAT incl., 5-15 days; registered (Signed For) from €19.10 VAT incl., 5-15 days
- ES: standard (Carta ordinaria) from €2.00 VAT incl., 4-6 days; registered (Carta certificada) from €8.10 VAT incl., 3-5 days; registered_ar (Carta certificada con aviso de recibo) from €25.30 VAT incl., 5-15 days
- US: standard (First-Class Mail) from €6.60 VAT incl., 5-15 days; tracked (First-Class Mail with tracking) from €11.60 VAT incl., 5-15 days; registered (Certified Mail) from €19.10 VAT incl., 5-15 days; registered_ar (Certified Mail with Return Receipt) from €25.30 VAT incl., 5-15 days
- * (every other country): standard (Letter) from €6.60 VAT incl., 5-15 days

Starting prices (1 page, black and white) come from GET /v1/coverage when this file is built; the quote is the exact price.

## x402 spend limit

Official x402 clients refuse payments above $1 by default. A letter usually costs more: raise the spend limit of your x402 client to at least the quote's `usd_amount`, or it will refuse to pay.