# Mail by Pony > Mail by Pony turns a letter written online into real mail. It prints the letter, puts it in an envelope, and sends it through USPS (US addresses). Agents can write letters, collect addresses in chat, show exact print proofs and send them: from the person's prepaid balance when they have allowed the assistant, or through a one-click Stripe payment link. Developers can automate mail through the HTTP API with API keys. Mail by Pony is an independent service and is not affiliated with the United States Postal Service. ## Connect - MCP server (Streamable HTTP): `https://www.mailbypony.com/mcp` - Claude Code: `claude mcp add --transport http mail-by-pony https://www.mailbypony.com/mcp` - Claude app: Settings → Connectors → Add custom connector → paste the server URL. - JSON-config clients (Cursor and similar): `{"mcpServers":{"mail-by-pony":{"url":"https://www.mailbypony.com/mcp"}}}` - VS Code (Copilot agent mode), `.vscode/mcp.json`: `{"servers":{"mail-by-pony":{"type":"http","url":"https://www.mailbypony.com/mcp"}}}` - Grok (grok.com): https://grok.com/connectors → New Connector → Custom → name Mail by Pony, server URL `https://www.mailbypony.com/mcp/signin` → sign in to Pony and approve. Use `/mcp/signin` for Grok and any client that only starts OAuth when the connection itself is refused: it answers every unauthenticated request with 401 and an OAuth challenge, then serves the same tools as `/mcp`. On Grok Business/Enterprise a team admin adds the connector first. Guide for people: https://www.mailbypony.com/agents/grok - Gemini CLI: `gemini mcp add --transport http mail-by-pony https://www.mailbypony.com/mcp` - Setup steps for people, by assistant: https://www.mailbypony.com/agents - Website for people: https://www.mailbypony.com ## Common letters Guides for people, with what fits and what does not. Share the one that matches what the person wants to send. - Letters from Santa: https://www.mailbypony.com/letters/santa . Sender name can be "Santa Claus"; the return address must still be a real US address. - Letters to Congress: https://www.mailbypony.com/letters/congress . Washington office mail is screened and slower; district or state offices are usually faster. - Mail from abroad: https://www.mailbypony.com/letters/from-abroad . Pony mails inside the US: recipient and return address must both be US addresses. - Cancellation and complaint letters: https://www.mailbypony.com/letters/cancellation . Not certified or tracked; for proof of delivery or deadlines, the person should use USPS Certified Mail. No credit bureau disputes (they need Social Security numbers and IDs). - Letters to a landlord: https://www.mailbypony.com/letters/landlord . Repair requests and follow-ups. Not certified; formal notices (to vacate, deposit demands) may legally need certified mail or hand delivery. - Billing dispute letters: https://www.mailbypony.com/letters/dispute . Wrong charges and bills, with an account number or last four card digits only. Disputes with legal time limits (credit card billing errors, debt verification) should go by USPS Certified Mail. No credit bureau disputes. - Letters to an insurer: https://www.mailbypony.com/letters/insurance . Claim follow-ups, cancellations and complaints. No medical records, so most health insurance appeals do not fit. - Letters to someone in prison or jail: https://www.mailbypony.com/letters/prison . Use the person's full name and ID number and the facility's mailing address; keep the default white paper, white envelope and a typed style; facility rules vary. ## Status (October 2026) - Open without sign-in: `catalog` (styles, papers, envelopes, prices, payment readiness). - OAuth sign-in is available for every other tool. Follow the authorization challenge, sign in on Pony and approve the connection. Do not ask the person for passwords, tokens, or codes in chat. - ChatGPT app and plugin directory listings are in preparation. ## Tools Read-only unless noted. All tools except `catalog` require OAuth. Request the provider-supported `email` scope (and `offline_access` for a renewable connection). The signed `pony_permissions` claim carries the application permissions shown below; these are not OAuth scopes accepted by Supabase. The consent page displays the complete permission bundle. - `catalog`: styles, materials, prices, payment and prepaid readiness. No sign-in. - `list_drafts`, `get_draft` (`letters:read`): the person's drafts. Addresses are masked. - `create_draft`, `update_draft`, `archive_draft` (`letters:write`): write and edit letters, including sender/recipient addresses given in chat. Text or Markdown pages; keep each page's stable `id` when editing or reordering. `address_validation` lists missing fields. - `upload_attachment`, `remove_attachment`, `add_library_artwork` (`letters:write`): print PDFs, photos, transparent PNG artwork. - `list_address_references` (`letters:read`): addresses the person saved on the website, by ID. - `preview`, `show_letter` (`letters:read`): render the exact pages that will print. - `quote` (`letters:read`): a revision-bound subtotal. A missing price means pricing is unavailable, not free. - `create_payment_link` (`checkout:write`): when the person says to send, create the order and a Stripe Checkout link. Paying it approves and sends the letter. - `quote_for_send`, `send_with_credits` (`orders:send`): final price and send from the prepaid balance under the person's permission for this assistant. - `get_credit_balance`, `list_agent_grants`, `get_connection_identity`: balance, send permissions and this assistant's client ID. - `create_template`, `list_templates`, `get_template`, `delete_template`, `create_template_draft` (`letters:write`/`letters:read`): reusable letters with `{{variable}}` placeholders. - `create_batch`, `get_batch` (`orders:send`): send up to 100 letters in one call, each with its own `client_reference`. - `list_orders`, `get_order`, `reconcile_payment` (`orders:read`): real order and payment status. - `cancel_order` (`orders:cancel`): only before preparation, only with explicit approval. - `request_status`: result of a previous idempotent mutation. - `prepare_checkout`, `get_checkout_preparation`, `checkout` (`checkout:write`): optional website-consent flow for people who prefer to approve on Pony. Full JSON schemas: `https://www.mailbypony.com/api/agent/tools`. REST API reference: `https://www.mailbypony.com/docs/api`. ## Rules for agents 1. Ordinary, non-sensitive correspondence only. No card numbers, government IDs, secrets, or confidential documents. 2. Run `preview` and tell the person what will print (pages, recipient, options, price) before sending. 3. Send only when the person asks. If prepaid sending is ready and they have allowed this assistant, use `quote_for_send` then `send_with_credits`; otherwise give them the `create_payment_link` checkout URL. 4. Never claim a letter was paid, printed, mailed, or delivered unless `get_order` says so. "Mailed" means handed to USPS, not delivered. 5. Every edit advances the draft `version`. Send the current version; a 409 means someone else changed it, so re-read and try again. 6. Reuse idempotency keys when retrying. Changed arguments with the same key conflict. 7. Collect missing address details in chat and ask only for fields in `address_validation`. Never guess a ZIP or claim postal verification. 8. On insufficient funds, share the returned funding link or offer a payment link. Never top up automatically. ## Optional - Styles include typed fonts and an experimental handwriting style. Unsupported characters fail with exact code points instead of substituting another font. - Markdown supports headings, paragraphs, bold, italics, lists and links. Raw HTML and remote images are rejected. ## HTTP API for developers Developer docs: https://www.mailbypony.com/docs (every page is also plain Markdown at /docs/.md) Quickstart: https://www.mailbypony.com/docs/quickstart.md Authentication (keys, OAuth, scopes, sending permissions): https://www.mailbypony.com/docs/authentication.md Concepts (retries, statuses, credits): https://www.mailbypony.com/docs/concepts.md API reference: https://www.mailbypony.com/docs/api.md Error codes: https://www.mailbypony.com/docs/errors.md Webhooks: https://www.mailbypony.com/docs/webhooks.md HTTP contract: https://www.mailbypony.com/api/v1/openapi.json Runnable example: https://www.mailbypony.com/docs/cron_send_example.py Create an API key with a spending limit on Account → Credits, fund the balance, then create drafts (text, Markdown or uploaded PDF), generate the proof, get a final quote and send. `grant_id` is optional: the key's own permission is used. Same key/body across HTTP and MCP returns one order and one debit; resolve uncertainty with `request_status`. Queued is not printed, mailed or delivered. Test mode (`pony_test_` keys): https://www.mailbypony.com/docs/test-mode.md . Templates: https://www.mailbypony.com/docs/templates.md . Batches: https://www.mailbypony.com/docs/batches.md . Check `catalog.prepaid` for live readiness. Pony has no customer scheduler; your system owns scheduling. After card payment, resume with `reconcile_payment` for the original `order_id`, then `get_order`. A redirect is not payment evidence. Reuse the original order on retry. Muse connector: `/mcp/muse` offers card-per-letter purchases. Quote and approve the exact final amount before creating the order; enter card details securely in Stripe, then return to Muse for provider-confirmed status. Prepaid funding and spending are not offered on this endpoint.