Zapmail
Overview
API Reference
Overview
API Reference
  1. Overview
  • Introduction
  • Quickstart
  • Authentication
  • MCP
  • Versioning
  • Errors
  • Webhooks
  • Rate Limits
  • Pagination
  • Changelog
  • Capabilities
    • Mailboxes
    • Pre-Warmed
    • Deliverability
    • Domains
    • Export to Sequencer
    • Zapbox
    • Team Management
    • ZapShield
    • ZapCare
    • AI Insight
    • Deliverability Tests
    • ZapSites
    • Zapwarm
    • ZapPulse
  • Billing
    • Understanding Zapmail billing
    • Wallet
  1. Overview

MCP

The Zapmail MCP server lets an AI agent or MCP-compatible client manage your Zapmail account through tools: domains, mailboxes, workspaces, billing, webhooks and sequencer exports. It is a remote server that you connect to with OAuth. It is separate from the REST API and does not use API keys.
Purchases are real
Purchase tools pay from your wallet and complete immediately when the wallet covers the cost. There is no test mode. Review what a tool will do before you approve it.

Connection details#

Server URLhttps://mcp.zapmail.ai/mcp
TransportStreamable HTTP. The server is stateless: every call is an HTTP POST to /mcp, and GET /mcp returns 405.
AuthenticationOAuth 2.0 authorization code flow with PKCE (S256 only). Clients are public: there is no client secret.
Access tokenBearer token, valid for 1 hour.
Refresh tokenValid for 60 days. Clients refresh automatically.
RegistrationDynamic client registration at /register. Limited to 20 registrations per hour per IP address.
Discovery/.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource on the same host.
The authorization, token and revocation endpoints (/authorize, /token, /revoke) are served by the same host. An MCP client discovers all of this on its own, so you only need the server URL.
A request without a valid bearer token gets 401 with a WWW-Authenticate header that points to the protected-resource metadata, which is what starts the OAuth flow in a compliant client.

Connect a client#

Every client uses the same URL and runs the same OAuth consent. When you connect, you sign in to Zapmail and choose which scopes to grant.
Claude Code
Claude Desktop
Cursor
VS Code
Codex CLI
Other clients
claude mcp add --transport http zapmail https://mcp.zapmail.ai/mcp
Run /mcp inside Claude Code and authenticate the zapmail server. Approve the scopes you want to grant.

Scopes#

Scopes decide which tools the server offers to your client. A tool whose scope you did not grant is not registered at all.
ScopeGrants
domainsView and manage domains, DNS and connections. Also covers ZapShield, Deliverability Tests, Pre-Warmed and quick setup tools.
mailboxesView and manage mailboxes, Zapwarm settings, AI Insight analysis and sequencer lists.
workspaces_billingBuy plans, domains and add-ons, and manage workspaces and team members. Covers wallet, subscriptions and user tools.
webhooks_integrationsManage webhooks and connected third-party accounts, exports and DNS records.
Grant only what the agent needs. A read-only assistant should not hold workspaces_billing.

Workspace and roles#

Each connection works in one active workspace, or across all of an owner's workspaces for unified accounts. Call get_current_context first: it returns the active workspace, your role and related context. Use switch_workspace to change workspace.
Every tool declares a minimum workspace role (Viewer, Editor, Admin or Owner). The role check runs on every call, in addition to the scope filter. A tool called without the required role returns an error with the message This action requires at least the <role> role. Workspace and resource IDs are re-validated against your workspace on every call, so an ID from another workspace is rejected.

Confirmation and charges#

Tools that delete data or spend money require an explicit confirmed: true argument. Without it the call fails with 400 and a message asking the agent to show the user what will happen first. The tools are marked in the tables below.
Purchase tools pay from the wallet balance. If the wallet covers the cost, the charge completes in that same call. If it does not, the tool returns a payment link for the remainder.
Some tools that can change what you pay do not require confirmation. They are upgrade_subscription, upgrade_dns_shield_plan, upgrade_ai_insight_plan, set_consolidated_billing and enable_auto_recharge. upgrade_subscription with upgradeType IMMEDIATE charges the prorated difference at once. These need Admin or Owner. Keep a human approval step in your client for them.
load_wallet_balance always returns a Stripe payment link. You pay by card in the browser.
Tool calls are recorded in an audit log. Sensitive arguments such as passwords, tokens and secrets are redacted.

Tool reference#

Tools are named for what they do, not for the REST endpoint behind them. The tables list every tool the server registers. Tool descriptions and input schemas are delivered to your client through the MCP tool listing, so a client always sees the current set. The fetch_zapmail_docs tool lets an agent read Zapmail documentation.
Tool results are returned as JSON text. A failed call returns the error message with isError set.

Workspaces and members#

ToolScopeMinimum roleNeeds confirmed: true
get_current_contextworkspaces_billingViewerNo
list_workspacesworkspaces_billingViewerNo
update_workspaceworkspaces_billingEditorNo
delete_workspaceworkspaces_billingOwnerYes
list_membersworkspaces_billingViewerNo
change_member_roleworkspaces_billingAdminNo
remove_memberworkspaces_billingAdminNo
invite_memberworkspaces_billingAdminNo
list_invitationsworkspaces_billingViewerNo
switch_workspaceworkspaces_billingViewerNo
switch_service_providerworkspaces_billingViewerNo

