Purpose and positioning
radmail-mcp is an email operating system for AI agents, provided in the form of a Model Context Protocol (MCP) server, enabling any AI agent to operate an inbox. It does not let agents own or send email on someone's behalf; instead, it provides a "triage and follow-through" capability layer on top of a real person's mailbox: the agent handles sorting, interpretation, commitment tracking, and drafting, while the authority to send always remains with the real person.
The project defines itself as the "fourth form" in the mailbox MCP server category. It differs from three common types of products: application-oriented transactional/lifecycle email sending, end-to-end sending and receiving through agent-owned mailboxes, and authorized access to read and write a real person's Gmail/Outlook via OAuth. radmail-mcp is a "triage and follow-through layer that sits on top of a real person's mailbox."
Main capabilities
- Two-axis triage: Classify email by importance x urgency.
- Right Now channel: Return the email channel that must not be missed right now, including classification, importance, urgency, and reasons.
- commitment follow-through: List unfulfilled commitments, including direction (owed_by_us / owed_to_us), party, action, due date/wording, status, and confidence.
- Reviewable drafts: Drafted by RadMail, sent by a real person, serving as the human review path outside the hard-stop categories.
- Email search and reading: In connected mode, search historical email and read full messages (headers + textBody).
- BEC hard stop (machine-verifiable): Five categories of matters-many, changed-banking, first-contact, decision/sign-off, prompt-injection-are deterministically judged by code as hardStop, are always limited to humans only, and no prompt can make RadMail send automatically.
How to use
Zero-auth hosted sandbox (fastest, no installation, keys, or registration required): Point any MCP client at the streamable-HTTP endpoint; you can also call triage_inbox without a token, and RadMail will automatically assign a free sandbox tenant and return usable triage results in a single round trip, then reuse the returned token.On the zero-auth hosted sandbox, triage_inbox takes no parameters; it triages a built-in demo inbox.
Local stdio method:
npx radmail-mcp
This package is published on npm, and the npx command above can be used directly.
Run from source:
git clone https://github.com/radmail-ai/radmail-mcp && npm i && npm run build && npm start
(stdio). The hosted deployment is a Vercel Node serverless function (api/mcp.ts; / rewritten to the MCP handler).
Connected mode-connect to a real inbox: After setting RADMAIL_API_KEY, the four tools search, read_email, list_right_now, and list_commitments will act on the real mailbox; the optional RADMAIL_API_URL overrides the API host (default https://app.radmail.ai）。密钥以 starts with tmk_, available at https://app.radmail.ai/settings/api-keys created. Connection mode only issues GET requests, is read-only, and never sends, drafts, or modifies real emails.
Applicable scenarios
Suitable for teams that need to delegate company email handling to an agent while retaining human control over high-risk operations. Its security contract is published via /.well-known/agent-safety.json, which proposes three values for enforcementModel: capability-absent (the capability is absent, the tool simply does not exist, cannot be invoked, cannot be configured, cannot be bypassed), config-restricted (the capability exists but is narrowed by configuration, and whoever holds the configuration can widen it again), policy-gated (the capability exists and is constrained by instructions or documented policy). radmail-mcp reports capability-absent for hard-stop categories: the hosted endpoint has no tool with sending capability, sending exists only as a local optional tool, and even if enabled it cannot release withheld emails.
The security contract also includes: taint envelope—all fields originating from the raw email body carry provenance: "untrusted-email-body", and each response includes a safety block reiterating the hard stop; fail-closed—if risk signals cannot be evaluated, automatic sending is refused.
Limitations and caveats
- Not suitable for scenarios where you want the agent to have its own address and reply fully automatically: what radmail-mcp refuses is precisely the capability such requirements demand.
- The local server runs a sandbox engine (heuristic, in-memory, free, no credentials), which is genuinely runnable, but is not the production "99%" engine.
- There is one honest disclosure in the released version (as of 2026-09-30): npm view radmail-mcp dist-tags shows latest: 0.5.0, but the build inside that tarball self-reports 0.4.0 on MCP (dist/ was packaged before the version bump); the repository main has reached 0.5.1 and fixes the root cause (prepublishOnly now rebuilds dist/ before packing), and the corrected package has not yet been published because publishing requires an interactive npm login that only maintainers can perform. The security contract does not depend on the version string.
- How to verify: the security contract is machine-verifiable and can be obtained without an account or keys; you can also read back the tool listto check whether any tool with sending capability exists. The hosted sandbox observed on 2026-10-09 has 6 tools: triage_inbox, list_right_now, why_surfaced, list_commitments, draft_reply, search. Note that grepping by name may falsely match check_send_domain (a read-only SPF/DKIM/DMARC DNS query that sends nothing); you should read each tool's description rather than only looking at names.
- A claim that cannot be inspected externally ("no tool can release a withheld send") is asserted by tests in the repository and can be verified by running the tests; the repository also discloses falsification steps (add one line in src/lib/send.ts and rerun; the second assertion fails and the suite exits non-zero). Observation on 2026-10-05: 3 passed, 0 failed.
