Connect Mailsnail to your agent

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 address above is the same everywhere. Where to paste it:

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

code --add-mcp '{"name":"mailsnail","type":"http","url":"https://api.mailsnail.dev/mcp"}'

codex mcp add mailsnail --url https://api.mailsnail.dev/mcp
codex mcp login mailsnail

Any other app that takes a JSON config uses the url form, and so does Cursor if you would rather add it by hand:

{
  "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.”

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

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 }