User#

ToolScopeMinimum roleNeeds confirmed: true
get_user_detailsworkspaces_billingViewerNo

Domains#

ToolScopeMinimum roleNeeds confirmed: true
list_domainsdomainsViewerNo
list_assignable_domainsdomainsViewerNo
check_domain_availabilitydomainsViewerNo
check_domain_availability_bulkdomainsViewerNo
add_dmarc_recorddomainsEditorNo
add_domain_forwardingdomainsEditorNo
remove_domain_forwardingdomainsEditorNo
connect_domaindomainsEditorNo
check_workspace_existsdomainsViewerNo
add_email_forwardingdomainsEditorNo
remove_email_forwardingdomainsEditorNo
add_catch_all_emaildomainsEditorNo
remove_catch_all_emaildomainsEditorNo
get_next_renewal_datedomainsViewerNo
check_dns_recordsdomainsViewerNo
update_domain_settingsdomainsEditorNo
remove_domainsdomainsEditorYes
buy_domaindomainsAdminYes
list_domain_connection_requestsdomainsViewerNo
remove_domain_connection_requestsdomainsEditorNo
add_google_client_id_to_domaindomainsAdminNo
get_domain_health_scoredomainsViewerNo
check_domain_blacklistdomainsViewerNo
ai_domain_finderdomainsViewerNo
move_domains_to_workspacedomainsAdminNo
assign_tag_to_domaindomainsEditorNo
list_domain_tagsdomainsViewerNo
create_domain_tagdomainsEditorNo
delete_domain_tagdomainsEditorNo
remove_tags_from_domainsdomainsEditorNo
update_compliance_rulesdomainsAdminNo
get_compliance_rulesdomainsViewerNo
list_domains_renewal_soondomainsViewerNo
get_domain_renewal_pricedomainsViewerNo
renew_domainsdomainsAdminYes
update_domain_auto_renewdomainsEditorNo
get_buyback_eligible_domainsdomainsViewerNo
sell_domain_buybackdomainsAdminYes

Mailboxes#

ToolScopeMinimum roleNeeds confirmed: true
provision_mailboxesmailboxesEditorNo
assign_mailboxesmailboxesEditorNo
list_mailboxesmailboxesViewerNo
get_mailbox_summarymailboxesViewerNo
get_mailbox_detailsmailboxesViewerNo
get_mailbox_subscriptionworkspaces_billingViewerNo
update_mailboxmailboxesEditorNo
schedule_mailbox_removalmailboxesEditorNo
get_authenticator_codemailboxesAdminNo
check_mailbox_exists_in_zapmailmailboxesViewerNo
custom_oauth_mailboxmailboxesEditorNo
schedule_mailboxesmailboxesEditorNo
retry_failed_mailbox_jobmailboxesEditorNo

Wallet and billing#

ToolScopeMinimum roleNeeds confirmed: true
load_wallet_balanceworkspaces_billingAdminYes
get_wallet_balanceworkspaces_billingViewerNo
get_billing_summaryworkspaces_billingViewerNo
set_consolidated_billingworkspaces_billingAdminNo
get_plan_pricingworkspaces_billingViewerNo
enable_auto_rechargeworkspaces_billingAdminNo
get_latest_invoice_urlworkspaces_billingViewerNo
buy_addon_mailboxesworkspaces_billingAdminYes
add_billing_detailsworkspaces_billingAdminNo

Subscriptions#

ToolScopeMinimum roleNeeds confirmed: true
get_user_subscriptionsworkspaces_billingViewerNo
buy_planworkspaces_billingAdminYes
upgrade_subscriptionworkspaces_billingAdminNo
cancel_subscriptionworkspaces_billingAdminYes
get_subscription_mailboxesworkspaces_billingViewerNo
update_user_detailsworkspaces_billingEditorNo

Pre-Warmed and aged domains#

ToolScopeMinimum roleNeeds confirmed: true
get_prewarmed_subscriptionsdomainsViewerNo
get_prewarmed_domainsdomainsViewerNo
get_prewarmed_domains_countdomainsViewerNo
purchase_prewarmed_subscriptiondomainsAdminYes
assign_prewarmed_mailboxesmailboxesEditorNo
get_aged_domains_availabledomainsViewerNo
purchase_aged_domaindomainsAdminYes

ZapShield#

ToolScopeMinimum roleNeeds confirmed: true
purchase_dns_shielddomainsAdminYes
upgrade_dns_shield_plandomainsAdminNo
get_dns_shield_eligible_domainsdomainsViewerNo
get_dns_shield_available_slotsdomainsViewerNo
allocate_dns_shield_domainsdomainsEditorNo
get_dns_shield_subscriptionsdomainsViewerNo
get_dns_shield_allocated_domainsdomainsViewerNo
cancel_dns_shield_subscriptiondomainsAdminYes

Deliverability Tests#

