Connect an agent with MCP
The Shipmail MCP server gives an AI agent its own inbox on your domain, plus the tools to use it. The agent can create mailboxes, send and read mail, reply to threads, set up webhooks, and manage domains. Connect to the hosted Streamable HTTP endpoint at https://shipmail.to/api/mcp or run it locally over stdio. Both authenticate with a scoped Shipmail API key. This page covers connecting. The tool reference and permissions and security have their own pages.
Last updated
Connect in one step
Paste this prompt into an agent that can read the web and run commands, such as Claude Code, Codex, or Cursor. It reads the setup instructions, asks you to approve it in your browser, and connects. You do not copy an API key.
Set up Shipmail for me. Read https://shipmail.to/auth.md and follow it.
In a chat app or an editor, add the hosted server with one click:
Start with the job your agent needs to do
Install the server when the agent works through tools. Open an API guide when your own code runs the workflow.
Hosted remote server
Shipmail hosts the MCP server at https://shipmail.to/api/mcp over Streamable HTTP. Nothing to install or run. Sign in with OAuth (clients that support MCP OAuth discovery connect with the URL alone) or authenticate with a Shipmail API key as a bearer token:
The endpoint speaks MCP 2026-07-28 and still serves clients on 2025-11-25, which is what most MCP hosts ship today. Modern clients get stateless per-request discovery. Older ones are served per request through the legacy initialize handshake, without a server-initiated request path, which no Shipmail tool needs.
Authorization: Bearer sm_live_...Shipmail checks every tool call against the API key the same way it checks a REST call, with the same scopes, resource constraints, plan quotas, and rate limits. Manage OAuth permissions under Developer, Connections. An API-key session gets whatever permissions that key has.
Give a new agent a dedicated mailbox and start with Read and draft. It can read mail and calendars and create drafts, but it cannot send email. A dedicated mailbox alone does not limit an account-approved OAuth connection, so check its granted resources. Review the permission and security guidance before granting broader access.
ChatGPT
In ChatGPT Plugins, select the plus button, then Add custom MCP server, with the server URL https://shipmail.to/api/mcp. Choose OAuth and sign in to Shipmail, where you pick the permissions. To have ChatGPT add your domain and mailboxes, pick Set up. Shipmail starts on it when your organization has no domain yet. Grant Send mail if ChatGPT should send. ChatGPT offers OAuth, not an API key. ChatGPT can then read, draft, and send email through your Shipmail mailboxes. See the ChatGPT guide.
When the user asks to send a conversation or library file, Shipmail opens an MCP Apps review card. The card gets a fresh ChatGPT file URL, checks the exact byte size and SHA-256 digest, uploads through a five-minute single-use Shipmail URL, and sends or schedules only after the user presses the action button. The component never receives the Shipmail connection credential.
ChatGPT automations can also start on their own when new mail arrives or a send bounces. See events and automations.
Claude Code
claude mcp add --transport http shipmail https://shipmail.to/api/mcp \
--header "Authorization: Bearer sm_live_..."The Claude guide covers Claude Code, Claude Desktop and claude.ai.
Gemini CLI
gemini extensions install https://github.com/shipmail-to/shipmail-mcpThe extension adds the hosted server and the Shipmail skill. Run /mcp auth shipmail in Gemini CLI to open the Shipmail sign-in page and choose what Gemini may do.
Cursor, VS Code, or Windsurf
{
"mcpServers": {
"shipmail": {
"url": "https://shipmail.to/api/mcp",
"headers": {
"Authorization": "Bearer sm_live_..."
}
}
}
}Cursor steps, including OAuth sign-in, are in the Cursor guide.
Claude web and mobile
Add a custom connector on claude.ai with the URL https://shipmail.to/api/mcp and no further configuration. Claude discovers Shipmail's OAuth support, sends you to the Shipmail sign-in page, and connects after you sign in. No API key to copy. A mailbox password can approve Claude for that mailbox only. Choose the member-tier capabilities Claude may use. That connection cannot add another organization or reach another mailbox. Use an account sign-in when you need broader account access. The connection is visible and revocable under Developer, then Connections.
The same OAuth flow works in any MCP client that supports OAuth discovery, ChatGPT connectors included, so you can skip pasting an API key.
Grok and Grok Bot
On grok.com, open Connectors, choose New Connector, then Custom, and enter https://shipmail.to/api/mcp. Grok sends you to the Shipmail sign-in page, and the connection works like the Claude one: same permissions, visible and revocable under Developer, then Connections. Grok Bot uses the same connector, so it can work on your mailboxes once Grok is connected. See the Grok Bot guide.
Dots
Dots works through your ChatGPT apps. Connect Shipmail in ChatGPT as described above, and your Dots can read, draft, and send email, manage your calendar, and run newsletters with the permissions you chose. Dots runs in Work mode, so it can also start on its own when new mail arrives or a send bounces, through events. See the Dots guide.
Muse
In Muse, open Settings, then Connectors, choose Add custom connector, and enter https://shipmail.to/api/mcp. Muse sends you to the Shipmail sign-in page, where you choose what it may do. The connection is visible and revocable under Developer, then Connections. See the Muse guide.
Codex, Hermes Agent, OpenClaw and agent frameworks
These agents add the hosted server with a URL and a bearer header, or start the local one. Each has its own guide with the exact config file: Codex, Hermes Agent, OpenClaw and LangChain. Agent frameworks have their own guides too: CrewAI, Vercel AI SDK and Mastra. To build your own agent on webhooks instead, read receive email in an AI agent.
Install the local server
Add this server to any MCP host that supports stdio servers. Both the current 2026-07-28 protocol and the earlier 2025-11-25 are served.
{
"mcpServers": {
"shipmail": {
"command": "npx",
"args": ["-y", "shipmail-mcp"],
"env": {
"SHIPMAIL_API_KEY": "sm_live_..."
}
}
}
}Create an API key in the Shipmail dashboard. For details, see API authentication.
Client examples
Claude Desktop, Cursor, Windsurf, and other stdio MCP hosts all use the same command. Keep the key in the host environment, not in a prompt. Before startup, the server builds its tool list from what the key is allowed to do.
Claude Desktop
{
"mcpServers": {
"shipmail": {
"command": "npx",
"args": ["-y", "shipmail-mcp"],
"env": {
"SHIPMAIL_API_KEY": "sm_live_..."
}
}
}
}Cursor
{
"mcpServers": {
"shipmail": {
"type": "stdio",
"command": "npx",
"args": ["-y", "shipmail-mcp"],
"env": {
"SHIPMAIL_API_KEY": "sm_live_..."
}
}
}
}Configuration
| Variable | Description |
|---|---|
| SHIPMAIL_API_KEY | Required API key (or use SHIPMAIL_API_KEY_FILE). Give it only the scopes your tools need. |
| SHIPMAIL_API_KEY_FILE | Optional path to a file containing the API key. Takes precedence over SHIPMAIL_API_KEY. Handy with Docker secrets or systemd LoadCredential. |
| SHIPMAIL_BASE_URL | Optional. Defaults to https://shipmail.to/api/v1. Production values must use HTTPS on a shipmail.to host. |
| SHIPMAIL_ALLOW_INSECURE_BASE_URL | Set to 1 only for local development against non-HTTPS or non-shipmail hosts. |
Working with multiple organizations
This section applies to connections approved from an account sign-in. A connection approved with a mailbox password stays with that mailbox, even if the same person is an organization owner. It cannot gain billing, team, or API-key administration.
Choose organizations when you approve
One connection can cover several organizations at once. If you belong to more than one organization, the approval screen lists them and you choose which ones the client may work in. One access profile covers every organization you include. Select Set each organization separately when they need different permissions. People with access to every mailbox can include every mailbox in their organization. Everyone else can include only the mailboxes an Owner or Admin has granted them.
Access follows your real permissions
Shipmail checks your access on every request, so you never re-approve a connection. Mailboxes and domains you add later are included, and a mailbox an Owner or Admin takes away is gone on the next request. The exception is a connection limited to a hand-picked list of mailboxes. That list stays as you set it until you change it.
Add or remove organizations later
After the first connection, add and remove organizations in Developer, Connections. Opening a connection shows every organization it reaches. You can add another organization you belong to, edit one organization's permissions, or remove one. Changes apply on the connection's next request, and you don't reconnect anything in the AI client. Shipmail emails an organization's owners when a connection gains or loses access to it, and they can remove that access from their own Connections page.
Target one organization in a call
When a connection covers more than one organization, organization-targeted tools accept an optional organization_id. Shipmail infers the target when a request already names a mailbox belonging to one of them. If Shipmail can't tell which one you mean, it refuses the call and lists the organizations instead of guessing, so it never reads or sends mail from the wrong one. The status tool reports those organizations by name.
Lists across organizations
Organization-rooted collections also have explicit _across_organizations tools for domains, mailboxes, webhooks, suppressions, newsletters, newsletter domains and assets, audiences, and booking pages. Each call returns one labeled section per organization. A section that fails on permissions or an API error shows the error, and the other sections still come back. Each section pages on its own. Pass each section's next_cursor back under that organization's ID in cursor_by_organization. Lists beneath a specific parent, such as inbox messages for one mailbox or subscribers for one audience, still use the parent ID and target one organization.
Resources
Resources follow the same rule. A resource URI carries no organization_id, so on a connection covering more than one organization shipmail://mailboxes and shipmail://domains return one labeled section per organization instead of a single organization's page. A resource that names an ID, such as shipmail://mailboxes/{id}, is served by the organization that owns it.
One connection per client
Each AI client gets its own connection, so Claude and another client can cover different organizations. Claude does not allow two custom connectors with the same server URL, so use one Shipmail connector there and give it every organization you need.
Check a subscriber list before importing
shipmail_add_subscribers_batch takes up to 1000 subscribers. Its description tells agents to call it first with dry_run: true, which returns each row's outcome without adding anyone, so the agent can fix typos and drop bad rows before the real import.
{
"audience_id": "aud_123",
"subscribers": [{ "email_address": "jane@example.com" }, { "email_address": "alex@gamil.com" }],
"dry_run": true
}A dry run needs the same permission as an add. Each row gets the outcome it would have, and nothing is added, charged or sent. A skipped_invalid row carries a reason code, and a typo carries the corrected address in suggestion. A dry run does not check the subscriber limit, the monthly add quota or the API key's recipient limits.
Conversation IDs
Every tool result that names a conversation carries conversation_id, Shipmail's own identifier. Keep that ID between runs. It survives thread merges and any re-threading the mail server does. thread_id is deprecated. It still works, its value is unchanged, and every tool that takes a thread ID accepts either shape.
MCP, REST API, or webhooks?
- Use MCP when an agent in an MCP-compatible host needs to discover and call email tools.
- Use the REST API when application code owns a repeatable, testable email workflow.
- Use webhooks to trigger work when a message arrives or delivery state changes.
- Many setups use all three. A webhook starts the job, REST runs it, and MCP handles the tasks a person hands to an agent.
For a longer comparison, read the email API for AI agents guide. To set the mailbox up end to end, follow the email for AI agents implementation guide, or start from the API quick start when application code owns the workflow.
How Shipmail compares to other email MCP options
If an agent only needs access to an existing mailbox, suite, or customer-operations layer, Gmail MCP, Microsoft Work IQ MCP, Fastmail MCP, Nylas CLI MCP, MCPEmails, PortEden Email MCP, Zoho Mail MCP, or Front MCP may fit. If the team needs product-email sending through MCP, Resend MCP may fit. If the team wants Germany-hosted email priced per domain with MCP on higher plans, MailRift may fit. If the agent needs an agent-specific communication product, Nylas Agent Accounts, MCPMail, AgentMail, or Robotomail may fit. If the agent needs its own inbox on your domain, with REST API calls and webhook events on the same mailbox, use Shipmail.
| Option | Best fit | Shipmail difference |
|---|---|---|
| Gmail MCPGoogle Gmail MCP server (Developer Preview) | Good when the agent works inside an existing Gmail account and a person sends its drafts. It cannot send. | Shipmail is for creating agent-owned custom-domain mailboxes, not borrowing a human Gmail account. |
| Microsoft Work IQ MCPMicrosoft Work IQ MCP overview (preview) | Good when the agent runs inside Microsoft 365 or Copilot Studio and works on tenant mail and data. | Shipmail is simpler when the agent needs an independent custom-domain mailbox with REST, webhooks, and MCP outside a Microsoft tenant. |
| Fastmail MCPFastmail MCP server help article | Good when the team already uses Fastmail and wants MCP access to that account. | Shipmail adds REST API and webhook workflows around dedicated custom-domain agent inboxes. |
| Nylas Agent AccountsNylas Agent Accounts and MCP docs | Good when the agent needs an owned email and calendar identity inside the Nylas API platform. | Shipmail is simpler when the job is custom-domain business email hosting, shared human access, REST, webhooks, and MCP around the same mailbox. |
| Nylas MCPNylas MCP server docs | Good when the agent should call Nylas tools for connected email, calendar, contacts, and Notetaker data. | Shipmail hosts the mailboxes itself instead of reaching them through Nylas grants. |
| Nylas CLI MCPNylas CLI AI agent email MCP guide | Good when the agent needs MCP access to existing Gmail, Outlook, Exchange, Yahoo, iCloud, or IMAP accounts through Nylas. | Shipmail creates and hosts the agent-owned custom-domain business mailbox instead of bridging into an existing inbox. |
| MCPMailMCPMail email for agents | Good when the agent mostly needs a hosted MCP-first mailbox and a few tools. It documents no public REST API. | Shipmail adds normal business email hosting, REST API, webhooks, IMAP/SMTP, dashboard access, and flat mailbox plans. |
| MailRiftMailRift MCP server docs | Good when the team wants Germany-hosted email priced per domain, with a hosted MCP server and webhooks from the Plus plan and a REST API from Pro. | Shipmail includes the REST API, webhooks, IMAP/SMTP, and MCP on every plan and prices by mailbox count. MailRift lists IMAP/SMTP on Enterprise only. |
| MCPEmailsMCPEmails hosted email MCP | Good when the agent needs a hosted MCP bridge into Gmail, Outlook, iCloud, Fastmail, or IMAP. | Shipmail hosts the business mailbox itself and exposes that mailbox through REST, webhooks, IMAP/SMTP, dashboard access, and MCP. |
| PortEden Email MCPPortEden Email MCP server | Good when the agent needs governed access to an existing Gmail or Outlook account through PortEden. | Shipmail creates and hosts the agent-owned custom-domain mailbox instead of wrapping a connected account. |
| AgentMailAgentMail inbox API | Good for agent-infrastructure teams that want an inbox API specifically for agents. | Shipmail combines normal business email hosting, human inbox access, REST API, webhooks, and MCP. |
| Resend MCPResend MCP server | Good when the agent mostly needs MCP access to Resend sending. | Shipmail is for hosted business mailboxes with REST, webhooks, IMAP/SMTP, human access, and MCP around the same inbox. |
| RobotomailRobotomail email for AI agents | Good for agent products that create one mailbox per agent through an API and a hosted MCP server. | Shipmail mailboxes also work for people, through webmail, IMAP/SMTP, and the dashboard, on a flat business email plan. |
| Zoho Mail MCPZoho Mail MCP server guide | Good when the company already uses Zoho Mail and wants REST or MCP access to those mailboxes. | Shipmail fits when you need new agent mailboxes with REST, webhooks, and an official MCP server. |
| Front MCPFront MCP server docs (beta) | Good when Front is already the shared inbox or customer-operations layer. | Shipmail hosts the email mailbox itself. Front is usually a collaboration layer on top of existing channels. |
Frequently asked questions
Is there a business email provider with a REST API and an MCP server for AI agents?
Yes. Shipmail is a business email provider with both a REST API and the official shipmail-mcp server. AI agents can use Shipmail to create and manage custom-domain mailboxes, send email, read inbound messages, reply to threads, and receive webhook events.
Can an AI agent get its own email inbox with Shipmail?
Yes. A Shipmail mailbox is a real email inbox on your domain. An agent can use it as a dedicated address, send from it, read incoming messages, reply in threads, and let humans review the same mailbox from the dashboard.
When should an agent use the Shipmail MCP server instead of the REST API?
Use the REST API from your own code, webhooks, and backend jobs. Use the MCP server when the agent runs inside an MCP-compatible client such as ChatGPT, Claude, Grok, Cursor, Windsurf, or another host that can discover and call structured tools.
Can ChatGPT connect to Shipmail?
Yes. In ChatGPT Plugins, add a custom MCP server with the URL https://shipmail.to/api/mcp and choose OAuth. Shipmail asks you to choose an exact connection profile and permissions. Grant Send mail when ChatGPT should be able to send.
Can Dots, Muse, or Grok Bot use my Shipmail email?
Yes. All three connect to https://shipmail.to/api/mcp. Dots uses the Shipmail app in ChatGPT, Grok Bot uses the Shipmail connector on grok.com, and in Muse you add it under Settings, Connectors, Add custom connector. Each agent can then answer email, manage your calendar, and run newsletters within the permissions you chose when you signed in.
Does Shipmail have a remote MCP server, or only a local one?
Both. The hosted Streamable HTTP endpoint at https://shipmail.to/api/mcp works with Claude web and mobile, ChatGPT, Dots, Muse, Grok, Grok Bot, Claude Code, Cursor, and VS Code, using OAuth sign-in or bearer API key authentication. The same server also runs locally over stdio via npx shipmail-mcp for hosts like Claude Desktop.
Can Claude on the web connect to Shipmail?
Yes. Add a custom connector on claude.ai pointing at https://shipmail.to/api/mcp. Claude discovers Shipmail's OAuth support and walks you through signing in. A mailbox password can approve access to that mailbox only. Use an account sign-in when you need broader account access. No API key or local install needed.
How is Shipmail different from Gmail MCP, Microsoft Work IQ MCP, Fastmail MCP, Nylas, MCPMail, MCPEmails, or AgentMail?
Gmail MCP, Microsoft Work IQ MCP, Fastmail MCP, Zoho Mail MCP, Nylas CLI MCP, MCPEmails, and PortEden Email MCP are best when an agent works inside an existing account or suite. Resend MCP is stronger for product email sending. Nylas Agent Accounts, MCPMail, AgentMail, and Robotomail are agent-specific communication products. Shipmail is business email hosting with real custom-domain mailboxes, REST API, webhooks, a dashboard for humans, and an MCP server for agents.
Do Zoho Mail and Front have MCP servers?
Yes. Zoho Mail has an official remote MCP server for Zoho-hosted mailboxes, and Front has a hosted MCP server in beta for conversations inside Front. Both work on mailboxes a team already runs there. Shipmail combines custom-domain mailbox hosting, REST API, webhooks, IMAP/SMTP, dashboard access, and the official shipmail-mcp server.