@multimail/mcp-server

MCP server for MultiMail. Give your agent its own email address with graduated human oversight — from full approval to autonomous sending.

Quick start

npx @multimail/mcp-server

Set MULTIMAIL_API_KEY for full access, or run without it to create an account first. Get a key at multimail.dev.

By using MultiMail you agree to the Terms of Service and Acceptable Use Policy.

Getting Started

Don't have an account yet? Two options:

Option A: Browser signup (recommended, 60 seconds)

1. Go to multimail.dev/pricing
2. Click Get started free (or pick a paid plan)
3. Choose what your agent will do and pick an oversight mode
4. Check your email for the activation code
5. Add the API key to your MCP config below

Option B: Remote MCP server (auto-signup via OAuth)

Add this to your MCP client — signup happens in the browser when you first connect:

{
  "mcpServers": {
    "multimail": {
      "type": "url",
      "url": "https://mcp.multimail.dev/mcp"
    }
  }
}

After signup: configure your mailbox

On first use, MultiMail will prompt you to configure your mailbox. You can also run this explicitly using the configure_mailbox tool:

• Oversight mode: How much human approval is required (gated_send, monitored, autonomous, etc.)
• Display name: Sender name shown in emails
• CC/BCC defaults: Automatically copy addresses on all outbound emails
• Scheduling: Enable/disable scheduled send and set default gate timing
• Signature: Email signature block

If you skip this step, MultiMail will remind you on your first tool call.

Setup

Option A: Remote server (recommended)

No install required. Connect directly to our hosted server. Authenticates via OAuth in the browser.

{
  "mcpServers": {
    "multimail": {
      "type": "url",
      "url": "https://mcp.multimail.dev/mcp"
    }
  }
}

Works with Claude.ai, Claude Desktop, Claude Code, and any client that supports remote MCP servers.

Option B: Local server (stdio)

Run the server locally. API key is passed as an environment variable.

{
  "mcpServers": {
    "multimail": {
      "command": "npx",
      "args": ["-y", "@multimail/mcp-server"],
      "env": {
        "MULTIMAIL_API_KEY": "mm_live_...",
        "MULTIMAIL_MAILBOX_ID": "01KJ1NHN8J..."
      }
    }
  }
}

Where to add this

Client	Config file
Claude Code	~/.claude/.mcp.json
Claude Desktop	claude_desktop_config.json
Cursor	.cursor/mcp.json in your project
Windsurf	~/.codeium/windsurf/mcp_config.json
Copilot (VS Code)	.vscode/mcp.json in your project
OpenCode	mcp.json in your project
ChatGPT Desktop	Settings > MCP Servers
Any MCP client	Consult your client's docs for config location

Environment variables

Variable	Required	Description
MULTIMAIL_API_KEY	Required for full access. Run without it to see setup instructions — or use the remote server for automatic OAuth signup.	Your MultiMail API key (mm_live_...)
MULTIMAIL_MAILBOX_ID	No	Default mailbox ID. If not set, pass mailbox_id to each tool or call list_mailboxes first.
MULTIMAIL_API_URL	No	API base URL. Defaults to https://api.multimail.dev.

Tools

Tool	Description
list_mailboxes	List all mailboxes available to this API key
configure_mailbox	Set up mailbox preferences: oversight mode, display name, CC/BCC, scheduling, signature
send_email	Send an email with a markdown body. Supports attachments, idempotency_key, and send_at for scheduled delivery.
check_inbox	List emails with filters: status, sender, subject, date range, direction, attachments, cursor pagination
read_email	Get full email content. Returns trusted metadata and untrusted body as separate content blocks.
reply_email	Reply to an email in its existing thread. Supports attachments and idempotency_key.
download_attachment	Download an email attachment as base64 with content type
get_thread	Get all emails in a conversation thread with participants and metadata
cancel_message	Cancel a pending or scheduled email
schedule_email	Schedule an email for future delivery with a required send_at time. Edit or cancel before it sends.
edit_scheduled_email	Edit a scheduled email's delivery time, recipients, subject, or body before it sends
update_mailbox	Update mailbox settings (display name, oversight mode, signature, webhooks)
update_account	Update account settings (org name, oversight email, physical address)
delete_mailbox	Permanently delete a mailbox (requires admin scope)
request_challenge	Request an ALTCHA proof-of-work challenge for account creation (no API key required)
create_account	Create a new account with a solved PoW challenge (no API key required)
resend_confirmation	Resend the activation email with a new code (no API key required)
activate_account	Activate an account using the code from the confirmation email (no API key required)
tag_email	Set, get, or delete key-value tags on emails (persistent agent memory)
add_contact	Add a contact to your address book with optional tags
search_contacts	Search address book by name or email
get_account	Get account status, plan, quota, sending enabled, enforcement tier
create_mailbox	Create a new mailbox (requires admin scope)
request_upgrade	Request an oversight mode upgrade (trust ladder)
apply_upgrade	Apply an upgrade code from the operator
get_usage	Check quota and usage stats for the billing period
list_pending	List emails awaiting oversight decision (requires oversight scope)
decide_email	Approve or reject a pending email (requires oversight scope)
report_spam	Mark an email as spam and move it to quarantine
not_spam	Restore a spam email to unread and label it as not spam
list_spam	List spam-flagged and quarantined emails
delete_contact	Delete a contact from the address book
check_suppression	List suppressed email addresses
remove_suppression	Remove an address from the suppression list
list_api_keys	List all API keys (requires admin scope)
create_api_key	Create a new API key with scopes (requires admin scope + operator approval; send+oversight combinations rejected to prevent self-approval)
revoke_api_key	Revoke an API key (requires admin scope)
get_audit_log	Get account audit log (requires admin scope)
delete_account	Permanently delete account and all data (requires admin scope)
wait_for_email	Block until a new email arrives matching filters, or timeout (max 120s)
create_webhook	Create a webhook subscription for real-time email event notifications
list_webhooks	List all webhook subscriptions for this account
delete_webhook	Delete a webhook subscription

How it works

• You write email bodies in markdown. MultiMail converts to formatted HTML for delivery.
• Incoming email arrives as clean markdown. No HTML parsing or MIME decoding.
• Threading is automatic. Reply to an email and headers are set correctly.
• Sends return pending_scan status while the email is scanned for threats. If your mailbox uses gated oversight, the status transitions to pending_send_approval for human review. Do not retry or resend.
• Verify other agents by checking the X-MultiMail-Identity signed header on received emails.

Development

npm install
npm run dev   # Run with tsx (no build needed)
npm run build # Compile TypeScript
npm start     # Run compiled version

Testing

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | MULTIMAIL_API_KEY=mm_live_... node dist/index.js

License

MIT