AvaMail

Self-hosted email on your own domain, running entirely on Cloudflare's edge.

Receive mail through Cloudflare Email Routing, store it in a D1 database (attachments optionally in R2), send through Brevo, and manage everything from a Vue 3 web app served by the same Worker. One deploy, no servers, free-tier friendly.

🤖 Installing with an AI agent (Claude Code, etc.)? Point it at agent-install.md — a step-by-step install guide written for agents.

Features

Mail

• Catch-all receiving on your domain — every address at your domain lands in one inbox
• Sending via Brevo's transactional API, with delivery tracking (delivered / opened / bounced) reported back by webhook
• Conversation threading via Message-ID / In-Reply-To headers
• Drafts, reply-with-quote, forwarding (original attachments included), and scheduled send (cron-delivered)
• Archive, labels, starring, and full-text search (SQLite FTS5 over subjects, bodies, and addresses)
• Attachments up to 5MB/file in D1, or 25MB/file with an optional R2 bucket
• Contacts with autocomplete in Compose — people you write to are captured automatically
• Per-message .eml download and whole-mailbox mbox export
• Optional forwarding of received mail to a personal inbox as backup

App

• Vue 3 SPA with full light / dark / system theming
• Dashboard: daily send/receive activity chart, recent messages, system status, storage usage
• Installable PWA with payload-free push notifications on new mail
• Remote-image blocking (tracking-pixel protection) with per-email reveal

Security

• Passkey sign-in (FIDO2/WebAuthn) — Touch ID, Windows Hello, security keys — plus a password fallback
• PBKDF2 password hashing (100k iterations), session tokens stored as SHA-256 hashes
• Received HTML sanitized with DOMPurify before rendering
• Strict Content-Security-Policy and security headers on every response
• Shared rate limit for password and passkey login attempts
• Server-side attachment validation, safe download headers, sanitized filenames

Architecture

                        Cloudflare Edge
┌────────────────────────────────────────────────────────────────┐
│                                                                │
│  Email Routing ──▶ Email Worker ──┬─▶ D1 (mail, contacts,      │
│   (catch-all)                     │      settings, sessions,   │
│                                   │      FTS index)            │
│  Cron (*/5) ──▶ scheduled send ───┤                            │
│                                   ├─▶ R2 (attachments,         │
│  HTTPS ──▶ Worker (Hono API) ─────┘      optional)             │
│              │                                                 │
│              └─▶ Vue 3 SPA (static assets)                     │
│                                                                │
└──────────────┬─────────────────────────────┬───────────────────┘
               │ send                        │ delivery webhooks
               ▼                             │
             Brevo ◀─────────────────────────┘

  Browser ◀── Web Push (VAPID, no payload) ── Email Worker

Quick start

Prerequisites: a Cloudflare account with a domain, a Brevo account (free tier is fine), Node.js 18+, and pnpm.

# 1. Clone and install
git clone https://github.com/MrOplus/AvaMail.git
cd AvaMail
pnpm install

# 2. Authenticate wrangler
npx wrangler login

# 3. Create the database
cd packages/worker
npx wrangler d1 create avamail-db          # note the database_id in the output

# 4. Configure
cp wrangler.toml.example wrangler.toml     # then paste your database_id into it

# 5. Initialize the schema (fresh installs only — see Upgrading otherwise)
npx wrangler d1 execute avamail-db --remote --file=./src/db/schema.sql

# 6. Build and deploy
cd ../..
pnpm -r build
cd packages/worker
npx wrangler deploy

Your app is now live at https://avamail.<your-subdomain>.workers.dev.

First-run configuration (in the app)

1. Open the URL and create your admin password. Add a passkey under Settings → Security for passwordless sign-in.

