Mermail

MCP

Connect AI assistants to Mermail over Streamable HTTP MCP with OAuth or an API key.

Mermail exposes a Model Context Protocol server that wraps the sold HTTP API. Assistants call the same workspace-scoped endpoints as authenticated clients — including usage, workspaces, mailboxes, email, agent conversations, and task triage.

Endpoint

Item	Value
URL	https://console.mermail.app/mcp
Transport	Streamable HTTP (JSON-RPC over POST)
Auth	OAuth 2.1 Bearer (interactive) or x-api-key: sk-proj-… (automation)
Methods	POST only — GET / DELETE return 405

The server is stateless: there is no SSE subscription. Clients that expect long-lived SSE should use a Streamable HTTP–capable MCP host instead.

Authentication

OAuth (browser-parity)

MCP clients that support OAuth discover Mermail via Protected Resource Metadata, open the console authorize page, and receive a Bearer access token after the user signs in with Enoki (same as the web app) and picks a workspace.

Item	Value
PRM	https://console.mermail.app/.well-known/oauth-protected-resource
AS metadata	https://console.mermail.app/.well-known/oauth-authorization-server
Scopes	mcp:tools, openid, offline_access

Unauthenticated calls return 401 with a WWW-Authenticate challenge pointing at the PRM document.

API key (automation / CLI)

1. Create a workspace API key in Settings → API Keys. See Authentication.
2. Send it on every MCP POST as x-api-key.
3. Cookie / console sessions alone are rejected for MCP.

Both auth modes scope tools to one workspace and consume that workspace’s RPM and API credits.

Discover the server

curl -sS https://console.mermail.app/.well-known/mcp/server-card.json | jq .

Official MCP Registry

Mermail is published as app.mermail/mcp on the Official MCP Registry. Clients and aggregators (PulseMCP, Smithery, Glama, and others) discover remote Streamable HTTP servers from that feed.

Item	Value
Registry name	app.mermail/mcp
Website	mermail.app/agents
Ownership proof	https://mermail.app/.well-known/mcp-registry-auth

The card includes OAuth and API-key authentication options, Streamable HTTP transport, and the full tool list.

Prefer the URL and tool list from the live server card for your host. Do not hardcode a host if you deploy to a custom domain.

Connect an assistant

OAuth-capable hosts should connect to https://console.mermail.app/mcp and complete the browser consent flow (no API key in config).

API-key hosts use Streamable HTTP + header auth:

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

Exact config keys differ by host (Cursor, Claude Code, Codex, custom MCP clients). The important parts are the /mcp URL and Streamable HTTP (not SSE).

For packaged workflows, install Mermail Skills (npx skills add Nudgen-Marketing/mermail-skills) or connect via the registry id app.mermail/mcp when your host supports Official Registry install.

How tools map to the API

Each tool (except prepare_destructive_action) maps to one sold API operation:

Argument	Use
Path params	Top-level strings (mailboxId, workspaceId, …) matching the OpenAPI path
query	Optional object of query-string values
body	Optional JSON body for POST / PUT / PATCH
idempotencyKey	Optional; sent as Idempotency-Key
confirmationToken	Required on destructive tools (see below)

Server instructions: prefer read-only tools before writes. Responses are JSON text plus object-shaped structuredContent. JSON arrays are exposed as { "items": [...] } so the result conforms to the MCP schema. Binary payloads (for example attachments) are capped at 1 MiB; larger downloads should use the REST attachment endpoint.

Destructive actions

Destructive tools (delete workspace/member/domain/email/folder/label/conversation/triager, bulk delete, empty trash, …) require a short-lived confirmation token:

1. Call prepare_destructive_action with:
   • action — the destructive tool name
   • arguments — the same arguments you will pass to that tool (without confirmationToken)
2. Receive { confirmationToken, expiresInSeconds } (token prefix mcp_confirm_, TTL 5 minutes, single-use, Redis-backed).
3. Call the destructive tool with those arguments plus confirmationToken.

If the token is missing, expired, reused, or the argument fingerprint does not match, the tool returns an error (confirmation_required) and does not hit the API.

Confirmations require Redis. If Redis / cache is disabled, `prepare_destructive_action` fails with `503` `confirmation_unavailable`.

Tool catalog

The live server exposes 63 tools: prepare_destructive_action + 62 API wrappers. Grouped by area:

`get_api_credit_usage`, `get_email_usage` `list_workspaces`, `get_workspace`, `update_workspace`, `delete_workspace`, `get_workspace_storage`, `list_workspace_members`, `update_member_role`, `remove_workspace_member`, `invite_workspace_member`, `resend_workspace_invite` `list_email_domains`, `add_email_domain`, `delete_email_domain`, `verify_email_domain`

These hit Developer-gated REST paths. Free workspaces receive `403` when the tool runs.

`list_workspace_mailboxes`, `list_mailboxes`, `create_mailbox`, `get_mailbox`, `update_mailbox_settings`, `get_mailbox_storage` `list_emails`, `send_email`, `get_email`, `update_email`, `delete_email`, `bulk_delete_emails`, `bulk_mark_emails_read`, `bulk_move_emails`, `move_email`, `reply_to_email`, `forward_email`, `download_attachment`, `save_draft`, `regenerate_draft`, `schedule_email_send`, `empty_trash`, `get_thread`, `mark_thread_read`, `list_folders`, `create_folder`, `update_folder`, `delete_folder`, `search_emails`, `list_custom_labels`, `create_custom_label`, `update_custom_label`, `delete_custom_label` `list_agent_conversations`, `create_agent_conversation`, `rename_agent_conversation`, `delete_agent_conversation`, `list_agent_messages`, `chat_with_mailbox_agent`, `list_task_triagers`, `create_task_triager`, `list_recent_triager_runs`, `update_task_triager`, `delete_task_triager`, `set_default_task_triager`, `get_or_create_triager_conversation` `prepare_destructive_action` — issues confirmation tokens for destructive tools

Open-world tools (outbound email / invites / agent chat) are annotated openWorldHint for MCP clients that surface that signal.

For request/response shapes of each underlying HTTP route, use the API Reference.

Related

Install Mermail workflows in Codex, Claude Code, and Cursor. Create and use `sk-proj-` API keys. Public discovery URLs including the MCP server card.