Mailroom

Give every project email address one private inbox your agent can use safely.

Mailroom receives email through Cloudflare and exposes bounded tools for reading, searching, drafting, and replying. Original messages stay archived, and sending always needs a separate approval.

Start with deployment · How it works · Documentation · Questions · Security · License · Agent notes

Project email tends to end up in a personal inbox, a shared login, or a service that gives automation far too much access. Mailroom gives the mail one private home and exposes small, named operations instead of an open-ended inbox and send button.

It is built for people who own their domains, are comfortable running Cloudflare infrastructure, and want to use project email from a terminal or local agent. There is no hosted Mailroom account and no web inbox.

What Mailroom gives you

• Exact email routes by default, with deliberate catch-all support.
• Original .eml files and attachments archived in R2.
• Threads, messages, drafts, approvals, and delivery history stored in D1.
• Search through Cloudflare AI Search with a D1 full-text fallback.
• One CLI for normal use and a typed API for scripts.
• Three compact MCP tools that discover and run the same operations.
• A hard boundary between creating a draft, approving it, and sending it.
• Optional Gmail forwarding and Sent-mail synchronization.
• A signed relay for domains owned by another Cloudflare account.

Start with one mailbox route

Mailroom is self-hosted email infrastructure, so the first setup is more involved than installing a normal CLI. The deployment guide starts with an empty Cloudflare account and ends with a live Worker, connected CLI, and one tested route.

Clone the repository and run its checks first:

git clone https://github.com/iannuttall/mailroom.git
cd mailroom
pnpm install
pnpm lint
pnpm typecheck
pnpm test
pnpm build:package

Then follow the deployment guide in order:

1. Choose the Cloudflare account that will own the mailbox.
2. Create D1, R2, Queue, and AI Search resources.
3. Add private Worker configuration and secrets.
4. Apply the migration and deploy the central Worker.
5. Connect the CLI and create the first domain, address, and route.
6. Test inbound mail before changing any important MX records.

The npm package is not published until the first tagged release. During development replace mailroom in the examples with node dist/cli.js.

Read and search from the terminal

Log in once with the Worker URL and API token:

mailroom auth login
mailroom status

On macOS the token goes into Keychain. The local config stores only the Worker URL and profile name.

Everyday commands stay small and predictable:

mailroom messages --status unread
mailroom read <message-id>
mailroom search "sponsorship"
mailroom drafts --status pending

Non-interactive environments can use MAILROOM_API_URL and MAILROOM_API_TOKEN instead of Keychain.

Give an agent bounded email tools

Mailroom does not dump its full API into an agent context. Its MCP server exposes three tools:

• mailroom_list_operations discovers compact operation IDs.
• mailroom_describe_operation returns one schema and its safety metadata.
• mailroom_run_operation validates and runs that operation.

Full message bodies, threads, attachment metadata, and prompt bodies are opt-in. An agent has to ask for the operation it needs rather than receiving the entire mailbox by default.

Print a stdio client configuration with:

mailroom mcp config

Install the packaged Mailroom skill through the standard Skills CLI:

npx skills add iannuttall/mailroom

The skill teaches agents how to search, inspect a message, prepare a draft, request approval, and send only the approved result.

Sending requires a real approval

Email bodies and attachments are untrusted input. Automation is disabled in the shipped configuration, and classification tests cannot store drafts or send mail.

Creating a draft, approving it, and sending it are separate operations. Outbound attempts are recorded before delivery and require an idempotency key. Drafts can contain normal email content, including currency symbols and web links.

Secrets belong in Wrangler secrets or the macOS Keychain. Do not put them in Worker variables, configuration files, fixtures, logs, issues, or prompts. SECURITY.md covers private vulnerability reporting and the trust boundaries in more detail.

Keep Gmail as the human inbox

Mailroom can forward stored inbound mail to a verified Gmail destination. The included Apps Script sends manual Gmail replies back to the correct Mailroom thread, so the archive and delivery history stay complete.

This is optional. Mailroom remains the source of mailbox state, while Gmail is the familiar human reading and reply surface. The Gmail setup guide covers forwarding, SMTP, Send As, the Sent-mail sync, and mobile behavior.

