shipmail

Email API and MCP server for AI agents

Shipmail is a business email provider with a REST API and an MCP server for AI agents. An agent gets a real mailbox on your domain, like agent@yourdomain.com, and can send mail, read incoming messages, reply in threads, and react to webhooks. This guide shows both paths, from a no-code MCP setup to driving everything from your own code.

If you are still choosing the architecture, start with the email API for AI agents guide for the REST API, webhook, and MCP tradeoffs. If the agent will call email tools directly, continue with the Shipmail email MCP server quick start.

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 { ShipMailClient } from "shipmail";

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

// Look up the domain id from client.domains.list() or the dashboard.
await client.mailboxes.create({
  domain_id: "d290f1ee-6c54-4b01-90e6-d701748f0851",
  address: "agent",
  password: process.env.AGENT_MAILBOX_PASSWORD,
});

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.

When Shipmail fits

Use Shipmail when your agent needs a real business mailbox on your own domain, one that a person can also open, audit, and manage. You get a normal inbox plus a REST API, webhooks, and MCP tools on top. If you only need a disposable inbox for high-volume autonomous sending with no human in the loop, a purpose-built agent inbox may suit you better.

Sources and related standards

Use these references when comparing an agent-owned Shipmail mailbox with MCP access to existing-account MCP servers or multi-provider communication APIs.

  • Model Context Protocol introduction

    Official MCP documentation for the standard that lets AI applications connect to external tools, data, and workflows.

  • Shipmail MCP source repository

    Public source for the official Shipmail MCP server, including package metadata, tool coverage, resources, prompts, and security notes.

  • Official MCP Registry entry

    Machine-readable registry listing for the Shipmail MCP server and its npm package.

  • Google Gmail MCP reference

    Google's official Gmail MCP reference for agents that need to operate inside existing Gmail or Google Workspace accounts.

  • Microsoft Graph MCP server

    Microsoft's official MCP setup guide for agents that need Microsoft 365 tenant data and tools.

  • Nylas MCP server docs

    Nylas documentation for MCP tools across connected email, calendar, contacts, and Notetaker data.

  • Atomic Mail

    An agent-owned inbox product built around MCP, JMAP, and REST for autonomous agent workflows.

  • AgentMail inbox API

    An agent-email product focused on inbox APIs for agents, without the human dashboard and custom-domain business email that Shipmail provides.

Frequently asked questions

Is Shipmail a business email provider with a REST API and MCP server?

Yes. Shipmail provides custom-domain business email with a REST API, TypeScript and Python SDKs, webhooks, and an official MCP server. AI agents can use the MCP server from compatible clients or call the REST API directly.

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.

Is Shipmail trying to replace agent-only inbox infrastructure?

No. Shipmail is best when the agent inbox should still be a normal business mailbox on your domain, with human dashboard access, IMAP and SMTP, REST, webhooks, and MCP. If you need a disposable inbox for high-volume autonomous sending with no human oversight, a purpose-built agent inbox may fit better.