# Mail HQ

Your email. Your domains. Your agents.

Canonical URL: https://kb.byaditya.com/entry/docs/mail-hq
Source: https://docs.adityabaindur.com/docs/mail-hq
Source updated: 2026-10-08T01:29:22Z
Indexed: 2026-11-05T03:56:29.576Z

---

## 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](https://github.com/Aditya-Baindur/mail-hq)

### [Deploy to Cloudflare](https://deploy.workers.cloudflare.com/?url=https://github.com/Aditya-Baindur/mail-hq)

## Tech Stack

- Next.js
- React
- Tailwind CSS
- shadcn/ui
- Cloudflare
- TypeScript
- Vite

## Quick Links

### [Deploy your own](/entry/docs/mail-hq/deployment)

Domains, Cloudflare Access, Email Routing, and Email Sending

### [Connect an agent](/entry/docs/mail-hq/mcp)

Mailbox-scoped MCP tokens, permissions, and tools

### [Security & limits](/entry/docs/mail-hq/security)

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.