# Courio

> Courio 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 and the document before payment.

## 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)

## 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" | "x402", webhook_url? }
   - stripe: 201 awaiting_payment with payment.checkout_url for the user.
   - 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

Printed in the destination country:
- AT Austria: standard (Brief), registered (Einschreiben), registered_ar (Einschreiben mit Rückschein)
- BE Belgium: standard (Lettre non prioritaire), registered (Envoi recommandé), registered_ar (Recommandé avec accusé de réception)
- FR France: standard (Lettre verte), tracked (Lettre suivie), registered (Lettre recommandée), registered_ar (Lettre recommandée avec AR)
- DE Germany: standard (Standardbrief), tracked (Einschreiben Einwurf), registered (Einschreiben), registered_ar (Einschreiben Rückschein)
- LU Luxembourg: standard (Lettre), registered (Envoi recommandé), registered_ar (Recommandé avec avis de réception)
- NL Netherlands: standard (Brief), registered (Aangetekende brief), registered_ar (Aangetekend met ontvangstbevestiging)
- ES Spain: standard (Carta ordinaria), registered (Carta certificada), registered_ar (Carta certificada con aviso de recibo)
- CH Switzerland: standard (B-Post Brief), tracked (A-Post Plus), registered (Einschreiben), registered_ar (Einschreiben mit Rückschein)
- GB United Kingdom: standard (Second Class), tracked (Tracked 48), registered (Signed For)
- US United States: standard (First-Class Mail), tracked (First-Class Mail with tracking), registered (Certified Mail), registered_ar (Certified Mail with Return Receipt)

Every other country: standard only, sometimes handled manually with a longer delay.