Giving every AI agent its own mailbox: the architecture behind a self-hosted MCP mail server

A developer built openagent.email, a self-hosted mail server that gives each AI agent its own mailbox on a user-owned domain. The architecture uses a single catch-all mailbox with logical identities, filtering mail by exact recipient header matching to prevent cross-agent access. The stack runs as two containers, idles at ~190 MB RAM, and includes 268 automated tests.

My agents keep needing to read email. Signup codes, verification links, password resets: every automated workflow that touches a third-party service eventually hits an inbox. There are hosted APIs for this, and they work fine until you think about what's actually in those emails. In a signup flow, the message with the verification code is the account credential. Every one of them passes through someone else's servers. So I built openagent.email https://openagent.email : a self-hosted mail server where every agent gets its own mailbox on a domain you own. It runs as two containers, a catch-all Postfix/Dovecot mailbox docker-mailserver https://github.com/docker-mailserver/docker-mailserver and a small Node/Hono API, with an MCP server on top so any MCP client Claude Code, Cursor, Windsurf... can use it. The whole stack idles at about 190 MB of RAM on my production instance, and it has 268 automated tests. This post is about the design decisions that make it work, because most of them are not the obvious ones. The naive design is one mailbox per agent. Provisioning mailboxes in Dovecot per agent is slow, stateful, and pointless. Agents don't need IMAP folders; they need an address and a way to read what lands on it. So there's exactly one real mailbox: a catch-all. Postfix aliases @yourdomain to a single account, so anything@yourdomain delivers to the same place. An "identity" is just a logical address plus a token. Creating one is a POST that takes milliseconds and touches no mail server config. This makes identity creation free, which changes how you use the system. Every test run, every signup flow, every throwaway experiment gets a fresh address. Identities are cheap enough to be single-use. But it creates the real problem: if all mail lands in one mailbox, how does an identity see only its own mail? When the API reads mail for an identity, it filters the catch-all by recipient headers: the envelope To / Cc / Bcc plus the Delivered-To header that Postfix stamps on every message. The match is exact string equality on the full address. Never a substring. That sounds paranoid until you look at what substring matching does. Say agent A owns k7d2@d and agent B owns fox-k7d2@d . A substring match lets A read B's mail. Worse: Postfix stamps Delivered-To: agent@d the catch-all account on every message, so a liberal match on that header means reading the entire mailbox. The address comparison is the only thing standing between "your mail" and "everyone's mail", so it can't be approximate. A few smaller traps fell out of the same code path: Name <mailbox , only the address inside the brackets grants access, because a display name can itself be crafted to look like an address. The parser also strips RFC 5322 comments with a bounded loop, since unbounded parsing of hostile headers is its own DoS. delivered-to , x-original-to , envelope-to , x-forwarded-to , to , cc , bcc , and the fetcher currently only requests delivered-to on top of the envelope. The whitelist exists so that widening the fetch later doesn't silently widen the trust boundary. Subject and random X- headers never grant anything. wait for . Sorting uses the server's INTERNALDATE first. +tag handling. Identity localparts don't allow + at all, and matching is exact, so fox-k7d2+signup@d is simply invisible to fox-k7d2@d . I'd rather have an explicit blind spot than a clever aliasing rule that becomes an attack surface.Each identity gets one token: oa plus 24 random bytes, base64url, 192 bits of entropy. The server stores only the SHA-256 hex; the plaintext is returned exactly once, at creation or rotation. Three details worth copying: timingSafeEqual . Token comparison is a dumb place to leak timing, but it's also a one-liner to do right. forbidUnlessAddress guard. The MCP server adds no permissions of its own; it's a thin stdio wrapper over the REST API, and all authorization lives server-side.The token store itself is boring and paranoid: a JSON file in a 0700 directory, 0600 permissions, written via tmp-file plus atomic rename. If it's corrupt, the code fails closed. It throws instead of "helpfully" treating the store as empty, which would risk overwriting everyone's tokens. The feature agents actually love is that messages come back with one-time codes and verification links already parsed. The extractor is a pure function with no I/O, which is why it has 44 test cases and I trust it. The rules are simple; the edges are not: code , verification , otp , passcode , plus the Chinese and Japanese equivalents appears within an 80-character window around them. 19xx / 20xx need a � are dropped rather than "recovered" into a fake 8-digit code. <a tags: anchor text like "Verify your email" can qualify an otherwise neutral URL. The intent regex verif|confirm|activate|reset|signin|login can hit either the URL or the anchor text. G-<span 77</span <span 4102</span must read as G-774102 .The call that makes automated signups practical is wait for : the agent says "tell me when mail arrives for this address" and blocks. Implementation-wise it's a long-lived IMAP connection doing: loop: re-check the mailbox latest 20 matching, then from/subject filters if no match: race client.idle , sleep 3000 IDLE gives instant wakeup when Dovecot sees new mail; the 3-second heartbeat covers the case where the IDLE event is silently lost. If the IDLE connection itself dies, the code degrades to plain 3-second polling on one-shot connections. One capacity decision hides here. Every wait pins an IMAP connection for up to 10 minutes, and all identities share one Dovecot account. Dovecot's default per-IP connection limit is 10, so waits are capped at 3 per address, 8 globally, deliberately below 10 to leave headroom for the short-lived reads. Excess waits get a 429 with retryAfterSec: 5 , which the MCP client surfaces as a clean retry hint instead of a mystery failure. Agents get the raw HTML. They're parsers, and sanitizing for them would only destroy information the OTP extractor already ran . The danger is the other path: the /ui dashboard, where a human opens the same message in a browser. The intuition "sanitize the HTML twice" is wrong, and it's not what the code does. It does one thing three ways: colspan / rowspan on table cells, zero allowed URL schemes, script/style/iframe/svg/template dropped with their contents, and a hard 512 KB cap. sandbox iframe with no permissions at all. default-src 'none'; script-src 'none'; img-src 'none' . Even if the sanitizer misses something, there's no script execution and no network egress.Also worth noting: the upgrade path for that sanitizer is "bump it in its own PR and re-run the poison-message corpus." Security dependencies that parse hostile input don't get ride-along upgrades. A few things that don't demo well but matter when it's your box: \Deleted plus expunge. First run waits 60 seconds for Dovecot to finish starting; errors are logged, never fatal. v runs the full test suite, checks that the tag, package.json , and server.json versions all agree, then publishes to npm with --provenance via OIDC trusted publishing no long-lived npm token anywhere and to the official MCP registry in the same workflow. cp .env.example .env , set your domain, docker compose up .The project is Apache-2.0: github.com/openagentemail/openagentemail . The MCP server is npx -y @openagentemail/mcp against any running instance. Point your domain's MX at a $5 VPS and every agent you run gets a real inbox on your own domain.If you're building agents that sign up for things, I'd genuinely like to hear how the wait-for flow works for you. Issues and PRs welcome.