MultiMail: Email for AI Agents

MultiMail gives you a real email address. Send and receive email as markdown, 15x fewer tokens than raw HTML email. Human oversight is handled for you.

OpenAPI spec: GET https://api.multimail.dev/v1/openapi.json for full machine-readable API details.

Base URL: https://api.multimail.dev

Auth: Authorization: Bearer mm_live_...

What this does for you

• You get an email address like zippy@agent.multimail.dev
• You send email by POSTing markdown. It arrives as formatted HTML.
• You receive email as clean markdown. No HTML parsing, no MIME decoding.
• Threading is automatic. Reply to an email and headers are set correctly.
• Attachments are stored separately and downloaded on demand, not inlined as base64
• Oversight mode controls whether your emails need approval before sending
• Every outbound email carries a cryptographically signed X-MultiMail-Identity header (ECDSA P-256) with operator, oversight mode, capabilities, and verification status.

Verify before you communicate

Every outbound email from a MultiMail address includes a signed X-MultiMail-Identity header. The header contains a base64url-encoded JSON payload and an ECDSA P-256 signature, separated by a dot. To verify: decode both parts, fetch the public key from GET /.well-known/multimail-signing-key, and verify the signature using ECDSA with SHA-256. Identity is delivered exclusively via this signed header. No separate lookup endpoint is needed or available.

Reputation data is delivered separately via the X-MultiMail-Reputation header on every outbound email.

Getting started

1. Sign up

Web setup (recommended): After your beta invite is approved, follow the setup link in your approval email. The guided flow walks you through account creation, activation, and client configuration.

API signup: Alternatively, create an account programmatically:

POST /v1/account
{
  "operator_name": "Greenline Studios",
  "slug": "greenline",
  "accepted_tos": true,
  "accepted_operator_agreement": true,
  "accepted_anti_spam_policy": true,
  "email_use_type": "transactional",
  "oversight_email": "ops@greenline.studio"
}

Response includes a default_mailbox address (e.g. agent@greenline.multimail.dev) and a pending status. Check your oversight email for an activation code, then confirm via POST /v1/confirm to activate and receive your API key (shown once). Manage your account at /dashboard.

Note: operator_name is published in the signed X-MultiMail-Identity header on every outbound email and visible to email recipients.

2. Upgrade (optional)

Plan	Price	Mailboxes	Emails/mo	Storage
Starter	Free	2	200	100 MB
Builder	$9/mo	5	5,000	10 GB
Pro	$29/mo	25	30,000	50 GB
Scale	$99/mo	100	150,000	150 GB

See full pricing with annual discounts and subscribe →

// Stripe (card) — supports monthly or annual billing
POST /v1/billing/checkout
{ "plan": "builder", "interval": "annual" }  // builder | pro | scale

// Crypto (Coinbase Commerce -- one-time annual payment)
POST /v1/billing/crypto-checkout
{ "plan": "builder" }

Both return { "url": "https://..." }. Stripe handles recurring subscriptions; Coinbase Commerce processes a one-time payment for the annual term. Complete payment at that URL or pass it to your operator.

3. Send an email

POST /v1/mailboxes/{mailbox_id}/send
{
  "to": ["recipient@example.com"],
  "subject": "Weekly summary",
  "markdown": "## Completed\n\n- Task A\n- Task B\n\nAll items resolved."
}

Returns 200 if sent, 202 if held for operator approval (gated mode), or 403 if the mailbox is in read_only mode.

4. Read your inbox

GET /v1/mailboxes/{mailbox_id}/emails?status=unread

Returns emails as markdown. Each email includes thread_id, from, to, subject, and attachment metadata.

5. Reply in-thread

POST /v1/mailboxes/{mailbox_id}/reply/{email_id}
{
  "markdown": "Acknowledged. I'll follow up tomorrow."
}

Oversight modes

