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.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 URL | https://mcp.zapmail.ai/mcp |
| Transport | Streamable HTTP. The server is stateless: every call is an HTTP POST to /mcp, and GET /mcp returns 405. |
| Authentication | OAuth 2.0 authorization code flow with PKCE (S256 only). Clients are public: there is no client secret. |
| Access token | Bearer token, valid for 1 hour. |
| Refresh token | Valid for 60 days. Clients refresh automatically. |
| Registration | Dynamic 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 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.| Scope | Grants |
|---|
domains | View and manage domains, DNS and connections. Also covers ZapShield, Deliverability Tests, Pre-Warmed and quick setup tools. |
mailboxes | View and manage mailboxes, Zapwarm settings, AI Insight analysis and sequencer lists. |
workspaces_billing | Buy plans, domains and add-ons, and manage workspaces and team members. Covers wallet, subscriptions and user tools. |
webhooks_integrations | Manage 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.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#
| Tool | Scope | Minimum role | Needs confirmed: true |
|---|
get_current_context | workspaces_billing | Viewer | No |
list_workspaces | workspaces_billing | Viewer | No |
update_workspace | workspaces_billing | Editor | No |
delete_workspace | workspaces_billing | Owner | Yes |
list_members | workspaces_billing | Viewer | No |
change_member_role | workspaces_billing | Admin | No |
remove_member | workspaces_billing | Admin | No |
invite_member | workspaces_billing | Admin | No |
list_invitations | workspaces_billing | Viewer | No |
switch_workspace | workspaces_billing | Viewer | No |
switch_service_provider | workspaces_billing | Viewer | No |
User#
| Tool | Scope | Minimum role | Needs confirmed: true |
|---|
get_user_details | workspaces_billing | Viewer | No |
Domains#
| Tool | Scope | Minimum role | Needs confirmed: true |
|---|
list_domains | domains | Viewer | No |
list_assignable_domains | domains | Viewer | No |
check_domain_availability | domains | Viewer | No |
check_domain_availability_bulk | domains | Viewer | No |
add_dmarc_record | domains | Editor | No |
add_domain_forwarding | domains | Editor | No |
remove_domain_forwarding | domains | Editor | No |
connect_domain | domains | Editor | No |
check_workspace_exists | domains | Viewer | No |
add_email_forwarding | domains | Editor | No |
remove_email_forwarding | domains | Editor | No |
add_catch_all_email | domains | Editor | No |
remove_catch_all_email | domains | Editor | No |
get_next_renewal_date | domains | Viewer | No |
check_dns_records | domains | Viewer | No |
update_domain_settings | domains | Editor | No |
remove_domains | domains | Editor | Yes |
buy_domain | domains | Admin | Yes |
list_domain_connection_requests | domains | Viewer | No |
remove_domain_connection_requests | domains | Editor | No |
add_google_client_id_to_domain | domains | Admin | No |
get_domain_health_score | domains | Viewer | No |
check_domain_blacklist | domains | Viewer | No |
ai_domain_finder | domains | Viewer | No |
move_domains_to_workspace | domains | Admin | No |
assign_tag_to_domain | domains | Editor | No |
list_domain_tags | domains | Viewer | No |
create_domain_tag | domains | Editor | No |
delete_domain_tag | domains | Editor | No |
remove_tags_from_domains | domains | Editor | No |
update_compliance_rules | domains | Admin | No |
get_compliance_rules | domains | Viewer | No |
list_domains_renewal_soon | domains | Viewer | No |
get_domain_renewal_price | domains | Viewer | No |
renew_domains | domains | Admin | Yes |
update_domain_auto_renew | domains | Editor | No |
get_buyback_eligible_domains | domains | Viewer | No |
sell_domain_buyback | domains | Admin | Yes |
Mailboxes#
| Tool | Scope | Minimum role | Needs confirmed: true |
|---|
provision_mailboxes | mailboxes | Editor | No |
assign_mailboxes | mailboxes | Editor | No |
list_mailboxes | mailboxes | Viewer | No |
get_mailbox_summary | mailboxes | Viewer | No |
get_mailbox_details | mailboxes | Viewer | No |
get_mailbox_subscription | workspaces_billing | Viewer | No |
update_mailbox | mailboxes | Editor | No |
schedule_mailbox_removal | mailboxes | Editor | No |
get_authenticator_code | mailboxes | Admin | No |
check_mailbox_exists_in_zapmail | mailboxes | Viewer | No |
custom_oauth_mailbox | mailboxes | Editor | No |
schedule_mailboxes | mailboxes | Editor | No |
retry_failed_mailbox_job | mailboxes | Editor | No |
Wallet and billing#
| Tool | Scope | Minimum role | Needs confirmed: true |
|---|
load_wallet_balance | workspaces_billing | Admin | Yes |
get_wallet_balance | workspaces_billing | Viewer | No |
get_billing_summary | workspaces_billing | Viewer | No |
set_consolidated_billing | workspaces_billing | Admin | No |
get_plan_pricing | workspaces_billing | Viewer | No |
enable_auto_recharge | workspaces_billing | Admin | No |
get_latest_invoice_url | workspaces_billing | Viewer | No |
buy_addon_mailboxes | workspaces_billing | Admin | Yes |
add_billing_details | workspaces_billing | Admin | No |
Subscriptions#
| Tool | Scope | Minimum role | Needs confirmed: true |
|---|
get_user_subscriptions | workspaces_billing | Viewer | No |
buy_plan | workspaces_billing | Admin | Yes |
upgrade_subscription | workspaces_billing | Admin | No |
cancel_subscription | workspaces_billing | Admin | Yes |
get_subscription_mailboxes | workspaces_billing | Viewer | No |
update_user_details | workspaces_billing | Editor | No |
Pre-Warmed and aged domains#
| Tool | Scope | Minimum role | Needs confirmed: true |
|---|
get_prewarmed_subscriptions | domains | Viewer | No |
get_prewarmed_domains | domains | Viewer | No |
get_prewarmed_domains_count | domains | Viewer | No |
purchase_prewarmed_subscription | domains | Admin | Yes |
assign_prewarmed_mailboxes | mailboxes | Editor | No |
get_aged_domains_available | domains | Viewer | No |
purchase_aged_domain | domains | Admin | Yes |
ZapShield#
| Tool | Scope | Minimum role | Needs confirmed: true |
|---|
purchase_dns_shield | domains | Admin | Yes |
upgrade_dns_shield_plan | domains | Admin | No |
get_dns_shield_eligible_domains | domains | Viewer | No |
get_dns_shield_available_slots | domains | Viewer | No |
allocate_dns_shield_domains | domains | Editor | No |
get_dns_shield_subscriptions | domains | Viewer | No |
get_dns_shield_allocated_domains | domains | Viewer | No |
cancel_dns_shield_subscription | domains | Admin | Yes |
Deliverability Tests#
| Tool | Scope | Minimum role | Needs confirmed: true |
|---|
get_placement_test_subscriptions | domains | Viewer | No |
purchase_placement_test_plan | domains | Admin | Yes |
get_placement_test_overall_report | domains | Viewer | No |
get_placement_test_orders | domains | Viewer | No |
get_placement_test_report | domains | Viewer | No |
get_placement_test_eligible_mailboxes | domains | Viewer | No |
get_placement_test_available_slots | domains | Viewer | No |
purchase_placement_test | domains | Editor | Yes |
generate_placement_test_spintax | domains | Editor | No |
cancel_placement_test_subscription | domains | Admin | Yes |
AI Insight#
| Tool | Scope | Minimum role | Needs confirmed: true |
|---|
get_ai_insight_credits | workspaces_billing | Viewer | No |
get_ai_insight_eligible_mailboxes | mailboxes | Viewer | No |
calculate_ai_insight_pricing | workspaces_billing | Viewer | No |
generate_mailbox_analysis | mailboxes | Editor | No |
get_mailbox_analysis | mailboxes | Viewer | No |
get_mailbox_analysis_by_id | mailboxes | Viewer | No |
share_mailbox_analysis | mailboxes | Editor | No |
get_public_mailbox_analysis | mailboxes | Viewer | No |
share_mailbox_analysis_by_email | mailboxes | Editor | No |
purchase_ai_insight_for_mailboxes | workspaces_billing | Admin | Yes |
purchase_ai_insight_plan | workspaces_billing | Admin | Yes |
upgrade_ai_insight_plan | workspaces_billing | Admin | No |
Zapwarm#
| Tool | Scope | Minimum role | Needs confirmed: true |
|---|
get_zapwarm_free_trial | mailboxes | Viewer | No |
get_zapwarm_subscription | mailboxes | Viewer | No |
get_zapwarm_pricing | workspaces_billing | Admin | No |
count_zapwarm_eligible | mailboxes | Viewer | No |
quote_zapwarm | workspaces_billing | Admin | No |
start_zapwarm | workspaces_billing | Admin | Yes |
pause_zapwarm | mailboxes | Editor | Yes |
update_zapwarm_settings | mailboxes | Editor | No |
update_zapwarm_signature | mailboxes | Editor | No |
get_zapwarm_overview | mailboxes | Viewer | No |
get_zapwarm_mailbox_scores | mailboxes | Viewer | No |
get_zapwarm_mailbox_report | mailboxes | Viewer | No |
get_zapwarm_mailbox_settings | mailboxes | Viewer | No |
guess_zapwarm_industry | mailboxes | Viewer | No |
list_zapwarm_custom_copies | mailboxes | Viewer | No |
add_zapwarm_custom_copy | mailboxes | Editor | No |
delete_zapwarm_custom_copy | mailboxes | Editor | Yes |
Quick setup#
| Tool | Scope | Minimum role | Needs confirmed: true |
|---|
store_quick_setup | domains | Editor | No |
get_quick_setup_entries | domains | Viewer | No |
Webhooks#
| Tool | Scope | Minimum role | Needs confirmed: true |
|---|
list_webhook_event_types | webhooks_integrations | Viewer | No |
create_webhook_endpoint | webhooks_integrations | Admin | No |
list_webhook_endpoints | webhooks_integrations | Viewer | No |
get_webhook_endpoint | webhooks_integrations | Viewer | No |
update_webhook_endpoint | webhooks_integrations | Admin | No |
delete_webhook_endpoint | webhooks_integrations | Admin | No |
test_webhook_endpoint | webhooks_integrations | Admin | No |
emit_dummy_webhook_event | webhooks_integrations | Admin | No |
list_webhook_deliveries | webhooks_integrations | Viewer | No |
resend_webhook_delivery | webhooks_integrations | Admin | No |
Sequencer accounts, exports and DNS records#
| Tool | Scope | Minimum role | Needs confirmed: true |
|---|
add_google_client_id | webhooks_integrations | Admin | No |
add_third_party_account | webhooks_integrations | Admin | No |
update_third_party_account | webhooks_integrations | Admin | No |
export_mailboxes_to_third_party | webhooks_integrations | Editor | No |
get_export_status | webhooks_integrations | Viewer | No |
fetch_third_party_workspaces | webhooks_integrations | Viewer | No |
add_user_dns_records | webhooks_integrations | Editor | No |
get_user_dns_records | webhooks_integrations | Viewer | No |
update_user_dns_records | webhooks_integrations | Editor | No |
delete_user_dns_records | webhooks_integrations | Editor | No |
bulk_add_user_dns_records | webhooks_integrations | Editor | No |
global_mailbox_domain_search | webhooks_integrations | Viewer | No |
Sequencers#
| Tool | Scope | Minimum role | Needs confirmed: true |
|---|
list_supported_sequencers | mailboxes | Viewer | No |
Documentation#
| Tool | Scope | Minimum role | Needs confirmed: true |
|---|
fetch_zapmail_docs | domains | Viewer | No |
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.