MCP - Mermail

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. The consent UI shows a friendly client name (for example ChatGPT or Cursor), not the opaque mcp_client_… id.

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)

Create a workspace API key in Settings → API Keys. See Authentication.
Send it on every MCP POST as x-api-key.
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 .

The card includes Streamable HTTP transport, OAuth 2.1 and optional API-key authentication, serverInfo.description, icons at https://console.mermail.app/brand/icon-primary.png, and the full tool list.

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, icons/description metadata, 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

Use the interactive guide at mermail.app/agents for host-specific steps.

Host	Auth
Cursor, Claude, ChatGPT	OAuth — connect to `https://console.mermail.app/mcp` and complete browser consent (no API key in config)
Codex, OpenClaw	API key — Streamable HTTP + `x-api-key`

API-key example:

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

Exact config keys differ by host. 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)

Nest Sold API fields under the MCP body argument. If agents pass Sold fields flat at the top level (to, subject, text, …), Mermail folds them into body.

Email write payloads

Tools	Content fields
`send_email`, `reply_to_email`, `forward_email`	`html` and/or `text` (required one of them) plus required `from`. Aliases: string `body` or `content` → `text` (or `html` when the string looks like HTML).
`save_draft`, `schedule_email_send`	String field `body` (HTML or text). Do not use `html`/`text` for drafts. Schedule also needs `scheduled_send_at`.

Validation failures return code: "validation_failed" with a details array of field paths (for example body: Either 'html' or 'text' must be provided) so agents can self-correct. Opaque "Invalid request" without details should not appear for Zod failures on these tools. 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:

Call prepare_destructive_action with:
- action — the destructive tool name
- arguments — the same arguments you will pass to that tool (without confirmationToken)
Receive { confirmationToken, expiresInSeconds } (token prefix mcp_confirm_, TTL 5 minutes, single-use, Redis-backed).
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:

Usage

get_api_credit_usage, get_email_usage

Workspaces & members

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

Custom domains (Developer+)

list_email_domains, add_email_domain, delete_email_domain, verify_email_domainThese hit Developer-gated REST paths. Free workspaces receive 403 when the tool runs.

Mailboxes

list_workspace_mailboxes, list_mailboxes, create_mailbox, get_mailbox, update_mailbox_settings, get_mailbox_storage

Emails, drafts, threads, folders, labels

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

AI agent & task triage

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

Safety

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.

Skills

Install Mermail workflows in Codex, Claude Code, and Cursor.

Authentication

Create and use sk-proj- API keys.

Discovery

Public discovery URLs including the MCP server card.

​Endpoint

​Authentication

​OAuth (browser-parity)

​API key (automation / CLI)

​Discover the server

​Official MCP Registry

​Connect an assistant

​How tools map to the API

​Email write payloads

​Destructive actions

​Tool catalog

​Related

Skills

Authentication

Discovery

Endpoint

Authentication

OAuth (browser-parity)

API key (automation / CLI)

Discover the server

Official MCP Registry

Connect an assistant

How tools map to the API

Email write payloads

Destructive actions

Tool catalog

Related