2. Settings → Cloudflare — create an API token (dash.cloudflare.com → API Tokens → Create Custom Token) with these permissions, then enter it with your Account ID and domain:

   Scope	Permission	Access
   Account	Email Routing Addresses	Edit
   Zone	Zone	Read
   Zone	DNS	Edit
   Zone	Email Routing Rules	Edit
   Zone	Zone Settings	Edit

   Saving enables Email Routing on your zone and points the catch-all rule at the worker. If inbound mail ever stops, the Fix Email Routing button re-applies the rule.

3. Settings → Brevo — paste your Brevo API key (app.brevo.com → SMTP & API). Saving also auto-registers the delivery-status webhook.

4. Verify your sending domain in Brevo (Senders & Domains) — add the SPF / DKIM / DMARC records it gives you, or outbound mail will be rejected or spam-foldered.

5. Settings → Addresses — add at least one From address.

6. Click Complete Setup, then test both directions: mail an external message to anything@yourdomain.com and send one out via Compose.

Configuration reference

wrangler.toml (gitignored; copy from wrangler.toml.example):

name = "avamail"                 # worker name — also the catch-all rule target
main = "src/index.ts"
compatibility_date = "2024-01-01"

[[d1_databases]]
binding = "DB"
database_name = "avamail-db"
database_id = "YOUR_DATABASE_ID_HERE"

[assets]
directory = "../../frontend/dist"
binding = "ASSETS"               # SPA deep links (/inbox, /login, …)
run_worker_first = true          # security headers on every response

# Optional — see "R2 attachments" below
# [[r2_buckets]]
# binding = "ATTACHMENTS"
# bucket_name = "avamail-attachments"

[triggers]
crons = ["*/5 * * * *"]          # scheduled send + session cleanup

[vars]
APP_NAME = "AvaMail"

Secrets (Cloudflare token, Brevo key) are never placed in config files — they're entered through the app UI and stored in D1.

R2 attachments (optional)

Without R2, attachments live base64-inline in D1 (5MB per file). To raise the cap to 25MB and keep the database lean:

1. Enable R2 once in the Cloudflare dashboard (the API errors with code 10042 until you do).
2. npx wrangler r2 bucket create avamail-attachments
3. Uncomment the [[r2_buckets]] block in wrangler.toml and redeploy.

Existing inline attachments keep working — reads fall back to D1 automatically.

Upgrading

Fresh installs use schema.sql only. Existing databases apply what they're missing, each file exactly once:

cd packages/worker
# pre-passkey installs first bring the base schema up to date:
npx wrangler d1 execute avamail-db --remote --file=./src/db/schema.sql
# then the structural migration (adds threading/drafts/FTS/etc. — run ONCE):
npx wrangler d1 execute avamail-db --remote --file=./src/db/migrations/002-features.sql

Unsure which generation you're on? agent-install.md has a decision table keyed off which tables exist. After migrating: pnpm -r build and npx wrangler deploy.

Upgrading from a pre-passkey version signs everyone out once (session tokens are now stored hashed) — just log in again.

Development

# Terminal 1 — worker + local D1 on :8787
cd packages/worker
npx wrangler d1 execute avamail-db --local --file=./src/db/schema.sql
npx wrangler dev

# Terminal 2 — Vite dev server with HMR on :5173 (proxies /api to :8787)
cd frontend
pnpm run dev

Test the cron locally: start with npx wrangler dev --test-scheduled, then curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*".

Project structure

AvaMail/
├── frontend/                  # Vue 3 SPA (Vite, Tailwind, Pinia)
│   ├── public/                # PWA manifest, service worker, theme bootstrap
│   └── src/
│       ├── api/               # typed API client
│       ├── components/        # EmailList, ActivityChart
│       ├── stores/            # auth, emails, theme
│       ├── utils/             # avatar helpers
│       └── views/             # Dashboard, Inbox, EmailView, Compose,
│                              # Drafts, Archive, Contacts, Settings, …
├── packages/
│   ├── worker/                # Cloudflare Worker (Hono)
│   │   └── src/
│   │       ├── api/           # routes: auth, webauthn, emails, contacts,
│   │       │                  # push, webhooks, settings, setup
│   │       ├── db/            # schema.sql, migrations/, queries.ts
│   │       ├── lib/           # mailer, attachments (R2/D1), push (VAPID),
│   │       │                  # eml builder, rate limiting, validation
│   │       ├── email-handler.ts   # inbound mail: parse, thread, store, notify
│   │       └── index.ts           # fetch + email + scheduled entrypoints
│   ├── brevo-api/             # Brevo REST wrapper (send, senders, webhooks)
│   └── cloudflare-email-api/  # Cloudflare REST wrapper (zones, routing, DNS)
└── agent-install.md           # agent-oriented install guide

