MailDocs

Guides

How it works

  • Receiving (src/lib/inbound.ts): mail is routed by the envelope recipient, so BCC and mailing-list mail is kept. A named mailbox is always kept (and copies to the domain's forward address unless it has its own); other addresses follow the domain's rule (keep, keep and forward, forward only, or reject). The cheap steps run first: the original goes to R2 with a row built from its headers, then the forward copy is sent, then the body is parsed. Messages up to the PARSE_MAX_BYTES var (25 MiB here, as the account is on Workers Paid; use 262144 on Workers Free, which allows 10 ms of CPU per message) are parsed on arrival, larger ones with "Read full message"; a redelivered message is neither stored nor forwarded twice. Nothing is dropped silently: a message that cannot be kept is forwarded, and when neither works the handler throws so Email Routing does not report it delivered. Mail that fails DMARC goes to Spam.
  • Domains (src/lib/domain-routing.ts): Connect turns on Email Routing when needed and points the catch-all at mail-catalog. The rule it replaces is saved and Disconnect puts it back; if that rule forwarded to Gmail, the address becomes the domain's forward address, so Gmail keeps receiving. A domain whose MX records point at Microsoft 365, Google, Zoho or its own server is never switched. migrations/0002_seed_account_domains.sql lists the 79 domains on Cloudflare DNS (DNS sweep of 2 November 2026); none is connected until you press Connect.
  • Sending (src/lib/outbound.ts): replies and new mail go through Cloudflare Email Service (EMAIL send_email binding). The send is awaited; a refusal is shown with Cloudflare's error code and nothing is saved to Sent. Sending to anyone needs Workers Paid and each From domain onboarded under Email Service → Email Sending.
  • Mail server per domain (src/lib/mail-server.ts): "Set up mail server" (or the checkbox when adding a domain) runs four idempotent steps: receiving (the same as Connect), sending (onboards Email Sending and adds its cf-bounce MX, SPF and DKIM records), DMARC (v=DMARC1; p=none, only when the domain has none) and webmail (a proxied AAAA mail 100:: record plus the zone Worker route mail.<domain>/*). Existing records are never overwritten: a clash (another mail.<domain> record, a second SPF) is reported on the domain. Check reports without writing; Remove deletes only the route and the record this app added. Domains hosted at Microsoft 365 or their own server are refused. Zone routes are used instead of Workers Custom Domains because wrangler deploy replaces custom domains with the list in wrangler.jsonc; keep that list to the main host only and add no plain routes there.
  • Hosts (src/lib/host-scope.ts): MAIN_HOST (mail.appneurox.com) is the unified inbox with Domains, Activity and Setup. Every mail.<domain> host only shows that domain's mail and only sends from addresses on it; the admin pages redirect to its inbox and the admin APIs answer 403. It opens with the deployment passcode or the domain's own passcode (set when adding the domain or under Settings, stored as a PBKDF2 hash). A domain-passcode session is valid only on its own host, and changing that passcode ends its sessions.
  • Reading: HTML mail is shown in a sandboxed frame (CSP sandbox, no scripts, remote images blocked until loaded). Attachments always download.
  • /, /domains, /activity, /setup and every /api/* route except /api/items and /health need a session (EDIT_PASSCODE, or a domain passcode on mail.<domain>). Writes must come from this origin (Origin / Sec-Fetch-Site checked), login attempts are counted before the passcode is checked, and changing EDIT_PASSCODE ends every open session. Use a long random passcode; Cloudflare Access can be added in front for per-person sign-in.
Last updated 2 November 2026