Hello, agents.
A tool for the part that happens after the PDF.
No signup. No API key. Pay per envelope.
Connect once.
Add this remote Streamable HTTP MCP endpoint to your agent’s MCP client. Authentication is not required to connect.
http://localhost:3000/mcpThe server exposes get_capabilities, upload_document, verify_address, quote_document, create_order, and get_order.
Prefer REST? Here’s the OpenAPI specification. For language models: llms.txt.
From file to front door.
- Check capabilities. Read
mode, supported formats, and current prices. Demo and test modes never send real mail. - Upload a PDF. Base64-encode a portrait US Letter PDF. Keep the returned document ID and token.
- Get a quote. Send the document and US destination. We verify the address and return the standardized version, total in cents, expiry, and print preview.
- Get approval. Show the address, preview, and total to the user. Create an order with their spending limit, address acceptance, and a stable idempotency key.
- Pay. Choose
checkoutfor a human-approved Stripe link. Agents with payment authorization can choosemppfor a card SPT orx402for USDC on Base, when enabled in capabilities. Creating an order never pays it. - Keep the receipt. Save the private order link and token. Poll
get_orderevery 10 seconds or slower.
For machine payments, POST the returned payment_url with X-Order-Token: ORDER_TOKEN. Your payment client answers the HTTP 402 challenge using Authorization: Payment … for MPP or PAYMENT-SIGNATURE for x402. Keep credentials private. Use the same order for retries; a pending or uncertain payment is not a reason to pay again.
Each order uses one payment method. If your agent has no wallet or authorized payment method, select checkout when creating the order and send its link to your human. Demo mode supports simulated checkout only.
Small API. Real mail.
| Endpoint | What it does |
|---|---|
| GET /v1/capabilities | Formats, coverage, pricing, mode. |
| POST /v1/documents | Upload and validate a PDF. |
| POST /v1/addresses/verify | Verify a US destination. |
| POST /v1/quotes | A fixed price and standardized address. |
| GET /v1/quotes/{id}/preview | PDF layout with an address cover sheet. |
| POST /v1/orders | Create an order and select its payment method. Idempotent. |
| POST /v1/orders/{id}/pay/mpp | MPP challenge and authorized card payment. |
| POST /v1/orders/{id}/pay/x402 | Base USDC challenge and payment. |
| GET /v1/orders/{id} | Payment, mailing, refund, and event status. |
Order reads require Authorization: Bearer ORDER_TOKEN. Quote previews accept the quote token. Tokens are private keys to individual resources; they are not accounts.
POST /v1/orders
Content-Type: application/json
Idempotency-Key: a-unique-key-for-this-envelope
{
"quote_id": "quo_…",
"quote_token": "…",
"max_amount_cents": 519,
"accept_standardized_address": true,
"payment_method": "checkout"
}The spending limit must be approved by the user and cover the returned quote. Prices are in USD cents. Reuse the same key and body if a request times out. A quote can create only one order.
Errors return {"error":{"code":"…","message":"…"}}. Check for address_undeliverable, invalid_pdf, quote_expired, budget_exceeded, and idempotency_conflict. Respect Retry-After on rate limits.
The practical details.
What ships: one document per envelope, 1–20 portrait US Letter pages, color or black & white, single- or double-sided. USPS First-Class Mail within the 50 states and DC. No certified mail, binding, stapling, or international delivery in v1.
Print layout: we fit each page inside a ¼-inch safe margin and add a separate address cover sheet. In double-sided mode the back of that cover is blank. The quote preview shows this layout; the printer adds the address to the cover.
Price: setup, cover sheet, and postage, plus a per-page amount. More than six sheets including the cover adds a flat-envelope surcharge. The quote lists every component. Retail totals include any applicable tax; there is no added checkout fee.
Address verification: live mode uses Lob’s address service. Missing or incorrect apartment numbers block checkout. Review the standardized address before you approve it. Demo addresses are simulated; provider test results are fixtures.
Delivery: production and arrival dates depend on the provider and USPS. Estimates are not guarantees. Ordinary mail scans may be incomplete and do not prove a recipient signed. Status is available through the order endpoint; outbound customer webhooks are not in v1.
After payment: orders proceed to printing and mailing. If the provider rejects the print request, your payment is refunded automatically.
Your data: documents and addresses are private to your capability links. Live orders share the PDF and mailing information with Lob; Stripe handles card details. Unordered uploads are removed after 24 hours. Terminal-order documents are removed after 30 days. Order records remain for support and accounting. Do not share your tokens or private links.
Preview release: the displayed mode is authoritative. Demo and test runs do not buy postage or mail documents. Operator accounts, return address, pricing review, and a live test mailing must be complete before launch.