MailSnail

npx add-mcp 'https://api.mailsnail.dev/mcp'

Managed — sign in, pay, send

Nothing to install and no keys to paste. The server URL is:

https://api.mailsnail.dev/mcp

Two steps: add it, then start the sign-in from your client — adding a server registers it, but doesn't open the browser on its own.

1. Add the server

The URL above is the same everywhere. Where to paste it:

• Claude (claude.ai, desktop, mobile): Settings → Connectors → Add custom connector. Paste the URL, then click Connect and sign in. Custom connectors need a paid Claude plan; on Team and Enterprise an owner may need to add it first.
• Claude Code: One command, below. Then run /mcp and choose Authenticate.
• ChatGPT: Turn on Developer mode in ChatGPT’s settings, then add a connector with the URL and sign in when prompted. Availability depends on your ChatGPT plan, and on Business or Enterprise an admin may need to enable it.
• Gemini, Perplexity, Mistral Le Chat, Grok: Each has a “custom connector” or “add MCP server” option in its connectors or apps settings. Paste the URL and sign in. These apps don’t review custom connectors, so you’re connecting directly to us.
• Cursor and other JSON-config clients: Use the url form in the JSON block below.

Claude Code, one line. Note -t http: this is a remote server, not an npm package.

claude mcp add -t http mailsnail https://api.mailsnail.dev/mcp

Cursor and other clients that take a JSON config use the url form:

{
  "mcpServers": {
    "mailsnail": {
      "url": "https://api.mailsnail.dev/mcp"
    }
  }
}

2. Sign in

The server answers an unauthenticated call with a standard OAuth challenge, so your client knows where to send you and registers itself. You just approve it in the browser.

# In Claude Code, open the MCP panel:
/mcp

# Select "mailsnail" -> Authenticate.
# Your browser opens our sign-in page. Sign in (or create an
# account), approve access, and the tab hands the session back.
# "mailsnail" then reads: connected.

Sign-in is email and password today. There is no separate account to create on this website — the account your agent authenticates against is the account.

3. Send something — and pay when asked

You do not have to fund anything up front. The first send tells you what it needs and hands back two links: one to pay for just that letter, one to add funds to your balance.

You: Ask your agent to mail something. For example —
     "Send a letter to Jane Doe at 1 Main St, Brooklyn NY 11201
      that says: thanks for the referral."

Agent: calls preview_letter -> shows you a proof PDF and the price
Agent: calls send_letter   -> { "error": "payment_setup_required",
                                "pay_per_letter_url": "https://checkout.stripe.com/...",
                                "pay_per_letter_cents": 151,
                                "setup_url": "https://checkout.stripe.com/..." }

You: open one of the two links and pay. Both are one-time payments
     and your card is not saved. Stripe handles the card; we never
     see the number.
       pay_per_letter_url  pay for just this letter by card
                           ($1.51 for a one-page first-class letter)
       setup_url           add funds to your balance ($25 by default);
                           letters then cost less ($1.21)

Agent: retry send_letter   -> { "id": "...", "status": "queued" }

Things to ask

• “Mail a thank-you letter to Jane Doe at 1 Main St, Brooklyn NY 11201. Show me the proof and price before sending.”
• “Send a certified letter with a return receipt to my tenant at 22 Oak Ave, Austin TX 78701 giving 30 days’ notice. I need the green card back.”
• “Check whether 1600 Pennsylvania Ave NW, Washington DC 20500 is a deliverable address.”
• “How much balance do I have left? If auto-reload is on, turn it off.”
• “What happened to the letter I sent yesterday? Here’s the receipt token.”

Why a letter costs less from a balance than by card

Card processing costs 2.9% plus a fixed 30¢ on every charge. Pay for a single letter by card (pay_per_letter_url) and that one charge carries the whole fee, so a one-page first-class letter costs $1.51 instead of $1.21. Funding a balance once (setup_url) and drawing mail against it spreads the fee over many letters, which is what keeps cheap mail cheap. Both prices are at our cost. Both links are one-time payments: we don't save your card or charge it again. If you want the balance to refill itself, ask your assistant to set up auto-reload. Stripe's page then saves your card and shows the terms (by default, $25 whenever the balance falls below $10), and you agree by paying. You can turn it off any time by asking your assistant (turn_off_auto_reload) or emailing hello@mailsnail.dev. More on billing.

Tools your agent gets in managed mode

