Courio 推出 REST API 和 MCP 服务器,让 AI 代理能寄出实体信件
来源标题:Courio – your AI agent can now send physical letters
Courio 上线 REST API 与 MCP 服务器,可将 PDF 打印成实体信件并寄出,覆盖普通信到带回执的挂号信。服务无需账号或 API 密钥,按目的国自动映射当地法定邮寄产品(如法国 Lettre recommandée avec AR、美国 Certified Mail),用户确认报价并付款后可追踪投递。
以下正文同步自 Hacker News 最新,版权归原站所有,已转换为易读排版。
Courio (sendcourio.com) is a REST API and MCP server that prints a PDF and mails it as a real letter, from a standard letter to registered mail with proof of delivery, sent as the destination country’s own postal product. You do not need an account, an API key or an installed plugin. You get a quote, your user approves and pays, the letter is mailed, and you can follow it.
Ask for a generic level; Courio maps it to the legal product of the destination country (FR “Lettre recommandée avec AR”, DE “Einschreiben Rückschein”, US “Certified Mail”…). The quote returns the exact product in legal_product.
If the user asks for “a registered letter” for a legal matter (termination, formal notice, dispute), registered_ar is almost always what they mean.
Hosted, stateless, streamable HTTP at https://api.sendcourio.com/mcp. No local install, no key. Add it as a remote MCP server or custom connector:
{ "mcpServers": { "courio": { "type": "http", "url": "https://api.sendcourio.com/mcp" } } }
ToolCall it whenReturns get_coverage Before quoting, to check a destination (country optional, ISO alpha-2). Services per country, “from” price, delivery days, legal product. quote_letter You have both addresses and the document. Free, commits to nothing. quote_id, fixed price (24 h), legal product, delivery estimate. send_letter The human agreed to the price. Same quote_id twice returns the same letter. letter_id, Stripe checkout_url for the human, next_step. get_letter_status To follow the letter after payment. Status, timeline, tracking number, proof links.
MPP and x402 payments are REST-only for now; MCP uses the Stripe link.
curl "https://api.sendcourio.com/v1/coverage?country=DE"
- Quote
POST /v1/letters/quote. The document is exactly one of { "pdf_base64": "…" }, { "pdf_url": "https://…" } or { "text": "…", "format": "plain" | "markdown" }. PDF up to 15 MB and 20 pages. Addresses: name (≤ 80), optional company, 1–3 address_lines, postal_code, city, country (ISO alpha-2). Put the sender’s email in sender. Optional options: color (default false), duplex (default true); currency: EUR or USD. No need to place the address in an envelope window: Courio adds an address page when needed (it is counted in the price).
curl -X POST https://api.sendcourio.com/v1/letters/quote
-H "Content-Type: application/json"
-H "Idempotency-Key: $(uuidgen)"
-H "X-Agent-Id: my-agent/1.0"
-d '{
"service": "registered_ar",
"sender": {
"name": "Jane Doe",
"address_lines": ["12 rue des Lilas"],
"postal_code": "75011", "city": "Paris", "country": "FR",
"email": "jane@example.com"
},
"recipient": {
"name": "Service résiliation",
"company": "Assur'Plus",
"address_lines": ["4 quai Perrache"],
"postal_code": "69002", "city": "Lyon", "country": "FR"
},
"document": { "text": "Madame, Monsieur,\n\nJe résilie...", "format": "markdown" }
}'
Response 200. Amounts are in cents, VAT included:
{ "quote_id": "qt_8fK2mQ0vXb7LwR4nT1yZc9Ae", "expires_at": "2026-11-03T10:12:00Z", "price": { "amount": 1290, "currency": "EUR", "tax_included": true, "usd_amount": 1405 }, "legal_product": { "code": "FR_REGISTERED_AR", "local_name": "Lettre recommandée avec AR", "english_name": "Registered letter with proof of delivery", "proof": "delivery" }, "estimated_delivery_days": { "min": 2, "max": 4 }, "pages": 2, "warnings": [] }
Show price, legal_product.local_name and the delivery estimate (estimated_delivery_days) to the human now.
curl -X POST https://api.sendcourio.com/v1/letters
-H "Content-Type: application/json"
-H "Idempotency-Key: $(uuidgen)"
-d '{
"quote_id": "qt_8fK2mQ0vXb7LwR4nT1yZc9Ae",
"payment_method": "stripe",
"webhook_url": "https://agent.example.com/hooks/courio"
}'
201 Created { "letter_id": "ltr_3Hq9ZxV2pLm7Ns0Kd4Rt8Wy1", "status": "awaiting_payment", "payment": { "checkout_url": "https://checkout.stripe.com/c/pay/cs_...", "expires_at": "2026-11-03T10:14:00Z" }, "webhook_secret": "9c1e…(64 hex chars)", ... }
Give checkout_url to the human. The link expires after about 24 h; unpaid letters become expired. Store webhook_secret if you passed a webhook_url: it is returned only once.
If your user lets you spend on their card through a Stripe Shared Payment Token (for example with Link for agents), pay the quote yourself with the Machine Payments Protocol. The amount is the quote’s EUR price. Your user sets the limits (amount, expiry, seller) when granting the token.
1. Ask for the letter with MPP: no credential yet
POST /v1/letters { "quote_id": "qt_...", "payment_method": "mpp" } -> 402 payment_required WWW-Authenticate: Payment id="...", realm="api.sendcourio.com", method="stripe", intent="charge", request="<base64url: amount, currency eur, networkId>", expires="..."
2. Get a Shared Payment Token for that challenge from your user's wallet
(e.g. npx @stripe/link-cli mpp pay), then resend the SAME request with the SAME Idempotency-Key
POST /v1/letters { "quote_id": "qt_...", "payment_method": "mpp" } Authorization: Payment <base64url credential with {"spt": "spt_..."}> -> 201 { "letter_id": "ltr_...", "status": "submitted" | "paid", "payment": { "method": "mpp", "payment_intent": "pi_...", ... } } Payment-Receipt: <base64url receipt>
If Authorization already carries your API key, send the credential in Payment-Authorization instead.
A challenge lasts 15 minutes (never longer than the quote). Replaying the same credential never charges twice.
If the bank asks for 3-D Secure, you get 402 with reason: authentication_required: switch to stripe and hand the link to your user.
MPP can be disabled on a deployment: 422 payment_method_unavailable means use stripe.
Paying with x402 (autonomous agents)
If you can sign crypto payments, pay the quote yourself in USDC on Base using x402. The amount is the quote’s usd_amount.
1. Ask for the letter with x402: no payment header yet
POST /v1/letters { "quote_id": "qt_...", "payment_method": "x402" } -> 402 payment_required PAYMENT-REQUIRED: <base64 requirements> (same object in the body: accepts[])
2. Sign a payment for those requirements (USDC on Base) with an x402 client,
then resend the SAME request with the SAME Idempotency-Key
POST /v1/letters { "quote_id": "qt_...", "payment_method": "x402" } PAYMENT-SIGNATURE: <base64 signed payment> -> 201 { "letter_id": "ltr_...", "status": "submitted" | "paid", ... } PAYMENT-RESPONSE: <base64 settlement>
Once the payment settles, the response is never an error: you get 201 with submitted, or paid if submission continues in the background.
Official x402 clients cap a payment at $1 by default. Raise the spend limit to cover the quote first.
x402 can be disabled on a deployment: 422 payment_method_unavailable means use stripe.
Tracking and webhooks
curl https://api.sendcourio.com/v1/letters/ltr_3Hq9ZxV2pLm7Ns0Kd4Rt8Wy1
No auth: the letter_id is the credential. Without the API key that created it, the recipient is reduced to city and country. Proof links (deposit for registered, delivery for registered_ar) are signed and valid 15 minutes; fetch the letter again for fresh ones.
awaiting_payment → paid → submitted → in_transit → delivered, or returned, failed (refunded), expired (never paid).
With a webhook_url (public https only), every status change is POSTed as { letter_id, status, occurred_at, data }, retried with backoff for 24 h. Verify the Courio-Signature header:
import { createHmac, timingSafeEqual } from 'node:crypto';
// header: Courio-Signature: t=1762077120,v1=5f2c...
function verify(rawBody: string, header: string, secret: string): boolean {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=', 2)));
const expected = createHmac('sha256', secret).update(${parts.t}.${rawBody}).digest('hex');
const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ''));
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return ok && fresh;
}
Errors
RFC 9457 application/problem+json, always with code and hint. A 5xx or a network failure is safe to retry with the same Idempotency-Key.
Defaults: one letter per request, price capped per letter, a daily number of letters per IP, sender email, wallet and API key. The complete list is in openapi.json.
Local legal products in these 10 countries. Every other ISO country accepts standard only. Human-readable list: /countries. Live data with prices: GET /v1/coverage.
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。