How mail moves through the system

Cloudflare Email Routing
          |
          v
central Worker --> R2 original mail + pending recovery marker
       |
       +--> optional verified Gmail destination
       |
       +--> Queue --> D1 messages, threads, drafts, approvals, audit trail
                    R2 attachments
                    AI Search compact search documents
             ^
             |
       five-minute recovery sweep
       |
       +--> private operations API
                 |
                 +--> mailroom CLI
                 +--> stdio MCP: list, describe, run

Domains in another Cloudflare account use the small apps/ingress relay. The relay is a stateless mini Worker deployed in the account that owns the domain, not another Mailroom inbox. It signs inbound MIME before passing it to the central Worker, forwards accepted messages to a verified Gmail destination in the domain account, and sends outbound mail through that account's Email Service binding. Inbox state, threads, drafts, and the raw archive remain in central Mailroom. Manual Gmail replies use Cloudflare SMTP directly; they do not pass through the relay Worker.

The architecture notes explain the storage model, recovery path, authentication, search fallback, and account boundaries.

What you need

• Node.js 22.19 or newer.
• pnpm 11.
• A Cloudflare account using Cloudflare DNS for each mail domain.
• D1, R2, Queues, Workers AI, and AI Search in the central account.
• Cloudflare Email Routing for inbound mail.
• Workers Paid when Mailroom must send to arbitrary recipients.

Cloudflare Email Sending is still a beta service. Check Cloudflare's current Email Service pricing before deploying.

Follow the setup in order

The documentation index keeps the setup sequence and account choices in one place.

| Guide | What it helps you finish | | --- | --- | | Deploy Mailroom | Cloudflare resources, secrets, Worker deployment, CLI login, and the first route. | | Configure Mailroom | Bindings, variables, secrets, tokens, and local state. | | Use Gmail | Forwarding, Cloudflare SMTP, Send As, Apps Script, and mobile behavior. | | Test the installation | Storage, search, routing, threading, drafts, Gmail, and failure recovery. | | Move a mail domain | A safe MX cutover with monitoring and rollback. | | Fix setup failures | Worker, routing, SMTP, and Apps Script errors. | | Use an installation agent | Terminal work, authenticated browser handoffs, and stop conditions. |

Develop locally

pnpm install
pnpm build
pnpm typecheck
pnpm test
pnpm lint
pnpm test:package-install
pnpm security:check
pnpm pack:check

The build includes dry-run deployments for both Workers. The package test checks the public API, CLI, MCP entry point, packaged skill, prompts, integrations, policy files, and clean-install behavior.

The repository is split by runtime boundary:

packages/core                 schemas, operations, validation, signing
packages/cli                  local CLI and Keychain authentication
packages/mcp                  stdio MCP server
apps/worker                   central mailbox Worker
apps/ingress                  cross-account email relay
integrations/gmail-sent-sync  user-owned Apps Script
migrations                    D1 schema
prompts                       versioned agent instructions
config                        safe automation examples
skills/mailroom               packaged agent workflow

Read CONTRIBUTING.md before sending a change. AGENTS.md records the product contracts and runtime boundaries that are easy to break accidentally.

Common questions

Is Mailroom a hosted email service?

No. You deploy it into your own Cloudflare account and keep control of the Worker, storage, domains, and secrets.

Can an agent send mail without approval?

The shipped configuration does not allow it. Draft creation, approval, and delivery are separate operations, and every outbound attempt is recorded before delivery.

Does Mailroom replace Gmail?

It can, but it does not have a web inbox. Gmail can remain the human interface while Mailroom keeps the original mail, routing state, search index, agent operations, and audit history.

Why does Mailroom need a Worker?

The Worker is the mailbox runtime. It receives messages from Cloudflare Email Routing, archives the original MIME, queues processing, exposes the private operations API, and sends approved replies. Unlike a local CLI wrapper, that work has to run where the email arrives.

Can domains in different Cloudflare accounts share one Mailroom?

Yes. Deploy the signed ingress relay in each additional account. Inbox state still stays in the central account.

License and project policy

Source code is available under the Apache 2.0 License. PRIVACY.md, TERMS.md, and TRADEMARKS.md cover the public project policies.