Mailsnail

io.github.iancollins27Published by GitHub account iancollins27v0.6.1Updated Nov 7, 2026

Send USPS letters & certified mail from any agent. Hosted: sign in, no install.

VerifiedStreamable HTTPWeb executableProductivity & WorkflowBusiness & Commerce

Overview

AI-generated overview

Lets an assistant verify addresses, preview proofs and send real USPS letters, certified mail and postcards, hosted or self-hosted.

What you can do
  • Verify addresses and preview letters with a proof PDF and exact price before sending
  • Send letters, certified letters and postcards, then track, list or cancel them
  • Check account balance and top up funds for hosted sending
  • Run diagnostics on connectivity and provider configuration
  • Choose between a hosted service, your own Click2Mail or Lob account, or a self-hosted gateway with failover
When to use it
Use it when an assistant needs to put physical paper in a US mailbox — routine correspondence, or certified letters such as legal notices that must be sent and tracked. The hosted connector suits people who want no install and no provider account.
Requirements
Either the remote endpoint with an OAuth sign-in, or the npm package run locally with Node.js. Self-hosting needs MAIL_PROVIDER plus provider credentials: CLICK2MAIL_USERNAME and CLICK2MAIL_PASSWORD, or LOB_API_KEY; managed mode needs MAIL_API_BASE_URL. Network access to the provider or gateway host is required.
Before you install
Sending spends real money: hosted mode charges per letter by card or from a balance, and BYOK modes bill your provider account. Live mail requires MAIL_MCP_ALLOW_LIVE=1; keep the default dry-run and set MAIL_MCP_SPEND_CAP_USD. Provider secrets are passed as environment variables. Sends are irreversible once in production, and USPS rules and provider terms apply.

Installation

In SourceWeft

  1. Open Mailsnail in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.iancollins27%2Fmailsnail/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

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

README

[Mailsnail]

Mailsnail

[smoke]

Open-source, provider-agnostic physical mail for AI agents.

Agents have every channel except one. They can email, text, call, and post to every feed — but until now, putting a real, postmarked envelope in a mailbox meant a human signing up for a print-provider account, provisioning API keys, and wiring billing. Mailsnail closes that gap:

  • Nothing to install. Add one URL to Claude, ChatGPT, Cursor or any MCP client and sign in. Pay for one letter by card or fund a balance, priced at our cost: from $1.21 first-class and $8.61 certified, no subscription. Agents that can mint a Stripe Shared Payment Token can also pay per piece with no account, over the Machine Payments Protocol (HTTP 402).
  • No lock-in, ever. The provider layer is open and swappable: bring your own Click2Mail or Lob account, self-host the whole gateway, or chain providers for failover. The managed service is a convenience, not a cage.
  • Built for compliance mail. Certified letters with extra_service: "certified" — the mail that legally must be physical (preliminary lien notices, legal notices) and must not miss its deadline because one print API had a bad day.
bash
claude mcp add -t http mailsnail https://api.mailsnail.dev/mcp# then /mcp → mailsnail → Authenticate, and: "Mail a thank-you letter to my aunt."

In Claude Desktop or ChatGPT, add https://api.mailsnail.dev/mcp as a custom connector. Steps for every app: mailsnail.dev/setup. Running your own Click2Mail or Lob account instead? See Ways to run it.

Hosted connector and plugins

The quickest start needs no install. Add https://api.mailsnail.dev/mcp as a custom connector in Claude, ChatGPT, Cursor or any MCP client that supports remote servers, then sign in. Each app's setup steps are at mailsnail.dev/setup.

plugins/mailsnail packages that connector with skills for sending letters, sending certified mail and tracking mail. It works in Claude (chat, Cowork and Claude Code) and in Cursor. To install it in Claude Code:

text
/plugin marketplace add iancollins27/mailsnail/plugin install mailsnail@mailsnail

Packages