API reference

All endpoints are under /api. Everything except login/setup ceremonies and the Brevo webhook requires Authorization: Bearer <token>.

Auth

Endpoint	Method	Description
/auth/status	GET	Auth state, needsSetup, hasPasskeys
/auth/setup	POST	Create the admin password (first run)
/auth/login	POST	Password login (rate limited: 5 / 15 min)
/auth/logout	POST	Invalidate the session
/auth/change-password	POST	Change password
/auth/webauthn/register/options · /verify	POST	Passkey registration ceremony
/auth/webauthn/login/options · /verify	POST	Passkey login ceremony (shares the login rate limit)
/auth/webauthn/credentials	GET	List passkeys
/auth/webauthn/credentials/:id	DELETE	Remove a passkey

Mail

Endpoint	Method	Description
/emails	GET	List (type=received|sent|draft|scheduled, archived, label, unread, starred, limit, offset)
/emails/search	GET	Full-text search (?q=)
/emails/labels	GET	All labels in use
/emails/stats	GET	Counts + storage usage
/emails/activity	GET	Daily send/receive counts (?days=14)
/emails/export/mbox	GET	Whole-mailbox mbox download
/emails/drafts	POST	Create or update a draft
/emails/send	POST	Send — supports draftId, scheduleAt, replyToEmailId, forwardOfEmailId, attachments
/emails/:id	GET	Single email with attachments + conversation thread
/emails/:id/eml	GET	Download as .eml
/emails/:id/read · /unread · /star	POST	Flags
/emails/:id/archive · /unarchive	POST	Archive state
/emails/:id/labels	PUT	Replace labels
/emails/:id	DELETE	Delete email + attachments (D1 and R2)
/emails/:id/attachments/:attachmentId	GET	Download an attachment

Contacts, push, setup

Endpoint	Method	Description
/contacts	GET / POST	List / create (upserts by email)
/contacts/:id	PUT / DELETE	Update / delete
/push/vapid-key	GET	VAPID public key
/push/subscribe · /unsubscribe	POST	Manage push subscriptions
/webhooks/brevo/:secret	POST	Brevo delivery events (auto-registered; secret-guarded)
/setup/status	GET	Configuration state
/setup/cloudflare	POST	Connect Cloudflare + enable routing
/setup/cloudflare/worker-routing	POST	Re-point the catch-all at the worker
/setup/brevo	POST	Connect Brevo + register webhook
/setup/addresses	GET / POST / DELETE	Manage From addresses
/setup/complete	POST	Finish onboarding

Troubleshooting

Symptom	Fix
"Frontend assets not found"	Build before deploying: pnpm -r build, then redeploy
Inbound mail not arriving	Settings → Cloudflare → Fix Email Routing; verify MX records and that the zone is active; npx wrangler tail to watch the worker
Outbound rejected / in spam	Verify the sending domain (SPF/DKIM/DMARC) in Brevo
No delivery badges on sent mail	Re-save the Brevo API key in Settings to (re)register the webhook
429 on login	Rate limit — wait 15 minutes (setup: 3/hour)
Signed out after upgrading	Expected once (hashed session tokens) — sign in again
Passkey missing on a new domain	Passkeys bind to the hostname; add one on the new host
Scheduled email shows "failed"	Fix the Brevo config; the message is preserved under Drafts — edit and resend

License

MIT — see LICENSE.

Support

Issues and feature requests: GitHub Issues.