Each mailbox has an oversight mode set via the API or by an admin. Modes form a trust ladder: start restrictive, upgrade as you earn trust.

• read_only: you can receive and read email, but cannot send or reply. Attempts return 403 with instructions on how to request an upgrade.
• gated_all: both inbound and outbound require human approval
• gated_send (default): outbound emails are held for approval. You receive a 202 instead of 200. Inbound delivered immediately.
• monitored: you operate freely, copies of outbound emails go to the oversight address
• autonomous: full send/receive without approval gates

If you receive a 202, the email is queued. Do not retry. The oversight address will be notified.

Requesting an upgrade

If your mailbox is in a restrictive mode and you need more autonomy, request an upgrade:

POST /v1/mailboxes/{mailbox_id}/request-upgrade
{ "target_mode": "gated_all" }

This emails a one-time upgrade code to your operator. Ask your operator to share it with you, then:

POST /v1/mailboxes/{mailbox_id}/upgrade
{ "code": "A7X-29K" }

Codes expire after 24 hours and can only be used once. No code is needed for downgrades. Use PATCH /v1/mailboxes/:id to move to a more restrictive mode at any time.

Handling attachments

• Sending: Include attachments array with name, content_base64, content_type. Max 10MB total.
• Receiving: Email response includes attachments with metadata. Download via GET /v1/mailboxes/:id/emails/:eid/attachments/:filename.

Webhooks

Configure webhooks on your mailbox to receive push notifications instead of polling. Two webhook types are available:

• webhook_url — notifies the agent when new email arrives (email.received)
• oversight_webhook_url — notifies the operator when an email is held for approval (email.pending_approval)

Set either via POST /v1/mailboxes or PATCH /v1/mailboxes/:id. Both must use HTTPS.

Webhook payload

All webhooks deliver a POST request with a JSON body:

{
  "event": "email.received",
  "timestamp": "2026-02-26T12:00:00.000Z",
  "data": {
    "email_id": "em_abc123",
    "from": "sender@example.com",
    "to": ["agent@yourco.multimail.dev"],
    "subject": "Weekly report",
    "direction": "inbound",
    "has_attachments": false
  }
}

For email.pending_approval, the data object also includes an approval_url for one-click approve/reject.

Signature verification

Every webhook request includes an X-MultiMail-Signature header containing an HMAC-SHA256 signature of the raw request body. Verify it server-side to confirm the request came from MultiMail.

Retries and delivery history

Failed deliveries (non-2xx response) are retried up to 3 times with exponential backoff. View delivery history and debug failures via GET /v1/webhook-deliveries (requires admin scope).

If you don't use webhooks, poll GET /v1/mailboxes/:id/emails?status=unread instead.

MCP Server

If your framework supports the Model Context Protocol (MCP), use our MCP server instead of direct API calls. One config line gives you thirty-five email tools.

Option A: Remote server (recommended)

No install required. Connect directly to our hosted MCP server at mcp.multimail.dev. Authenticates via OAuth in the browser — paste your API key once and you're connected. Works with Claude.ai, Claude Desktop, Claude Code, and any client that supports remote MCP.

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

Option B: Local server (stdio)

Run the server locally via npm. API key is passed as an environment variable. Works with all MCP-compatible clients. Package: @multimail/mcp-server

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

Environment variables (local server only)

• MULTIMAIL_API_KEY (required): your API key. Server refuses to start without it.
• MULTIMAIL_MAILBOX_ID (optional): default mailbox ID so you don't need to pass it on every tool call. If not set, call list_mailboxes first.
• MULTIMAIL_API_URL (optional): override API base URL for local development. Defaults to https://api.multimail.dev.

Tools

list_mailboxes: List all mailboxes available to this API key. Returns each mailbox's ID, email address, oversight mode, and display name. No arguments.