• verify_address — USPS address validation. Free: never charges, never mails.
• preview_letter — Proof PDF plus the exact price, without charging or mailing. Shows both prices: amount_cents (from your balance) and pay_per_letter_cents (paying for just that letter by card). The usual first step.
• send_letter — Mails a letter, drawn against your balance. If the balance can’t cover it, it returns two Stripe links: pay_per_letter_url (pay for just that letter by card) and setup_url (add funds). Add extra_service: "certified" for tracking. Paid and irreversible, so your client asks before it runs.
• get_balance — Your balance, saved card, and auto-reload settings. Free.
• add_payment_method — Returns a Stripe link to add funds. By default it is a one-time payment and your card is not saved; with auto_reload: true it also saves the card for auto-reload. If a card is on file it also returns a billing-portal link. Charges nothing by itself.
• turn_off_auto_reload — Turns off automatic charges to your saved card and keeps the card on file. Free. On a team account, only an organization admin can use it.
• get_letter — Delivery status for a letter, with the USPS tracking number for certified mail. Free.
• cancel_letter — Cancel a letter before printing starts (usually within about a day) and get its full price back on your balance.

send_postcard and get_postcard are temporarily unavailable.

list_letters is not available in managed mode. It exists only on the self-hosted path below, where the underlying provider account is yours.

What a piece costs

from $1.21

First-class letter

$1.51 for one letter by card

from $8.61

Certified letter

$8.83 for one letter by card

from $11.64

Certified + electronic return receipt

$11.83 for one letter by card

from $14.27

Certified + green-card return receipt

$14.42 for one letter by card

Priced at our cost. The large price is drawn from your balance; the smaller one is what you pay to cover just one letter by card, which is a little higher because that single payment carries Stripe's whole processing fee. These are one-page, black-and-white prices; extra pages and color are priced at our cost. Ask your agent to call preview_letter and it will quote the exact price before anything is charged.

Self-hosted — bring your own mail provider

Run the open-source server yourself against your own Click2Mail or Lob account. There is no sign-in and no balance: your provider bills you directly, and we are not in the payment path at all. This is the mailsnail npm package over stdio.

Claude Code

claude mcp add mailsnail \
  -e MAIL_PROVIDER=click2mail \
  -e CLICK2MAIL_USERNAME=your-username \
  -e CLICK2MAIL_PASSWORD=your-password \
  -- npx -y mailsnail

Claude Desktop and Cursor

Claude Desktop: claude_desktop_config.json (Settings → Developer → Edit Config). Cursor: ~/.cursor/mcp.json or the project's .cursor/mcp.json. Needs Node.js 18+.

{
  "mcpServers": {
    "mailsnail": {
      "command": "npx",
      "args": [
        "-y",
        "mailsnail"
      ],
      "env": {
        "MAIL_PROVIDER": "click2mail",
        "CLICK2MAIL_USERNAME": "your-username",
        "CLICK2MAIL_PASSWORD": "your-password"
      }
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml.

[mcp_servers.mailsnail]
command = "npx"
args = ["-y", "mailsnail"]

[mcp_servers.mailsnail.env]
MAIL_PROVIDER = "click2mail"
CLICK2MAIL_USERNAME = "your-username"
CLICK2MAIL_PASSWORD = "your-password"

Set MAIL_PROVIDER=lob with LOB_API_KEY to use Lob instead. Self-hosted mode adds list_letters (Lob only — Click2Mail has no list endpoint), and cancel_letter works against your own provider account within its window. Source and provider docs are on GitHub.

HTTP API, no account

There is also an anonymous path for agents that can pay for themselves: post a letter, get a 402 with the price, retry with a Stripe Shared Payment Token for that amount. The quoted amount is the single-letter card price, which includes Stripe's fee. No sign-in, no balance, no account on our side.

Worth being straight about the tradeoff: most coding agents, including Claude Code, cannot mint a Shared Payment Token on their own today. If yours can't, use managed mode above — that is precisely the gap it was built to close. Settlement in USDC over x402 is planned, not shipped.

# Anonymous, no account: quote first, then pay for that exact piece.
# Your client has to be able to produce a Stripe Shared Payment Token.

curl -X POST https://api.mailsnail.dev/v1/letters \
  -H "Content-Type: application/json" \
  -d '{
    "to": {
      "name": "Jane Doe",
      "address_line1": "1 Main St",
      "address_city": "Brooklyn",
      "address_state": "NY",
      "address_zip": "11201"
    },
    "from": { "…same shape…": "" },
    "body_text": "Hello from your agent."
  }'

# -> 402 Payment Required
# {
#   "status": 402,
#   "payment_request": {
#     "amount": 151, "currency": "usd", "methods": ["stripe.spt"],
#     "idempotency_key": "…"
#   }
# }
# 151 is the card price for one page of first-class mail. The price from
# a balance is lower; preview_letter returns both (amount_cents and
# pay_per_letter_cents).

# Retry the identical request with a token for the quoted amount:
#   "payment_token": "spt_…"
# -> 200 { id, status, receipt_url }

Machine-readable everything

Full tool schemas live in /llms-full.txt and /openapi.json. If a model is reading this page cold, those are the two files it wants.

Stuck? Email hello@mailsnail.dev.