@mailslot/core

Mailslot

A real inbox for AI agents. Self-hosted.

On your own Cloudflare account, on your own domain. The open-source alternative to hosted agent-email APIs.

┌─────────────────────────── your Cloudflare account  ───────────────────────────┐
│                                                                                │
│  any sender ──▶ Email Routing ──▶ one Durable Object per address               │
│                                      │  parse · store · read-once state        │
│                                      ├──▶ MCP server   ◀── Claude / OpenClaw   │
│                                      ├──▶ HTTP API     ◀── your code           │
│                                      ├──▶ webhook      ──▶ n8n / Make          │
│                                      └──▶ forward()    ──▶ your real inbox     │
│                                                                                │
└── nobody else's servers. nobody else's eyes. ──────────────────────────────────┘

Why

Give an agent real work and it eventually needs to receive email. Sign up for a service, there's a verification link. Log in, there's an OTP. Register an account, reset a password, collect an invoice. The loop always closes through an inbox.

Across the automation and agent systems I've worked on, the same wall comes up every time. The agent is fully capable of the task, and then it stalls at "check your email." The existing options are both bad in the same way. Either you hand the agent the keys to your personal Gmail, or you rent an inbox from a hosted API that reads everything passing through it.

So Mailslot is the third option. It's your agent's inbox, deployed to your Cloudflare account in about ten minutes. Mail lands on your domain, gets parsed and stored on your own infrastructure, and only your agents can read it.

The privacy here isn't a policy you have to trust. It's the architecture. The mail never passes through anything of mine, because there is nothing of mine in the path. No "we," just your account.

What your agent can do

Exposed three ways, same engine:

• MCP server: point Claude, OpenClaw, or any MCP client at it
• HTTP API: token-auth REST for your own code
• Webhooks: message.received pushed to n8n, Make, or anything with a URL

Quick start

npx create-mailslot

Ten minutes, interactively. It scaffolds a project you own, provisions storage and an API token, deploys the worker, walks you through Email Routing setup (a Cloudflare API token, or guided dashboard steps with live DNS verification), and finishes with a live round-trip. Send an email from your phone, watch it arrive in your terminal. Flags for non-interactive use are in the wizard's README.

Requirements: Node 18+, a Cloudflare account (free tier works), and a domain on Cloudflare.

⚠️ Domain reality check (the wizard enforces this): Email Routing is zone-level. If a domain's apex already receives mail elsewhere (Google Workspace, Lark, O365, and so on), that domain cannot host Mailslot at all, not even on a subdomain, without breaking its existing mail. Use a separate domain. (Subdomains work fine on zones where Email Routing is already enabled.)

git clone https://github.com/mailslot/mailslot && cd mailslot && npm install
cd packages/core

# 1. Storage + auth (one-time)
npx wrangler r2 bucket create mailslot-raw
openssl rand -hex 24 | npx wrangler secret put MAILSLOT_TOKEN   # keep a copy!

# 2. Deploy, baking in your mail domain (persists across future deploys)
npx wrangler deploy --var EMAIL_DOMAIN:mail.example.com

3. Enable Email Routing on your domain in the Cloudflare dashboard (zone → Email Routing), respecting the domain reality check above.

4. Point mail at the worker: Email Routing → Routing rules → Catch-all → action Send to a Worker → mailslot → Enabled.

5. Round-trip test:

TOKEN=<your token>
WORKER=https://mailslot.<your-subdomain>.workers.dev

# mint an address, send any email to it, then:
curl -s "$WORKER/v1/inboxes/<address>/wait?timeout_s=90" \
  -H "Authorization: Bearer $TOKEN"

Config lives in two instance-specific values that survive every deploy (keep_vars): EMAIL_DOMAIN (a var, editable in the dashboard) and MAILSLOT_TOKEN (a secret). The repo's wrangler.jsonc stays generic. Optional: FORWARD_TO plus FORWARD_MODE=all (copy mail to a verified address), and WEBHOOK_URL / WEBHOOK_SECRET (signed message.received events).

Connect an agent (MCP)

claude mcp add mailslot $WORKER/mcp \
  --transport http --header "Authorization: Bearer $TOKEN"

The canonical demo

An agent signs itself up for a service, end to end:

agent: create_address()            → [email protected]
agent: (signs up at the service using that address)
agent: wait_for_message(timeout=120)
agent: extract_otp()               → "482913"   [marked read-once]
agent: (submits the code, done)

No human inbox touched. No credentials shared. The address is disposable. Mint a new one per task.

Why self-hosted

Hosted APIs are a fine product. This is for the people and companies for whom "a third party processes all my agent's mail" is a non-starter: self-hosters, automation agencies deploying for clients, and anyone whose compliance team asks where the data lives.

Built on

• Cloudflare Email Routing: the SMTP edge, no port 25 and no mail server to run
• Cloudflare Agents SDK: one Durable Object per inbox (routeAgentEmail, onEmail), McpAgent for the MCP surface
• postal-mime: MIME parsing built for Workers

Standard Cloudflare stack, thin on top. If you can maintain a Worker, you can maintain this.

Integrations

• MCP: works with any MCP client today (Claude Code, Claude Desktop, OpenClaw, custom agents)
• n8n: community node (trigger + actions), in progress
• OpenClaw skill: points at your instance, not a hosted cloud, in progress

Adapters are thin wrappers over one versioned event schema and one tool API. Want an adapter that isn't here yet? The contract is small, so PRs are welcome.

Roadmap

• v1: receive → parse → store → MCP/HTTP tools → webhooks → forward
• create-mailslot deploy wizard
• onStored(email, message) extension hook: subclass Inbox for custom per-deployment logic. Core stays a clean library with no business logic; the live instance (@mailslot/instance) uses the hook for return-receipt auto-replies (replyToEmail, no ESP). See instance/README.
• n8n community node, OpenClaw skill

Deliberately not planned: hosted multi-tenant service, AI triage of your personal mail, reading anything it doesn't have to. Boring, auditable plumbing.

Need it deployed for you?

I do fixed-price integrations. Your domain, your Cloudflare account, wired into your n8n or agent stack, with a handover doc. Email [email protected] and tell me what you're building.

License

MIT