shipmail

Email for AI agents

Shipmail is email an AI agent can actually operate. Through the MCP server or the REST API, an agent gets a real mailbox on your domain that it can send from, read, and reply to. This guide shows both paths, from a no-code MCP setup to driving everything from your own code.

Last updated

1. Create a Shipmail API key

  1. Sign up at shipmail.to and add your domain (or use a domain you already own).
  2. Go to Settings, then API Keys, and create a key. It looks like sm_live_...
  3. Give the key only the scopes the agent needs (for example mailboxes and messages).

2. Pick how the agent connects

  1. MCP server: the fastest path for chat agents like Claude Desktop, Cursor, or Windsurf. No code.
  2. REST API, CLI, or SDK: for agents and apps you build yourself in TypeScript or Python.
  3. Both use the same API key and the same account, so you can mix them.

3. Give the agent an inbox

  1. Create a mailbox on your domain, like agent@yourdomain.com.
  2. The agent can now send mail, read its inbox, and reply, all through the API or MCP tools.
  3. Add a webhook if you want the agent to be notified the moment new mail arrives.

Examples

Connect the MCP server (Claude Desktop, Cursor, Windsurf)

{
  "mcpServers": {
    "shipmail": {
      "command": "npx",
      "args": ["-y", "shipmail-mcp"],
      "env": { "SHIPMAIL_API_KEY": "sm_live_..." }
    }
  }
}

Create a mailbox for the agent (TypeScript SDK)

import Shipmail from "shipmail";

const client = new Shipmail("sm_live_...");

await client.mailboxes.create({
  domain: "yourdomain.com",
  localPart: "agent",
});

Send mail from the agent (cURL)

curl -X POST https://shipmail.to/api/v1/messages \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "agent@yourdomain.com",
    "to": ["customer@example.com"],
    "subject": "Following up",
    "text": "Thanks for reaching out. Here is what you asked for."
  }'

Get notified when mail arrives (webhook)

await client.webhooks.create({
  url: "https://your-agent.example.com/inbound",
  events: ["message.received"],
});

Key concepts

MCP vs the API

The MCP server wraps the Shipmail API as agent tools, so an MCP client can manage email without writing code. The REST API, CLI, and SDKs are for software you build yourself. Same account, same key.

What the agent can do

Create and manage domains and mailboxes, send mail, read an inbox, reply in a thread, manage webhooks, and handle suppressions. Each capability is a tool the agent can call.

Guardrails

Scope each API key to only what the agent needs. The MCP server also caps risky actions per session, like sends, replies, and deletes, so a misbehaving agent cannot fire off mail in a loop.

Inbound mail

Agents can poll the inbox, or you can register a webhook for message.received so the agent reacts the moment new mail lands instead of polling.

Frequently asked questions

Do I need to be a developer to use this?

Not for the MCP path. If you use Claude Desktop, Cursor, or another MCP client, you paste a small config with your API key and the agent can manage email right away. The API and SDKs are there if you want to build something custom.

Which AI agents can connect?

Any MCP-compatible client, including Claude Desktop, Cursor, and Windsurf, can use the Shipmail MCP server. Any agent or app that can make HTTP requests can use the REST API directly.

Can the agent both send and receive email?

Yes. A mailbox is a real inbox on your domain. The agent can send mail, read what comes in, and reply in the same thread, all through the API or MCP tools.

How do I stop an agent from sending too much mail?

Scope the API key to the minimum it needs, and rely on the MCP server's per-session caps on sends, replies, and deletes. Your plan's daily sending limits also apply, so a runaway agent cannot exceed them.

Is this different from a transactional email API?

Yes. Shipmail gives the agent a full mailbox it owns, not just an outbound send endpoint. It can receive, read, and reply, which is what an agent handling real conversations needs.