Mail HQ
Your email. Your domains. Your agents.
Overview
A minimal email workspace built with Next.js, shadcn/ui, and Cloudflare Workers. Create mailboxes on your own domains, send and receive formatted email, and give an AI agent access to exactly one inbox. Everything runs in your Cloudflare account: one Worker, one D1 database, and one private R2 bucket.
GitHub
Deploy to Cloudflare
Tech Stack
- Next.js
- React
- Tailwind CSS
- shadcn/ui
- Cloudflare
- TypeScript
- Vite
Quick Links
Deploy your own
Domains, Cloudflare Access, Email Routing, and Email Sending
Connect an agent
Mailbox-scoped MCP tokens, permissions, and tools
Security & limits
How Mail HQ protects your mail, and its current limits
Features
- Clean, responsive inbox with searchable mailbox selectors and keyboard controls
- Unified and individual inboxes, threads, replies, forwarding, search, stars, archive, and trash
- Rich text composition, attachments, and automatically saved drafts
- Mailbox management and a stats view for mail, storage, and agent activity
- Private R2 storage for attachments, message bodies, and original incoming MIME; D1 for metadata
- Cloudflare Access login for the dashboard
- Hosted MCP server with revocable, expiring tokens scoped to one mailbox and read/send permissions
Architecture
One Worker, two hostnames:
- Dashboard: Next.js App Router (through vinext) served by the Worker on your dashboard hostname, protected by Cloudflare Access
- API: Hono routes under
/api/*on the same hostname; every request re-verifies the Access JWT - MCP: A separate hostname that serves the MCP server and authenticates with mailbox-scoped bearer tokens instead of Access
- Metadata: Cloudflare D1 (mailboxes, messages, drafts, agent tokens, audit events)
- Mail content: Private Cloudflare R2 (message bodies, original incoming MIME, attachments)
- Receiving and sending: Cloudflare Email Routing delivers to the Worker's email handler; Cloudflare Email Sending sends outgoing mail
Incoming mail: Email Routing → Worker email handler → R2 (original message and body) + D1 (metadata) → Inbox
Outgoing mail: Dashboard or agent → Worker → Email Sending → Sent to Cloudflare
Mail HQ never rewrites MX records or edits existing routing rules. Domains that already use another mail provider stay unavailable for new mailboxes until you migrate them yourself.
Stack
| Layer | Technology |
|---|---|
| Dashboard | Next.js App Router through vinext, React, shadcn/ui, Tailwind CSS |
| Backend and MCP | Cloudflare Workers, Hono, MCP SDK |
| Metadata | Cloudflare D1 |
| Email and attachments | Private Cloudflare R2 |
| Receiving and sending | Cloudflare Email Routing / Email Sending |
| Dashboard authentication | Cloudflare Access |
Status
Not implemented yet
- IMAP/SMTP access (for example, Apple Mail on a phone) is planned, not implemented.
- You can add the dashboard to an iPhone Home Screen, but push notifications and offline support are not implemented.
- External historical mail is not imported automatically.