send_email: Send an email with a markdown body. Args: to (string[]), subject (string), markdown (string), cc (string[], optional), bcc (string[], optional), attachments (array of {name, content_base64, content_type}, optional), idempotency_key (string, optional), mailbox_id (string, optional). Returns { id, status, thread_id } where status is "pending_scan". For gated mailboxes, transitions to "pending_send_approval". Do not retry or resend. Use idempotency_key to prevent duplicate sends (24h TTL).

check_inbox: List email summaries with filtering. Args: status (unread/read/archived/deleted/pending_send_approval/pending_inbound_approval/rejected/cancelled/send_failed, optional), sender (string, partial match, optional), subject_contains (string, optional), date_after / date_before (ISO datetime, optional), direction (inbound/outbound, optional), has_attachments (boolean, optional), since_id (string, for incremental polling, optional), limit (number, max 100, optional), cursor (string, pagination cursor, optional), mailbox_id (string, optional). Returns array of { id, from, to, subject, status, received_at, has_attachments, delivered_at, bounced_at, bounce_type }. Does NOT include the email body. Call read_email for full content.

read_email: Get full email content including markdown body, attachment metadata, delivery timestamps, and tags. Args: email_id (string), mailbox_id (string, optional). Automatically marks unread emails as read. Returns delivered_at, bounced_at, bounce_type, approved_at, approved_by, and tags.

reply_email: Reply to an email in its existing thread. Threading headers set automatically. Args: email_id (string), markdown (string), cc (string[], optional), bcc (string[], optional), attachments (array, optional), idempotency_key (string, optional), mailbox_id (string, optional). Returns { id, status, thread_id }. Same scanning and approval behavior as send_email.

download_attachment: Download an email attachment as base64-encoded data. Args: email_id (string), filename (string, from read_email attachment list), mailbox_id (string, optional). Returns { filename, content_type, content_base64, size_bytes }.

get_thread: Get all emails in a conversation thread, ordered chronologically. Args: thread_id (string, from check_inbox or read_email), mailbox_id (string, optional). Returns participants, message_count, last_activity, has_unanswered_inbound, and the full email list.

cancel_message: Cancel a pending email. Args: email_id (string), mailbox_id (string, optional). Works on emails with status pending_scan, pending_send_approval, or pending_inbound_approval. Returns 409 if already sent. Idempotent on already-cancelled emails.

tag_email: Set, get, or delete key-value tags on emails. Tags persist across sessions. Args: email_id (string), action (set/get/delete), tags (Record<string, string>, for set), key (string, for delete), mailbox_id (string, optional). Use for priority flags, follow-up dates, extracted data, or any agent metadata.

add_contact: Add a contact to your address book. Args: name (string), email (string), tags (string[], optional). Build contacts organically from processed messages.

search_contacts: Search address book by name or email (partial match). Args: query (string, optional). Returns matching contacts with tags. Call with no query to list all.

update_mailbox: Update mailbox settings. All fields optional — only include what you want to change. Args: mailbox_id (string, optional), display_name (string, optional), oversight_mode (string, optional), auto_cc (string, optional), auto_bcc (string, optional), forward_inbound (boolean, optional), webhook_url (string, optional), oversight_webhook_url (string, optional), signature_block (string, optional).

update_account: Update account settings. Args: name (string, optional), oversight_email (string, optional), physical_address (string, optional). Requires admin scope.

delete_mailbox: Permanently delete a mailbox and all associated data. Args: mailbox_id (string). Requires admin scope. This action cannot be undone.

resend_confirmation: Resend the operator activation email with a new code. No arguments. Rate limited to 1 request per 5 minutes. Only works for unconfirmed accounts.

activate_account: Activate your account using the code from the confirmation email. Args: code (string, e.g. "SKP-7D2-4V8"). Accepts with or without dashes. Rate limited to 5 attempts per hour.

get_account: Get account status, plan, quota used/remaining, sending enabled, and enforcement tier. No arguments. Use for self-diagnosis when sends fail.

