Sendmux Email MCP

MCP

Connect AI tools to Sendmux documentation and product tools.

Sendmux has two MCP connections. Use Doc Search MCP when you want an AI tool to search Sendmux docs. Use MCP when you want an agent to work with Sendmux tools you authorise.

Connection	Use it for	Server
Doc Search MCP	Search Sendmux guides and API references.	https://sendmux.ai/docs/mcp
MCP	Use Management, Mailbox, and Sending tools.	https://mcp.sendmux.ai/mcp or the local sendmux-mcp package

[!NOTE]

MCP exposes a curated agent toolset, not every API endpoint. Use the SDKs, CLI, or API reference when you need full endpoint coverage.

Doc Search MCP

Doc Search MCP exposes search_sendmux.

[accordion] Claude Code

claude mcp add sendmux-docs --transport http https://sendmux.ai/docs/mcp

[accordion] Cursor

Add this server to .cursor/mcp.json for one project or ~/.cursor/mcp.json for all projects.

{
  "mcpServers": {
    "sendmux-docs": {
      "url": "https://sendmux.ai/docs/mcp"
    }
  }
}

[accordion] VS Code

Add this server to your user or workspace mcp.json.

{
  "servers": {
    "sendmux-docs": {
      "type": "http",
      "url": "https://sendmux.ai/docs/mcp"
    }
  }
}

[accordion] Codex

Add this server to ~/.codex/config.toml or a trusted project .codex/config.toml.

[mcp_servers.sendmux_docs]
url = "https://sendmux.ai/docs/mcp"

MCP

MCP exposes the product surfaces you grant.

Surface	Use it for	Access
Mailbox	Search, read, organise, and send from granted mailboxes.	Hosted grant with Mailbox access, an smx_mbx_ key, or a scoped smx_agent_ token locally
Management	Manage team resources such as domains, mailboxes, sending accounts, logs, metrics, billing, and webhooks.	Hosted grant with Management access, or an smx_root_ key locally
Sending	Send single or batch emails.	Hosted grant with Sending access, an smx_mbx_ key, or an owner-approved Sending-resource smx_agent_ token locally

Hosted MCP is the default when your client supports remote MCP with browser OAuth. It keeps Sendmux in the authorisation flow, avoids distributing manual API keys to agents, and shows only the tools allowed by the grant.

[!NOTE]

PyPI package: sendmux-mcp

PyPI version: 2.1.3

npm package: sendmux-mcp

npm version: 1.0.0

Registry metadata version: 2.1.4

Hosted resource: https://mcp.sendmux.ai/mcp

Hosted transport: Streamable HTTP

Curated tool count: 54

Certified protocol versions: 2025-11-25, 2026-07-28

Runtime-accepted protocol versions: 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25, 2026-07-28. Runtime acceptance provides compatibility; it does not certify each version.

Setting	Value
Server URL	https://mcp.sendmux.ai/mcp
Authorisation server	https://app.sendmux.ai
Health check	https://mcp.sendmux.ai/health

Use the Postman collection when you want to test MCP requests from Postman:

When you connect, Sendmux asks you to choose a team, product surfaces, and mailbox access where relevant. Access tokens are short-lived. Refresh tokens rotate on use and can last up to 30 days unless the connection is disconnected or expires.

[!NOTE]

If you grant more than one mailbox, start mailbox workflows with mailbox_list_granted_mailboxes and pass the returned mailbox_id to tools that act on one mailbox.

Connection modes

[card] Hosted OAuth

Use when your client can open a browser-based MCP OAuth flow.

[card] Local stdio

Use when your coding agent can launch a local command on your machine.

[card] Private HTTP

Use when a client needs a URL but you run the MCP package yourself.

npm bridge

Requires Node.js 22 or later. Run the npm bridge:

npx -y sendmux-mcp

The bridge connects stdio clients to the hosted server through browser OAuth. Tools follow your hosted grant.

{
  "mcpServers": {
    "sendmux": {
      "command": "npx",
      "args": ["-y", "sendmux-mcp"]
    }
  }
}

Local package

Install the local package from PyPI:

pip install sendmux-mcp

Run one surface:

SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-mailbox
SENDMUX_API_KEY=smx_root_... sendmux-mcp-management
SENDMUX_API_KEY=smx_mbx_... sendmux-mcp-sending

Run all product surfaces:

