All notable changes to @multimail/mcp-server will be documented in this file.
Removed the ai_disclosure parameter from create_mailbox, update_mailbox, and configure_mailbox. AI transparency marking — the signed ai_generated claim in X-MultiMail-Identity, the X-AI-Generated: true header, and the visible disclosure footer line — is injected at the send gateway on every agent-originated email and can no longer be disabled. API calls setting ai_disclosure: false are rejected with 400; true is accepted as a no-op. Templated system notifications (not AI-generated content) remain unmarked.
Optional ucan parameter on the send_email and reply_email tools. When supplied, MultiMail relays the agent's self-signed UCAN (base64url, up to 11008 chars) verbatim in a separate X-Agent-Identity email header alongside the agent's bound did:key. MultiMail signs nothing and vouches for nothing — recipient tooling verifies the delegation independently. Inert unless the sending account has a bound agent DID.
The signup tools (request_challenge / create_account / activate_account) no longer require an API key, so an agent can create its own MultiMail account before it has credentials (#130).
Splits 4 tools that mixed safe (GET) and unsafe (POST/PUT/DELETE) HTTP methods into 10 single-method tools to satisfy Claude connector directory review criteria. Each tool now uses exactly one HTTP method.
Migration table:
| Old tool | New tools |
|---|---|
tag_email |
get_tags (GET), set_tags (PUT), delete_tag (DELETE) |
manage_contacts |
search_contacts (GET), add_contact (POST), delete_contact (DELETE) |
manage_suppression |
list_suppression (GET), remove_suppression (DELETE) |
manage_webhooks |
list_webhooks (GET), delete_webhook (DELETE) |
manage_upgrade(POST+POST) andmanage_spam_status(POST+POST) are not split — both actions use the same HTTP method class.
- Structural prompt-injection isolation for
list_pending— email bodies are now extracted from the metadata JSON and wrapped in--- BEGIN UNTRUSTED EMAIL BODY ---/--- END UNTRUSTED EMAIL BODY ---markers (matchingread_emailpattern). Previously bodies were returned inline with trusted metadata. - Structural
--- UNTRUSTED FIELDS WARNING ---block appended tocheck_inbox,get_thread,list_pending,list_spam, andwait_for_emailresponses, annotating subject lines and sender addresses as untrusted external content. - All isolation patterns applied to both stdio and remote MCP servers.
Consolidates 12 single-purpose tools into 5 action-enum tools, drops schedule_email, and adds report_issue. Net reduction: 50 → 44 tools (~1,500 fewer tokens in context window).
Migration table:
| Old tool(s) | New tool | Action parameter |
|---|---|---|
add_contact, search_contacts, delete_contact |
manage_contacts |
add | search | delete |
check_suppression, remove_suppression |
manage_suppression |
check | remove |
request_upgrade, apply_upgrade |
manage_upgrade |
request | apply |
report_spam, not_spam |
manage_spam_status |
report | clear |
list_webhooks, delete_webhook |
manage_webhooks |
list | delete |
schedule_email |
(removed — use send_email with send_at) |
— |
report_issuetool — report tool bugs, site problems, or feature requests directly from MCPPOST /v1/feedbackendpoint — durable feedback ingestion with email notification- Prompt injection warnings on
send_email(untrusted email bodies) andmanage_spam_statusclear action
- All merged tools use action-enum pattern (same as existing
tag_email) - Tool annotations use most-permissive classification across merged actions
manage_allowlisttool — add, list, or remove per-mailbox sending allowlist entriesget_allowlist_statustool — check if a recipient is on the allowlistset_allowlist_modetool — set allowlist enforcement mode (enforce|monitor|off)- Allowlist bypass gating on
send_email— blocked sends return actionable remediation
- Add title and annotations on all tools for directory submission readiness.
- Add security.txt, security policy, and submission assets.
- Migrate to @modelcontextprotocol/sdk 1.29.0 (server.tool → server.registerTool, Zod v4 in the remote server)
- Upgrade remote MCP server runtime (0.5 → 0.11.4)
- Fix tool-count claim in setup_multimail (40 → 43)
- Unify mailbox_id parameter description across stdio and worker
- No tool API changes
- Block
send+oversightscope combinations on API keys. Prevents the self-approval attack where a single key can both compose and approve emails, bypassing thegated_sendoversight model. Applies to bothPOST /v1/api-keyscreation andPATCH /v1/api-keys/:idscope updates. - Gate oversight scope escalation behind operator approval. Adding the
oversightscope to an existing key now requires the admin-action approval flow, closing the escalation path that bypassed the scope combination block. - Remove
webhook_urlandoversight_webhook_urlfromupdate_mailbox. Webhook URLs can only be set viacreate_webhookwhich requires operator approval. Prevents the silent event exfiltration path. - Timing-safe upgrade code verification — replaced
===string comparison withcrypto.subtle.timingSafeEqualinverifyUpgradeCode. Eliminates the timing side channel on approval code checks. - MCP tool descriptions updated with prompt injection warnings on
update_mailbox,update_account,configure_mailbox,edit_scheduled_email, andget_thread.
- Phases 3-4 (auto_bcc gating, oversight_email confirmation, recipient edit blocking) will follow in a subsequent release.
request_challengetool — request an ALTCHA proof-of-work challenge for account creationcreate_accounttool — create a MultiMail account with a solved PoW challenge/onboardpublic MCP endpoint on remote worker — agents can sign up without OAuth- PoW enforcement on
POST /v1/account— proof-of-work is now required for all signups
- stdio MCP server starts without
MULTIMAIL_API_KEY— registers 4 onboarding tools (request_challenge, create_account, activate_account, resend_confirmation) resend_confirmationuses direct fetch instead of authenticated API call (works without API key)- MCP server description updated to reflect trust-ladder positioning
ai_disclosureparameter oncreate_mailbox,configure_mailbox, andupdate_mailboxtools — enables EU AI Act Article 50 compliance by includingai_generatedfield in signed identity claimsai_disclosurefield returned inlist_mailboxesresponsesX-AI-Generated: trueconvenience header on outbound emails from AI-operated mailboxestamper_evident_ai_generatedLean 4 theorem proving AI disclosure field is tamper-evident
X-MultiMail-Identitysigned claim now includesai_generatedboolean (first field in sorted canonical JSON)- Email body signature block includes "This email was sent by an AI agent." when
ai_disclosureis enabled - System notification emails explicitly set
ai_generated: false
read_emailnow separates trusted metadata from untrusted email body into distinct content blocks, preventing prompt injection via email content- Tool descriptions for
read_email,reply_email, andsend_emailinclude warnings that email bodies are untrusted external content - Webhook creation, API key creation, and mailbox creation now require operator approval via email code (prevents injected agents from creating exfiltration webhooks or escalating privileges)
- Identity header serialization uses sorted-key canonical format (deterministic by construction)
GET /v1/proof-statusendpoint — returns Lean 4 proof verification timestamp
read_emailresponse now returns two content blocks: metadata (trusted) and body (untrusted with explicit framing)- New mailbox creation returns 202 with approval code flow instead of immediate 201
download_attachmentnow returns presigned URLs for attachments >50KB (1-hour expiry). Small files still return inline base64.- Presigned URL API endpoint:
GET /v1/mailboxes/:id/emails/:emailId/attachments/:filename/url
- Email parser now preserves original body in forwarded and replied messages
- Strips
Fwd:andRe:prefixes from inbound email subjects
- Deduplicated a build-time dev dependency (shared via root)
schedule_emailtool — schedule an email for future delivery with a requiredsend_attime. Edit or cancel before it sends.configure_mailboxtool — set up mailbox preferences: oversight mode, display name, CC/BCC defaults, scheduling, signature. Soft-nudge on first use if mailbox is unconfigured.edit_scheduled_emailtool — edit a scheduled email's delivery time, recipients, subject, or body before it sendssend_emailnow also accepts optionalsend_at(ISO 8601) for scheduled delivery andgate_timing(gate_firstorschedule_first) for oversight orderingcheck_inboxstatus filter now includesscheduledcancel_messagenow works on scheduled emails- First-run onboarding: soft nudge when mailbox is unconfigured (action still executes,
setup_requiredflag is informational)
- Tool count: 35 → 38
wait_for_emailtool — block until a new email arrives matching optional filters, or timeout. Polls internally usingsince_idevery 3 seconds. Supportstimeout_seconds(5–120, default 30) and optionalfilterwithsenderandsubject_contains. Returns immediately when mail arrives.create_webhooktool — create a webhook subscription for real-time email event notifications (message.received, message.sent, message.delivered, message.bounced, message.complained, oversight.pending, oversight.approved, oversight.rejected). Returns signing_secret for payload verification.list_webhookstool — list all webhook subscriptions for this accountdelete_webhooktool — delete a webhook subscription by ID
- Tool count: 31 → 35
get_accounttool — check account status, plan, quota, enforcement tiercreate_mailboxtool — create new mailboxes (requires admin scope)request_upgradetool — request oversight mode upgrade (trust ladder entry point)apply_upgradetool — apply upgrade code from operator approval emailget_usagetool — check quota and usage stats for billing periodlist_pendingtool — list emails awaiting oversight decision (requires oversight scope)decide_emailtool — approve or reject pending emails (requires oversight scope)delete_contacttool — delete a contact from address bookcheck_suppressiontool — list suppressed email addressesremove_suppressiontool — remove an address from suppression listlist_api_keystool — list all API keys (requires admin scope)create_api_keytool — create API key with scopes (requires admin scope)revoke_api_keytool — revoke an API key (requires admin scope)get_audit_logtool — get account audit log (requires admin scope)delete_accounttool — permanently delete account and all data (requires admin scope)send_emailandreply_emailnow acceptattachmentsparameter (base64-encoded files)check_inboxnow supportscursorpagination parametercheck_inboxstatus filter expanded to all 9 API-filterable statuses
send_emailandreply_emaildescriptions now correctly referencepending_scanandpending_send_approval(waspending_approval)cancel_messagedescription now mentionspending_scanas a valid cancelable status- 429 error messages now distinguish warmup limits, quota exceeded, and rate limits
- Tool count: 16 → 31
send_emailandreply_emailnow returnpending_scanstatus — emails are scanned for threats before delivery- Tool descriptions updated to mention
pending_scanas a non-retryable status
download_attachmenttool — download email attachments as base64 with content typeget_threadtool — retrieve full conversation thread with participants and metadatacancel_messagetool — cancel pending emails awaiting oversight approvaltag_emailtool — set, get, or delete key-value tags on emails (agent persistent memory)add_contacttool — add contacts to address book with optional tagssearch_contactstool — search address book by name or emailcheck_inboxnow supports filtering:sender,subject_contains,date_after,date_before,direction,has_attachments,since_id,limitsend_emailandreply_emailnow acceptidempotency_keyto prevent duplicate sends (24h TTL)- Reply endpoint now has SHA-256 dedup (60s window), matching send behavior
- API responses now include
delivered_at,bounced_at,bounce_type,approved_at,approved_by - Thread tracking: send generates thread_id, reply inherits it, inbound looks up parent
cancelledemail status for cancelled pending messages- Email tags (key-value pairs) included in read_email response
- Contacts API with search
- Tool count: 10 → 15
update_accounttool — change org name, oversight email, physical address (requires admin scope)update_mailboxtool — change display name, oversight mode, signature block, webhooks, and moredelete_mailboxtool — permanently delete a mailbox (requires admin scope)- Remote MCP server at
mcp.multimail.dev/mcp— no install needed, OAuth authentication
- Email footer redesigned: multi-line format with human-readable oversight descriptions
- README now shows remote server as recommended Option A
delete_mailboxtool (requires admin scope)
update_mailboxtool — update display name, oversight mode, signature block, webhooks
bccparameter onsend_emailandreply_email
search_identitytool — identity is now delivered via signedX-MultiMail-Identityemail header
activate_accounttool — activate account using confirmation code- Reputation hash via
X-MultiMail-Reputationemail header
resend_confirmationtool — resend operator activation email
read_onlymode documentation — send/reply now return 403 with upgrade instructions
- Initial public release
- Tools:
list_mailboxes,send_email,check_inbox,read_email,reply_email