How to Use MCP with Mermail's Email API

Point Cursor, Claude, or Codex at Mermail’s hosted MCP server, authenticate with OAuth 2.1 or an API key, then let the agent call typed tools to create a mailbox, list mail, and read threads — without wiring SMTP yourself.

How to use MCP with Mermail’s email API

Mermail hosts a Streamable HTTP MCP server that wraps the same Sold API your apps already call. The client discovers tools at runtime; the agent never sees SMTP credentials. For mailbox-first verification and provisioning, use the agent-inbox profile. For send, drafts, and the full catalog, use the default endpoint. Looking for a personal Gmail bridge instead? See Should you connect Grok Bot to Gmail? — agents need their own address.

Prerequisites

• A Mermail account with at least one workspace
• An MCP-capable client: Cursor, Claude Code / Claude Desktop, Codex, or another Streamable HTTP host
• OAuth 2.1 (interactive) or a workspace API key (sk-proj-…) from Settings → API Keys

Endpoint and auth

Default full-catalog URL: https://console.mermail.app/mcp. Recommended agent-inbox URL: https://console.mermail.app/mcp?profile=agent-inbox. Transport is Streamable HTTP (JSON-RPC over POST). Auth is OAuth 2.1 Bearer or x-api-key: sk-proj-….

Install in Claude Code, Cursor, and Codex

# Claude Code — full catalog
claude mcp add --transport http mermail https://console.mermail.app/mcp

# Claude Code — agent-inbox (no send)
claude mcp add --transport http mermail-inbox https://console.mermail.app/mcp?profile=agent-inbox

# Codex
codex mcp add mermail --url https://console.mermail.app/mcp
codex mcp login mermail

{
  "mcpServers": {
    "mermail": {
      "url": "https://console.mermail.app/mcp",
      "headers": { "x-api-key": "sk-proj-YOUR_KEY" }
    },
    "mermail-agent-inbox": {
      "url": "https://console.mermail.app/mcp?profile=agent-inbox",
      "headers": { "x-api-key": "sk-proj-YOUR_KEY" }
    }
  }
}

Tools: full catalog vs agent-inbox

The default /mcp endpoint exposes Sold API wrappers — mailboxes, emails, drafts, domains, workspaces, triage, and more. Verify tool names from tools/list. See the MCP tool catalog.

The agent-inbox profile is a 12-tool allowlist for mailbox-first workflows. It exposes one provisioning write plus safe reads — and it does not expose send:

get_api_credit_usage
list_workspaces
get_workspace
list_email_domains
list_workspace_mailboxes
list_mailboxes
create_mailbox
get_mailbox
list_emails
search_emails
get_email
get_email_context

First loop: create_mailbox → list_emails → get_email

After install, give the agent one prompt. Prefer create_mailbox on a disposable username, then read mail with list_emails / search_emails. Patterns: agent email inbox guide.

Using Mermail MCP (agent-inbox profile):
1. Call create_mailbox with a disposable username and display name.
2. Call list_mailboxes and confirm receiving readiness.
3. Call list_emails on that mailbox (metadata-only is fine).
4. Call get_email on a specific id when you need the body.
Print mailbox ids and email ids as you go.

• create_mailbox provisions an address on the Mermail-hosted domain (or a verified custom domain on Developer+). A successful create consumes provision credits from the workspace API balance — usage units, not a dollar charge.
• list_emails / search_emails return messages. On agent-inbox, Mermail forces metadata-only + clean-scan + agent-safe projections.

When another email MCP fits instead

Mermail fills the inbox-first lane. Use a send-platform MCP when the agent should operate campaigns; use Gmail MCP when the mailbox already belongs to a human.

Limitations

The agent-inbox profile does not expose send, domain create/verify writes beyond list, webhook CRUD, or wallet tools. Domain add/verify tools live on the full catalog and require Developer+.

Ready to put those mailboxes on your own domain? Continue with Custom Domains for Thousands of Agent Inboxes.

FAQ

How do I use MCP with Mermail’s email API?

Point Cursor, Claude, or Codex at https://console.mermail.app/mcp (or ?profile=agent-inbox), authenticate with OAuth 2.1 or x-api-key: sk-proj-…, then let the agent call create_mailbox, list_emails, and related tools.

Does the agent-inbox profile send email?

No. It is a 12-tool allowlist for provisioning and safe reads. Connect the default /mcp catalog for send_email and replies.

What keys does Mermail use?

Workspace API keys use the sk-proj- prefix and the x-api-key header.