DearAgent: email inboxes for AI agents, self-hosted on Cloudflare
Your agent needs an email address. DearAgent gives every agent its own inbox, running entirely on your Cloudflare account. Receive inbound email, wait for the verification code, reply in thread, send new mail, and get a webhook when something arrives. One Worker, one repo, no servers.
It is the open-source, self-hosted alternative to : the same idea, an email inbox API for AI agents, run on your own infrastructure for the cost of a Workers plan.
Email inbox API for AI agents, self-hosted on Cloudflare Workers. Open source, with an MCP server. AgentMail alternative.
Experimental. DearAgent is early software. It works end to end, but it has not had an in-depth audit, the API may still change, and things may break. Review the code and run your own audit before pointing it at anything sensitive or exposing it to untrusted agents.
What it looks like from the agent
> create_inbox {}
✓ [email protected]
# hand the address to the signup form
> wait_for_message { inbox: "[email protected]", timeout: 25 }
✓ from: Pied Piper <[email protected]>
subject: Your verification code
text: "Your code is 493021. It expires in 10 minutes."
The same operations exist over REST. Under the hood:
You do not need to deploy anything to see it work. dearagent.sh creates a real inbox for you on the public demo instance when the page loads. Send it an email from anywhere and watch it arrive on the page. Demo addresses live for fifteen minutes and demo mail is not kept.
Features
Catch-all inboxes. Any address at your domain works immediately. Inboxes are created implicitly on first email or explicitly via POST /inboxes (with a random address if you want one).
Threads. Messages are grouped by In-Reply-To / References, never by subject, so automated mail does not get merged.
Full-text search (SQLite FTS5) over subject, body and sender.
Attachments stored in R2 and served back with the right content type. Inline images are distinguished from real attachments.
Send, reply, reply-all, forward with correct threading headers, via the native Email Sending binding.
Webhooks on message.received and message.sent, HMAC-signed, retried, with a per-webhook delivery log.
Email MCP server at /mcp so Claude Code, Cursor, or any MCP client can use an inbox as a tool, including wait_for_message to block until mail arrives.
Retention. Daily purge after RETENTION_DAYS, plus per-address TTLs (signup.ttl.600@… expires after 600 s).
Why self-host
Hosted inbox APIs
DearAgent
Where mail lives
Their cloud
Your Cloudflare account: D1 for mail, R2 for attachments
What it costs
A plan with per-inbox or per-message limits
Your Workers bill. Receiving runs on the free plan
Source
Closed
One repo you can read, tests that run in the real Workers runtime
Tenancy
Multi-tenant, per-agent keys
Single-tenant, one API key. Put it behind your own auth for per-agent scoping
Requirements
A Cloudflare account.
An apex domain that receives no mail today, dedicated to Cloudflare Email Routing. See Which domains work.
Workers Paid, only if you send. Receiving is free.
cp wrangler.example.jsonc wrangler.jsonc # wrangler.jsonc is git-ignored; it holds your values
npx wrangler d1 create dearagent # paste database_id into wrangler.jsonc
npx wrangler r2 bucket create dearagent-attachments
# edit wrangler.jsonc: set EMAIL_DOMAINS to "example.com" and addresses to ["*@example.com"]
npx wrangler d1 migrations apply dearagent --remote
npx wrangler secret put API_KEY # any long random string
npx wrangler email routing enable example.com
npx wrangler email sending enable example.com # only needed to send/reply; Workers Paid
npx wrangler deploy # also creates the catch-all routing rule from `addresses`
The addresses entry in wrangler.jsonc declares the Email Routing rules this Worker owns; *@example.com is the catch-all. wrangler deploy prints an "Email Routing plan" and applies it, so no separate rule command is needed. If your wrangler is older than 4.131 and ignores addresses, set the catch-all in the dashboard: Compute & AI → Email Service → Email Routing → your domain → Routing rules → Catch-all → Send to a Worker → dearagent.
Which domains work
Use an apex domain that you can dedicate to Cloudflare Email Routing, such as example.com. Email Routing is configured on the apex zone and must own its MX records, so a domain that already receives mail elsewhere (Google Workspace, Fastmail, …) cannot be used: Cloudflare refuses to onboard it with "Non-Cloudflare MX records exist". Pick a domain that receives no mail today, or register a new one.
Email Sending has no such restriction and works on any domain or subdomain you verify, so you can send from mail.example.com even if example.com receives mail elsewhere. You just cannot receive there.
Then:
export DA=https://dearagent.<your-subdomain>.workers.dev
export KEY=<your API_KEY>
# 1. get an address
curl -s -X POST $DA/inboxes -H "Authorization: Bearer $KEY" -d '{}'
# → { "id": "[email protected]", ... }
# 2. send an email to it, then read it
curl -s "$DA/inboxes/[email protected]/messages/latest" -H "Authorization: Bearer $KEY"
Configuration
Everything lives in wrangler.jsonc, which is git-ignored and generated from wrangler.example.jsonc by npm run setup (or cp it yourself). The template is the committed source of truth; put new settings there. Secrets are set with wrangler secret put.
Setting
Default
What it does
EMAIL_DOMAINS
required
Comma-separated domains this deployment accepts mail for and sends from. Mail to other domains is rejected at SMTP time.
ALLOW_UNKNOWN_INBOX
true
Accept mail for any address and create the inbox on the fly. Set false to reject addresses not created via POST /inboxes.
RETENTION_DAYS
30
Purge messages older than this. 0 keeps them forever. Per-address ttl.<seconds> still applies.
STORE_RAW
false
Keep the raw MIME in R2 so GET …/messages/:id/raw works.
MAX_ATTACHMENT_BYTES
10485760
Larger attachments keep metadata only (stored: false).
DEFAULT_FROM_NAME
""
Display name on outbound mail when the request or inbox has none.
WEBHOOK_TIMEOUT_MS
10000
Per-attempt webhook timeout.
ADDRESS_MATCH_PATTERN
unset
Regex tested against the local-part. When set, only matching addresses are ingested; everything else is handled per FORWARD_UNMATCHED_TO. Unset ingests everything (default).
FORWARD_UNMATCHED_TO
unset
Destination address for mail that doesn't match ADDRESS_MATCH_PATTERN. Must be verified in Cloudflare Email Routing (Dashboard → Email → Destination addresses) or the forward fails. Unset rejects that mail instead.
secret API_KEY
required
Bearer token for the API and MCP.
Bindings (DB, ATTACHMENTS, EMAIL) and the daily cron are pre-declared. To serve the API on your own hostname, uncomment routes in wrangler.jsonc.
API
All endpoints except GET /health require Authorization: Bearer <API_KEY>. Bodies and responses are JSON. Errors look like { "error": { "code": "not_found", "message": "Inbox not found" } }.
Inbox ids are the lowercased address, so URL-encode the @ if your client insists (agent%40mail.example.com works too).
Inboxes
Method
Path
Notes
GET
/inboxes?limit=&cursor=
Newest first.
POST
/inboxes
{ address? | local_part? + domain?, display_name?, metadata? }. Empty body gives a random address. 201 on create, 200 if it existed.
GET
/inboxes/:inbox
PATCH
/inboxes/:inbox
display_name, metadata.
DELETE
/inboxes/:inbox
Removes all threads, messages, attachments, and inbox webhooks.
Messages
Method
Path
Notes
GET
/inboxes/:inbox/messages
Filters: since, before (epoch ms, epoch s, or ISO), unread, has_attachment, direction, thread_id, from, label. Returns snippets; add include_body=true for text/html. Paginate with limit + cursor.
GET
/inboxes/:inbox/messages/latest?since=
Newest match with full body, or 404. The polling primitive: pass the received_at_ms of the last message you saw.
GET
/inboxes/:inbox/messages/wait?since=&timeout=25
Long-polls up to 25 s for a message newer than since (default: now). Returns { message, timed_out }.
GET
/inboxes/:inbox/messages/search?q=
FTS over subject, body, sender.
GET
/inboxes/:inbox/messages/:id
Full message.
PATCH
/inboxes/:inbox/messages/:id
{ read?, labels? }.
DELETE
/inboxes/:inbox/messages/:id
Also deletes attachments; prunes the thread if empty.
GET
/inboxes/:inbox/messages/:id/raw
message/rfc822, requires STORE_RAW=true.
GET
/inboxes/:inbox/messages/:id/attachments/:attId
Streams the file.
POST
/inboxes/:inbox/messages
Compose. { to, cc?, bcc?, subject, text?, html?, from_name?, reply_to?, headers?, attachments?, labels? }. Recipients may be "[email protected]", "Name <[email protected]>", or { address, name }.
POST
/inboxes/:inbox/messages/:id/reply
{ text?, html?, subject?, cc?, bcc?, attachments?, quote_original? }. Sets In-Reply-To/References, honours Reply-To. The original is quoted below the body unless quote_original: false.
POST
/inboxes/:inbox/messages/:id/reply-all
Same, plus the other original recipients on cc.
POST
/inboxes/:inbox/messages/:id/forward
{ to, text?, html?, include_attachments? }. Quotes the original; starts a new thread.
Outbound attachments are { filename, content_type, content_base64, disposition?, content_id? }.
Every outbound message is sent as multipart/alternative: when only text is given an HTML part is generated from it, and when only html is given a text part is derived. Replies and forwards quote the original message the way mail clients do, which keeps them out of spam filters and readable for humans.
/inboxes/:inbox/threads/:id (includes messages[], oldest first, full bodies)
DELETE
/inboxes/:inbox/threads/:id
Webhooks
Method
Path
Notes
GET
/webhooks?scope=global
All webhooks, or only global ones.
POST
/webhooks
{ url, events?, secret?, enabled?, inbox_id? }. Without inbox_id it fires for every inbox. The secret is returned only here (or with ?include_secret=true).
Bodies over 32 KB are omitted and body_truncated is set; fetch the message by id. Headers: X-DearAgent-Event, X-DearAgent-Delivery, X-DearAgent-Timestamp (unix seconds), X-DearAgent-Signature: sha256=<hex>. Verify with:
A typical agent flow: create_inbox → hand the address to a signup form → wait_for_message → read the verification link out of the returned message body.
An agent skill teaches an agent this workflow in full: connecting, waiting instead of polling, reading attachments, replying in thread, and the mistakes to avoid. Copy the skills/dearagent folder into your project's skills directory to use it.
Local development
cp .dev.vars.example .dev.vars # set API_KEY
npm run db:migrate:local
npx wrangler dev --var EMAIL_DOMAINS:mail.example.com
Deliver a test email to the local email() handler:
Sending from wrangler dev needs "remote": true on the send_email binding (see the comment in wrangler.jsonc); it will send real mail. Binary attachments do not work through the remote proxy, deploy to test those.
Tests run inside the Workers runtime with real D1 and R2 emulation:
npm test
npm run typecheck
Limits and gotchas
Receiving works on the free plan; sending needs Workers Paid. Before a domain is onboarded for Email Sending you can only send to addresses verified on your account.
Email Sending: 50 recipients per message, 5 MiB per message (25 MiB to verified destinations), 16 KB of custom headers. Inbound: 25 MiB.
New accounts start with conservative daily send quotas that grow with reputation.
Inbound mail is stored with read: false. Nothing marks messages read automatically except get_message with mark_read: true or PATCH.
The catch-all rule sends every address at the domain to the Worker. Use ALLOW_UNKNOWN_INBOX=false if you want to reject unknown addresses at SMTP time.
One API key, full access. This is a single-tenant tool; put it behind your own auth if you need per-agent scoping.
One bearer key grants full access to every inbox on the server. Treat it like a database password: set it with wrangler secret put, never commit it, rotate it if it leaks.
The Worker has no per-agent scoping. If several agents or people share a deployment, put it behind Cloudflare Access or your own gateway.
Webhooks are HMAC-signed. Verify X-DearAgent-Signature before trusting a payload.
Anything an agent can read from an inbox, a sender can put there. Treat inbound mail as untrusted input to the agent.
Found a vulnerability? Please report it privately through GitHub's Security → Report a vulnerability on this repository rather than opening a public issue.
Contributing
Pull requests are welcome. Run npm test and npm run typecheck before opening one. By submitting a contribution you agree to the Contributor License Agreement, which lets the project also be offered under licenses other than the AGPL.
License
Copyright (c) 2026 Sandeep Panda.
GNU Affero General Public License v3.0. You can self-host, modify and redistribute DearAgent freely. If you run a modified version as a network service, you must make your modified source available to its users under the same license.
D
Dearagent
panda-sandeep·42 estrellas·
Email inbox API for AI agents, self-hosted on Cloudflare Workers. Open source, with an MCP server. AgentMail alternative.
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Preguntas
¿Cómo instalo Dearagent?
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
¿Dearagent necesita una clave de API?
Este registro no indica ninguna variable de entorno obligatoria.
¿Qué transporte usa Dearagent?
Dearagent se ejecuta localmente por stdio.
¿Cuándo se comprobó Dearagent por última vez?
Última comprobación: 2026-10-28. Email inbox API for AI agents, self-hosted on Cloudflare Workers. Open source, with an MCP server. AgentMail alternative.