Documentation
MCP server, REST API and security model.
MCP endpoint
https://mailmux.main.zone/mcp
Streamable HTTP, stateless. Supports protocol revisions 2026-07-28 (per-request metadata) and 2025-03-26 through 2025-11-25 (initialize handshake). Authentication: OAuth 2.1 (authorization code + PKCE S256, resource indicators) discovered via
/.well-known/oauth-protected-resource/mcp; clients may register with a Client ID Metadata Document or dynamic registration. Personal API keys are accepted as bearer tokens too.
Permissions
| mail.read | Read email. Search and read messages and attachments in the allowed mailboxes. |
| mail.manage | Organize email. Mark read or unread, flag, move, archive and trash messages. Nothing is ever deleted permanently. |
| mail.draft | Write drafts. Save new messages, replies and forwards into your Drafts folders for you to review. |
| mail.send | Send email. Send email from your addresses. Only works while sending is switched on in Settings. |
Tools
| Tool | Needs | What it does |
|---|---|---|
| list_accounts | mail.read | List the user's connected mailboxes (id, address, provider, status, whether sending is possible). |
| get_overview | mail.read | Unread counts and the latest unread messages for each account's inbox. A good first call for 'what's new in my email?'. |
| search_emails | mail.read | Search one folder across all (or selected) accounts; results are merged newest first with short snippets. query is free text (on Gmail accounts it accepts Gmail search syntax, e.g. 'from:bob has:attachment newer_than:7d'). folder: inbox (default), sent, drafts, archive, trash, junk, all, or a folder path from list_folders. Pass next_cursor back as cursor to get the next page. Message ids are opaque: pass them unchanged to other tools. |
| read_email | mail.read | Read one message: headers, attachments list, and the body as plain text (HTML is converted). Long bodies are paged: pass offset=next_offset to continue. Set mark_read to mark it as read. |
| get_thread | mail.read | All messages of the conversation a message belongs to (oldest first), across inbox, sent and archive where the provider allows. |
| get_attachment | mail.read | Fetch one attachment of a message (part from read_email's attachments). Text-like files are returned as text, images inline; other files (PDF, Office, archives) as a download link valid for 15 minutes that you can give to the user. |
| list_folders | mail.read | List an account's folders with their roles (inbox, sent, drafts, archive, trash, junk) and message counts. |
| update_emails | mail.manage | Mark messages read or unread and/or flagged (starred) or unflagged. Up to 100 ids per call. |
| move_emails | mail.manage | Move messages to "archive", "trash", "inbox", "junk", or a folder path. Archive on Gmail removes the Inbox label. Returns the new ids (ids change when a message moves). Nothing is ever deleted permanently. |
| create_draft | mail.draft | Write a draft (new message, reply, or forward) into the account's Drafts folder, where the user can review and send it from their own mail app. Prefer this over send_email unless the user explicitly asked you to send. |
| send_email | mail.send | Send an email (new, reply, forward, or an existing draft via draft_id) through the account's own mail server. Only when the user explicitly asked to send; confirm recipients and content first. Fails if the user has not turned on sending in their settings — then use create_draft. |
REST API
Send Authorization: Bearer <API key>. JSON in, JSON out; errors are {"error": {"code", "message"}}.
GET /api/v1/accounts
GET /api/v1/overview?accounts=a,b
GET /api/v1/messages?q=&folder=&from=&to=&subject=&since=&before=&unread=1&flagged=1&attachments=1&limit=&cursor=
GET /api/v1/messages/{id}?format=text|html|both&max_chars=&offset=&mark_read=1
GET /api/v1/messages/{id}/thread
GET /api/v1/messages/{id}/attachments/{part}
GET /api/v1/accounts/{account}/folders
POST /api/v1/messages/update {"ids": [...], "read": true, "flagged": false}
POST /api/v1/messages/move {"ids": [...], "destination": "archive"}
POST /api/v1/drafts {"account", "to", "cc", "bcc", "subject", "body", "reply_to_id", "forward_id"}
POST /api/v1/send {... same as drafts, or "draft_id"}
POST /api/v1/tools/{tool} any MCP tool with its JSON arguments
Rate limit: about two requests per second per user with bursts of 120.