OpenAI Agents SDK + Physical Mail

Two ways in

If you want mail from ChatGPT itself, you don't need the SDK: add https://api.mailsnail.dev/mcp as a connector and sign in. See Send a letter from ChatGPT.

For a headless agent built on the Agents SDK, there's no person around to click a sign-in page, so run the open-source server yourself against your own Click2Mail or Lob account. Your provider bills you directly.

Wire-up (self-hosted)

from agents import Agent, MCPServerStdio

mail = MCPServerStdio(
    name="mailsnail",
    params={
        "command": "npx",
        "args": ["-y", "mailsnail"],
        "env": {
            "MAIL_PROVIDER": "click2mail",
            "CLICK2MAIL_USERNAME": "your-username",
            "CLICK2MAIL_PASSWORD": "your-password",
        },
    },
)

agent = Agent(
    name="Mailer",
    instructions="You can send physical mail via the Mailsnail MCP server.",
    mcp_servers=[mail],
)

That's it — the agent now has the mail tools available alongside whatever else it can do.

A practical example

A classic loop: a CRM webhook fires when a deal closes, the agent drafts a personalized thank-you letter to the buyer, and send_letter puts it in the mail. The whole sequence is one tool-using turn for the agent.

response = await agent.run(
    "A new deal closed: contact_id=c_42. Mail them a thank-you note."
)

The agent fetches the contact, drafts a letter, and calls send_letter. You get back an id it can poll later via get_letter.

Gotchas

• The server runs over stdio via npx, so Node.js 18+ must be installed wherever your agent process runs.
• By default the server is in dry-run mode and won't actually mail anything — set MAIL_MCP_ALLOW_LIVE=1 (and a spend cap) when you're ready to print.
• The agent SDK's tool-use loop occasionally retries. Make sure your prompts make it obvious that one piece per request is the intended behavior.

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

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