--- name: courio-send-letter description: Send a PDF or text as a real physical letter (standard, tracked, registered, registered with proof of delivery) anywhere in the world with Courio, then track it. Use when the user wants to mail, post or send a paper letter, a termination, a formal notice or a registered letter. No account needed. --- # Send a physical letter with Courio Base URL: https://api.sendcourio.com. MCP server: https://api.sendcourio.com/mcp. OpenAPI: https://api.sendcourio.com/openapi.json. Full docs: https://sendcourio.com/llms-full.txt. **Payment is the point of no return.** The letter is mailed right after payment and cannot be cancelled or edited. Before any payment, show the user the price, the recipient and the document, and get their explicit approval. Never pay on your own initiative. ## 1. Check coverage and price (optional) GET https://api.sendcourio.com/v1/coverage?country=DE returns the services, from-price and delivery days. Starting prices when this skill was published (1 page, black and white): - 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 ## 2. Get a quote (free, nothing is charged) POST https://api.sendcourio.com/v1/letters/quote with header Idempotency-Key: and body: { "service": "registered_ar", "sender": {name, address_lines[], postal_code, city, country, email}, "recipient": {...same...}, "document": { "pdf_base64": "..." } } document is one of { "pdf_base64" }, { "pdf_url" }, { "text": "...", "format": "plain" | "markdown" }. PDF up to 15 MB and 20 pages. Services: standard, tracked, registered, registered_ar. The answer has quote_id, price (cents, VAT included, plus usd_amount), legal_product and estimated_delivery_days. Valid 24 h. Show it to the user. ## 3. Pay after approval POST https://api.sendcourio.com/v1/letters with a new Idempotency-Key and { "quote_id": "...", "payment_method": "stripe" | "mpp" | "x402", "webhook_url": "https://..." (optional) }. - **stripe** (default): 201 with payment.checkout_url. Give this link to the user: they pay by card. You cannot pay it yourself. - **mpp** (only if your user gave you a card through a Stripe Shared Payment Token, e.g. with Link: `npx @stripe/link-cli mpp pay`): the first call answers 402 with a `WWW-Authenticate: Payment` challenge for the EUR price. Get an SPT for it and resend the same request, same Idempotency-Key, with `Authorization: Payment ` (`Payment-Authorization` if Authorization carries your API key): 201. If the bank asks for 3-D Secure you get 402 `authentication_required`, and 422 payment_method_unavailable if MPP is off: use stripe. - **x402** (only if your wallet is allowed to spend): the first call answers 402 with a PAYMENT-REQUIRED header (USDC on Base). Sign it with an x402 client and resend the same request, same Idempotency-Key, with the PAYMENT-SIGNATURE header: 201. If x402 is off you get 422 payment_method_unavailable: use stripe. 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. Over MCP, send_letter always returns the Stripe link (MPP and x402 are REST-only). ## 4. Track the letter GET https://api.sendcourio.com/v1/letters/{letter_id} gives status (awaiting_payment, paid, submitted, in_transit, delivered, returned, failed, expired), the timeline, the tracking number and proof links. Or pass webhook_url and verify the Courio-Signature header: t=,v1=.")>; deduplicate on event_id. ## Errors Errors are application/problem+json with a stable code and a hint saying what to do next: read the hint. Same Idempotency-Key and same body to retry safely. quote_expired: ask for a new quote. limit_exceeded: wait retry_after seconds. Optional header X-Agent-Id: your-agent/version.