create_mailbox: Create a new mailbox. Args: address_local_part (string), display_name (string, optional), oversight_mode (string, optional). Requires admin scope.

request_upgrade: Request an oversight mode upgrade. Args: mailbox_id (string, optional), target_mode (string). Sends upgrade request to operator. Requires admin scope.

apply_upgrade: Apply an upgrade code from operator. Args: mailbox_id (string, optional), code (string).

get_usage: Check quota and usage stats. Args: period (summary/daily, optional). Returns emails sent, received, storage used, plan limits.

list_pending: List emails awaiting oversight decision. No arguments. Requires oversight or oversight_read scope.

decide_email: Approve or reject a pending email. Args: email_id (string), action (approve/reject), reason (string, optional). Requires oversight scope.

delete_contact: Delete a contact. Args: contact_id (string).

check_suppression: List suppressed email addresses. Args: limit (number, optional), cursor (string, optional).

remove_suppression: Remove address from suppression list. Args: email_address (string).

list_api_keys: List all API keys with metadata. No arguments. Requires admin scope.

create_api_key: Create a new API key. Args: name (string), scopes (string[]). Requires admin scope. Key value returned only once.

revoke_api_key: Revoke an API key. Args: key_id (string). Requires admin scope. Cannot be undone.

get_audit_log: Get account audit log. Args: limit (number, optional), cursor (string, optional). Requires admin scope.

delete_account: Permanently delete account and all data. No arguments. Requires admin scope. Cannot be undone.

wait_for_email: Block until a new email arrives matching optional filters, or timeout. Args: mailbox_id (string, optional), timeout_seconds (number, 5–120, default 30), filter ({sender?, subject_contains?}, optional). Returns immediately when mail arrives.

create_webhook: Create a webhook subscription for real-time email event notifications. Args: url (HTTPS string), events (string[]), mailbox_id (string, optional). Returns subscription with signing_secret.

list_webhooks: List all webhook subscriptions for this account. No arguments.

delete_webhook: Delete a webhook subscription. Args: webhook_id (string).

Error handling

• 401: Invalid API key. Check MULTIMAIL_API_KEY.
• 403: API key lacks required scope for this operation.
• 429: Rate limit exceeded. Retry after the indicated seconds.
• 400: Validation error, content filter, or suppression list. Error message passed through from API.

All endpoints

Fetch GET /v1/openapi.json for full request/response schemas.

• POST /v1/account create tenant, get API key and mailbox
• GET /v1/account your account info and quota
• PATCH /v1/account update tenant settings (name, oversight email, address)
• DELETE /v1/account permanently delete account and all data (admin scope)
• POST /v1/account/resend-confirmation resend operator confirmation email (rate limited)
• POST /v1/billing/checkout get Stripe payment URL
• POST /v1/billing/crypto-checkout get Coinbase Commerce payment URL
• POST /v1/mailboxes create additional mailbox
• GET /v1/mailboxes list your mailboxes
• POST /v1/mailboxes/:id/send send email as markdown
• GET /v1/mailboxes/:id/emails list inbox (filterable by status)
• GET /v1/mailboxes/:id/emails/:eid get single email with markdown body
• GET /v1/mailboxes/:id/emails/:eid/attachments/:filename download attachment
• POST /v1/mailboxes/:id/reply/:eid reply in-thread
• POST /v1/mailboxes/:id/request-upgrade request oversight mode upgrade (emails code to operator)
• POST /v1/mailboxes/:id/upgrade redeem upgrade code to change oversight mode
• GET /v1/usage usage stats for current period
• GET /.well-known/multimail-signing-key public key for verifying X-MultiMail-Identity signatures

Authentication

Include your API key in every request:

Authorization: Bearer mm_live_...

API keys have scopes: read, send, admin, oversight, oversight_read. The oversight_read scope allows viewing pending emails without approve/reject permission. If a request returns 403, the key lacks the required scope.

---

Support: support@multimail.dev