PackageWhat it is
mailsnailMCP server — 11 tools (doctor, verify_address, preview_letter, send_letter, send_postcard, get_balance, top_up, get_letter, get_postcard, list_letters, cancel_letter) over any provider below. Works in Claude Code, Claude Desktop, Cursor, Codex CLI, OpenAI Agents SDK.
@mailsnail/coreProvider-agnostic core: adapters (Click2Mail, Lob, any Mailsnail gateway), multi-provider failover router, request validation. Zero dependencies.
@mailsnail/gatewaySelf-hostable REST API: BYO provider credentials, body_text→PDF rendering, proofs, invocation logging. The managed service at api.mailsnail.dev runs the same wire protocol.
spec/The provider-neutral mail-piece schema + the failover-safety contract. Implement it and anything — including a print shop — becomes a Mailsnail-compatible node.

Ways to run it

ModeCredentialsPayingGood for
hosted connector (api.mailsnail.dev/mcp)none; you sign inyou, per letter by card or from a balancepeople in Claude, ChatGPT, Cursor; zero-setup
managed (stdio default)noneagent, per piece (Stripe SPT)agents that can mint an SPT
gatewayyour own, on your serveryour provider accountteams; PII stays in your infra
click2mail / lob (BYOK)yours, local envyour provider accountdirect control, one provider
failover chainyours, per provideryour provider accountsmail that must not miss deadlines

Failover is deliberately conservative: a send moves to the next provider only when the failed provider guarantees nothing entered production and no money moved (safeToRetry — see the spec). A duplicate certified letter is worse than an error.

Running behind an egress proxy or allowlist

Sandboxed agents — CI runners, enterprise agent platforms, hosted agent sessions — usually sit behind an egress allowlist, and that is the environment managed mode is for. Two minutes of setup:

bash
npx mailsnail doctor      # says exactly what it can and can't reach, and why. Free; never mails.

Allow this host:

ModeHost to permitPort
managed (default)api.mailsnail.dev443 (TCP / HTTPS CONNECT)
self-hosted gatewaywhatever MAIL_API_BASE_URL points atits port
click2mail (BYOK)rest.click2mail.com443
lob (BYOK)api.lob.com443

Allowlist by hostname, not IP: the managed gateway runs on managed infrastructure and its addresses change without notice. If your policy is IP-only, self-host @mailsnail/gateway on an address you control — that escape hatch is the whole point of the open provider layer.

Through an HTTP proxy. Node's fetch ignores HTTPS_PROXY unless you tell it not to, so an allowlisted gateway can still time out silently. Either:

bash
export NODE_USE_ENV_PROXY=1        # Node >= 22.21export HTTPS_PROXY=http://proxy.example:8080

or install undici alongside mailsnail (npm i undici) and Mailsnail routes through HTTPS_PROXY/HTTP_PROXY/ALL_PROXY itself, honoring NO_PROXY. mailsnail doctor tells you which of these is actually in effect.

TLS-inspecting proxy? Point NODE_EXTRA_CA_CERTS at your organization's CA bundle.

When it's blocked anyway, the failure says so instead of guessing: transport errors carry a code of unreachable, egress_blocked, or tls_untrusted, plus the exact host:port to permit. Any of those codes means the request never reached the backend — nothing mailed, nothing was charged, and the fix is network policy, not your account.

Safety

  • Dry-run by default everywhere; live mail requires an explicit MAIL_MCP_ALLOW_LIVE=1.
  • Per-session spend caps in the MCP server; auto-refund in managed mode when a paid piece fails to mail.
  • preview_letter returns a proof PDF and exact price before anything is charged — show it to your user first.
  • Don't use this for spam, harassment, or fraud. Provider terms and USPS regulations apply; managed mode enforces its own abuse screening.

Why open source

You're letting software put paper in mailboxes and spend money doing it. Read the code. Run it yourself with your own provider account for free. Use managed mode when you'd rather not hold credentials at all. If we ever disappoint you, MAIL_PROVIDER=click2mail and your mail keeps moving — that's the deal, and it's enforceable because this repo exists.

Status

Early. US-only today. Letters, certified letters, and postcards. The managed API, MCP server, self-host gateway, and Click2Mail/Lob adapters are live; additional adapters (PostGrid, Stannp) are next — CONTRIBUTING.md has the adapter guide if you want one sooner.

License

MIT.

Source: README.md at commit 6367d26

Tools

0
This server asks you to sign in, so SourceWeft could not read its tools without an account and has not indexed them. What a connected account sees can depend on that account and its permissions.

Version history

2
  1. v0.6.1LatestNov 7, 2026
  2. v0.6.0Sep 16, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts