Zapmail MCP — Setup Guide

Zapmail's MCP server is a remote, OAuth-protected endpoint — the same domains, mailboxes,
billing, and integrations you manage in the dashboard, exposed as 134 tools your agent can
call directly. No API keys to copy, no separate REST client to write.

Overview


Endpoint	`https://mcp.zapmail.ai/mcp`
Auth	OAuth 2.1 — discovery, authorize, token, and revoke endpoints are served by the same host. No static API keys.
Context	Call `get_current_context` first — it returns the active workspace, your role, and the connected service provider (Google or Microsoft).
Tool count	134 tools across domains, mailboxes, workspaces & billing, and integrations — filtered to whatever scopes your token was granted.

It speaks Streamable HTTP (the current MCP transport), and every call is scoped to your
authenticated user and their active workspace — the agent never sees more than what you've
granted.

Connect your client

Every client below talks to the same URL and runs the same OAuth handshake — only the config
location changes.

Cursor

VS Code

Claude Code

Claude Desktop

Codex CLI

General (any MCP client)

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "zapmail": {
      "url": "https://mcp.zapmail.ai/mcp"
    }
  }
}

Cursor prompts for OAuth on first connect — approve it, and the tools appear in the MCP panel.

Scopes & roles

Scopes gate which tools appear during OAuth consent. Workspace role gates whether a call
succeeds once the tool is invoked — both checks run on every call, not just at connect time.

Scope	Grants	Tools
`domains`	View and manage domains, DNS, and connections	63
`mailboxes`	View and manage mailboxes	20
`workspaces_billing`	Buy plans, domains, and add-ons; manage workspaces and team members	29
`webhooks_integrations`	Manage webhooks and connected third-party accounts	22

Request only the scopes your agent actually needs — a read-only research assistant should never
hold workspaces_billing.

Role	Can call
Viewer	Read-only tools — lookups, lists, status checks
Editor / Admin	Mutating tools — create, update, connect, delete
Admin / Owner	Anything that spends wallet balance — purchases, renewals, sell-back

Tool surface

Tools are named for what they do, not the endpoint behind them.

Category	Examples	Count
Domains	`search_domains` · `buy_domains` · `connect_domain` · `get_domain_dns`	37
Mailboxes	`schedule_mailboxes` · `list_mailboxes` · `update_mailbox`	12
Prewarmed & aged domains	`list_aged_domains` · `buy_prewarmed_domain`	7
DNS Shield	`enable_dns_shield` · `get_dns_shield_status`	8
Workspaces	`invite_workspace_member` · `switch_workspace` · `update_member_role`	11
Billing & subscriptions	`top_up_wallet` · `get_wallet_balance` · `list_invoices`	12
Webhooks	`create_webhook` · `list_webhook_deliveries`	10
Third-party accounts	`connect_sequencer` · `export_mailboxes`	12
AI insight & placement tests	`get_deliverability_insight` · `run_placement_test`	22
Quick setup, users	`quick_setup_workspace` · `get_user_details`	3

Guardrails

Destructive and paying tools require confirmed: true. Deleting a domain, buying domains,
renewing, or selling back all reject the call until the argument is set — the agent is expected
to show the user exactly what will happen first.

Purchases charge immediately, not on preview. If your wallet balance covers the cost, a
purchase or renewal tool completes the charge in that same call. If it doesn't, the tool returns
a payment link for the remainder instead of failing outright.

IDs are re-validated per call. A domain, mailbox, or workspace ID from a different workspace
is rejected server-side — an agent can't reuse or guess its way across workspace boundaries.

Orchestration patterns

Provisioning a new domain

Check availability — search_domains or the bulk variant

Confirm wallet balance — get_wallet_balance (top up first if short)

Purchase — buy_domains with confirmed: true, after telling the user the charge

Schedule mailboxes — schedule_mailboxes against the new domain

Confirm — poll list_mailboxes until provisioning completes

Team operations

Find the workspace — get_current_context, or switch_workspace if it's the wrong one

Invite — invite_workspace_member

Adjust role — update_member_role if their access needs to change

Exporting mailboxes to a sequencer

Connect the account — connect_sequencer / create third-party credentials

Trigger the export — export_mailboxes

Watch status — poll the export job until it reports done

MCP

Zapmail MCP — Setup Guide#

Overview#

Connect your client#

Scopes & roles#

Tool surface#

Guardrails#