--- 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.courio.si. MCP server: https://api.courio.si/mcp. OpenAPI: https://api.courio.si/openapi.json. Full docs: https://courio.si/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.courio.si/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 €8.70 VAT incl., 5-15 days, handled manually; tracked (Lettre suivie) from €14.30 VAT incl., 5-15 days, handled manually; registered (Lettre recommandée) from €22.50 VAT incl., 5-15 days, handled manually; registered_ar (Lettre recommandée avec AR) from €29.40 VAT incl., 5-15 days, handled manually - DE: standard (Standardbrief) from €8.70 VAT incl., 5-15 days, handled manually; tracked (Einschreiben Einwurf) from €14.30 VAT incl., 5-15 days, handled manually; registered (Einschreiben) from €22.50 VAT incl., 5-15 days, handled manually; registered_ar (Einschreiben Rückschein) from €29.40 VAT incl., 5-15 days, handled manually - AT: standard (Brief) from €8.70 VAT incl., 5-15 days, handled manually; registered (Einschreiben) from €22.50 VAT incl., 5-15 days, handled manually; registered_ar (Einschreiben mit Rückschein) from €29.40 VAT incl., 5-15 days, handled manually - CH: standard (B-Post Brief) from €8.70 VAT incl., 5-15 days, handled manually; tracked (A-Post Plus) from €14.30 VAT incl., 5-15 days, handled manually; registered (Einschreiben) from €22.50 VAT incl., 5-15 days, handled manually; registered_ar (Einschreiben mit Rückschein) from €29.40 VAT incl., 5-15 days, handled manually - NL: standard (Brief) from €8.70 VAT incl., 5-15 days, handled manually; registered (Aangetekende brief) from €22.50 VAT incl., 5-15 days, handled manually; registered_ar (Aangetekend met ontvangstbevestiging) from €29.40 VAT incl., 5-15 days, handled manually - BE: standard (Lettre non prioritaire) from €8.70 VAT incl., 5-15 days, handled manually; registered (Envoi recommandé) from €22.50 VAT incl., 5-15 days, handled manually; registered_ar (Recommandé avec accusé de réception) from €29.40 VAT incl., 5-15 days, handled manually - LU: standard (Lettre) from €8.70 VAT incl., 5-15 days, handled manually; registered (Envoi recommandé) from €22.50 VAT incl., 5-15 days, handled manually; registered_ar (Recommandé avec avis de réception) from €29.40 VAT incl., 5-15 days, handled manually - GB: standard (Second Class) from €8.70 VAT incl., 5-15 days, handled manually; tracked (Tracked 48) from €14.30 VAT incl., 5-15 days, handled manually; registered (Signed For) from €22.50 VAT incl., 5-15 days, handled manually - ES: standard (Carta ordinaria) from €8.70 VAT incl., 5-15 days, handled manually; registered (Carta certificada) from €22.50 VAT incl., 5-15 days, handled manually; registered_ar (Carta certificada con aviso de recibo) from €29.40 VAT incl., 5-15 days, handled manually - US: standard (First-Class Mail) from €8.70 VAT incl., 5-15 days, handled manually; tracked (First-Class Mail with tracking) from €14.30 VAT incl., 5-15 days, handled manually; registered (Certified Mail) from €22.50 VAT incl., 5-15 days, handled manually; registered_ar (Certified Mail with Return Receipt) from €29.40 VAT incl., 5-15 days, handled manually - * (every other country): standard (Letter) from €8.70 VAT incl., 5-15 days, handled manually ## 2. Get a quote (free, nothing is charged) POST https://api.courio.si/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.courio.si/v1/letters with a new Idempotency-Key and { "quote_id": "...", "payment_method": "stripe" | "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. - **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. ## 4. Track the letter GET https://api.courio.si/v1/letters/{letter_id} gives status (awaiting_payment, paid, submitted, in_transit, delivered, returned, failed, manual_pending, manual_done, 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.