ToolScopeMinimum roleNeeds confirmed: true
get_placement_test_subscriptionsdomainsViewerNo
purchase_placement_test_plandomainsAdminYes
get_placement_test_overall_reportdomainsViewerNo
get_placement_test_ordersdomainsViewerNo
get_placement_test_reportdomainsViewerNo
get_placement_test_eligible_mailboxesdomainsViewerNo
get_placement_test_available_slotsdomainsViewerNo
purchase_placement_testdomainsEditorYes
generate_placement_test_spintaxdomainsEditorNo
cancel_placement_test_subscriptiondomainsAdminYes

AI Insight#

ToolScopeMinimum roleNeeds confirmed: true
get_ai_insight_creditsworkspaces_billingViewerNo
get_ai_insight_eligible_mailboxesmailboxesViewerNo
calculate_ai_insight_pricingworkspaces_billingViewerNo
generate_mailbox_analysismailboxesEditorNo
get_mailbox_analysismailboxesViewerNo
get_mailbox_analysis_by_idmailboxesViewerNo
share_mailbox_analysismailboxesEditorNo
get_public_mailbox_analysismailboxesViewerNo
share_mailbox_analysis_by_emailmailboxesEditorNo
purchase_ai_insight_for_mailboxesworkspaces_billingAdminYes
purchase_ai_insight_planworkspaces_billingAdminYes
upgrade_ai_insight_planworkspaces_billingAdminNo

Zapwarm#

ToolScopeMinimum roleNeeds confirmed: true
get_zapwarm_free_trialmailboxesViewerNo
get_zapwarm_subscriptionmailboxesViewerNo
get_zapwarm_pricingworkspaces_billingAdminNo
count_zapwarm_eligiblemailboxesViewerNo
quote_zapwarmworkspaces_billingAdminNo
start_zapwarmworkspaces_billingAdminYes
pause_zapwarmmailboxesEditorYes
update_zapwarm_settingsmailboxesEditorNo
update_zapwarm_signaturemailboxesEditorNo
get_zapwarm_overviewmailboxesViewerNo
get_zapwarm_mailbox_scoresmailboxesViewerNo
get_zapwarm_mailbox_reportmailboxesViewerNo
get_zapwarm_mailbox_settingsmailboxesViewerNo
guess_zapwarm_industrymailboxesViewerNo
list_zapwarm_custom_copiesmailboxesViewerNo
add_zapwarm_custom_copymailboxesEditorNo
delete_zapwarm_custom_copymailboxesEditorYes

Quick setup#

ToolScopeMinimum roleNeeds confirmed: true
store_quick_setupdomainsEditorNo
get_quick_setup_entriesdomainsViewerNo

Webhooks#

ToolScopeMinimum roleNeeds confirmed: true
list_webhook_event_typeswebhooks_integrationsViewerNo
create_webhook_endpointwebhooks_integrationsAdminNo
list_webhook_endpointswebhooks_integrationsViewerNo
get_webhook_endpointwebhooks_integrationsViewerNo
update_webhook_endpointwebhooks_integrationsAdminNo
delete_webhook_endpointwebhooks_integrationsAdminNo
test_webhook_endpointwebhooks_integrationsAdminNo
emit_dummy_webhook_eventwebhooks_integrationsAdminNo
list_webhook_deliverieswebhooks_integrationsViewerNo
resend_webhook_deliverywebhooks_integrationsAdminNo

Sequencer accounts, exports and DNS records#

ToolScopeMinimum roleNeeds confirmed: true
add_google_client_idwebhooks_integrationsAdminNo
add_third_party_accountwebhooks_integrationsAdminNo
update_third_party_accountwebhooks_integrationsAdminNo
export_mailboxes_to_third_partywebhooks_integrationsEditorNo
get_export_statuswebhooks_integrationsViewerNo
fetch_third_party_workspaceswebhooks_integrationsViewerNo
add_user_dns_recordswebhooks_integrationsEditorNo
get_user_dns_recordswebhooks_integrationsViewerNo
update_user_dns_recordswebhooks_integrationsEditorNo
delete_user_dns_recordswebhooks_integrationsEditorNo
bulk_add_user_dns_recordswebhooks_integrationsEditorNo
global_mailbox_domain_searchwebhooks_integrationsViewerNo

Sequencers#

ToolScopeMinimum roleNeeds confirmed: true
list_supported_sequencersmailboxesViewerNo

Documentation#

ToolScopeMinimum roleNeeds confirmed: true
fetch_zapmail_docsdomainsViewerNo

Example: provision a new domain#

1.
Call get_current_context to confirm the workspace.
2.
Check availability with check_domain_availability or check_domain_availability_bulk.
3.
Check the balance with get_wallet_balance. If it is short, call load_wallet_balance and have the user pay the link.
4.
Tell the user the cost, then call buy_domain with confirmed: true.
5.
Create mailboxes with schedule_mailboxes.
6.
Poll list_mailboxes until provisioning completes.
Related: Authentication, Understanding Zapmail billing, Webhooks.
Previous
Authentication
Next
Versioning
Built with