SENDMUX_MCP_SURFACES=mailbox,management,sending \
SENDMUX_MAILBOX_API_KEY=smx_mbx_... \
SENDMUX_MANAGEMENT_API_KEY=smx_root_... \
SENDMUX_SENDING_API_KEY=smx_mbx_... \
sendmux-mcp

The server validates key prefixes before starting. Management requires smx_root_. Sending accepts a send-capable smx_mbx_ key or owner-approved Sending-resource smx_agent_ token. Mailbox accepts an smx_mbx_ key or a scoped smx_agent_ token.

Private HTTP

HTTP mode is useful when your MCP client connects to a server URL but you still want to run the package yourself.

SENDMUX_API_KEY=smx_mbx_... \
SENDMUX_MCP_HTTP_BEARER_TOKEN=local-mcp-token \
sendmux-mcp-mailbox --transport http --host 127.0.0.1 --port 8765

The endpoint defaults to /mcp. /health returns the selected surfaces. HTTP mode requires SENDMUX_MCP_HTTP_BEARER_TOKEN unless you explicitly start it with --allow-unauthenticated-http.

Configuration reference

[accordion] Environment variables

Setting	Environment	Default
Tool surfaces	SENDMUX_MCP_SURFACES	Required for sendmux-mcp
API key fallback	SENDMUX_API_KEY	None
Mailbox API key	SENDMUX_MAILBOX_API_KEY	None
Management API key	SENDMUX_MANAGEMENT_API_KEY	None
Sending API key	SENDMUX_SENDING_API_KEY	None
Management and Mailbox API base URL	SENDMUX_APP_BASE_URL	https://app.sendmux.ai/api/v1
Sending API base URL	SENDMUX_SENDING_BASE_URL	https://smtp.sendmux.ai/api/v1
Retry time budget, in seconds	SENDMUX_MCP_RETRY_MAX_ELAPSED_SECONDS	Unset
Transport	SENDMUX_MCP_TRANSPORT	stdio
HTTP host	SENDMUX_MCP_HOST	127.0.0.1
HTTP port	SENDMUX_MCP_PORT	8765
HTTP path	SENDMUX_MCP_PATH	/mcp
HTTP bearer token	SENDMUX_MCP_HTTP_BEARER_TOKEN	Required for HTTP
Allowed browser origins	SENDMUX_MCP_ALLOWED_ORIGINS	No browser origins

[accordion] Protected environment input

SENDMUX_MCP_SURFACES=mailbox,management,sending \
SENDMUX_MAILBOX_API_KEY="$SENDMUX_MAILBOX_KEY" \
SENDMUX_MANAGEMENT_API_KEY="$SENDMUX_ROOT_KEY" \
SENDMUX_SENDING_API_KEY="$SENDMUX_SENDING_KEY" \
sendmux-mcp

Tool discovery

[accordion] How tool discovery works

Tool names are generated from the current public API surfaces. Open your MCP client's tool picker after authorisation to see the tools available to that connection.

Hosted connections show only the tools allowed by the selected product surfaces, permissions, and mailbox grant. Local servers show the tools for the surfaces and keys you provide at startup.

Troubleshooting

[accordion] No tools appear

Confirm the selected product surfaces and granted permissions. Hosted connections show only tools allowed by the grant.

[accordion] Local server fails before starting

Check the API key prefix. Management needs smx_root_; Sending accepts smx_mbx_ or owner-approved Sending-resource smx_agent_; Mailbox accepts smx_mbx_ or scoped smx_agent_.

[accordion] HTTP server returns 401

Send Authorization: Bearer <SENDMUX_MCP_HTTP_BEARER_TOKEN> to private HTTP, or complete OAuth for hosted MCP.

[accordion] HTTP server returns 403 origin_forbidden

Add the browser client's origin to SENDMUX_MCP_ALLOWED_ORIGINS for private HTTP.

[accordion] Too many tools in one client

Connect only the surfaces you need, or disable unused tools in the client.

Next steps

[card] A2A

Use Sendmux through an A2A 1.0 agent endpoint with hosted OAuth.

[card] MCP clients

Configure Sendmux MCP in Claude Code, Cursor, Codex, Gemini CLI, Qwen Code, Zed, and more.

[card] SDKs

Use package-managed clients from application code.

[card] CLI

Install the CLI with Snap, Homebrew, or npm when you need terminal access.

[card] API keys

Create scoped credentials for local MCP setups.

This documentation is built and hosted on Mintlify, a developer documentation platform.