title: "cmail documentation" summary: "The index of every cmail guide, with where to start for primary mail or a Microsoft 365 standby." applies_to: both audience: [operator, manager, user] switch: none last_reviewed: 2026-11-16 related: [credentials.md, glossary.md, getting-started.md, onboarding-microsoft-365.md]
cmail documentation
cmail is beta software (0.9, before 1.0). Operators should read the deployment and security guides before sending real mail through it. Words like switch, dry run and standby are defined in the Glossary.
Start here
- Primary mail for your organisation: Getting started, then Deployment and verification.
- Standby for an organisation on Microsoft 365: Onboarding an organisation that uses Microsoft 365.
- Either way: Credentials and permissions lists every token, app and secret, with exact permissions.
Use cmail
- User guide: first sign-in, reading, composing, folders, safety.
- Calendar: meeting invitations.
- Mobile app and notifications: install on a phone, new-mail alerts.
- Shared mailboxes: team addresses, Send as, Full access.
- Email signatures: personal and organisation signatures.
- Inbox rules: file mail automatically.
- Focused Inbox: Focused and Other tabs (off by default), how mail is sorted and why.
- Spam and quarantine: scoring, quarantine, sender rules.
- AI agents and MCP: connect Claude or another AI app.
- Mail client connectivity: why there is no IMAP yet, and the plan.
Manage cmail
- Manager handbook: people, mailboxes, organisation, policy, mail trace, audit.
- Travel approvals: limit sign-in to approved countries.
- Support process: triage, evidence, escalation.
- Acceptable-use policy template.
Deploy and run cmail
- Getting started: local setup and Cloudflare storage.
- Configuration reference: every setting.
- Credentials and permissions: every token, app and secret.
- Email authentication: read before changing mail DNS.
- Architecture and trust boundaries.
- Deployment and verification: the production sequence.
- Security checklist and Operations checklist.
- Running cmail: upgrade, back up, restore, roll back, monitor, rotate secrets.
- Upgrading and keeping your settings.
Sign-in
- Staff sign-in: staff-portal links, the Cloudflare Access bridge, Microsoft sign-in for synced people.
- Passkey break-glass sign-in: sign in when Microsoft or Access is down.
Microsoft 365 standby
All off by default, each with its own Admin switch. Order and setup:
Onboarding an organisation that uses Microsoft 365,
with scripts in scripts/onboarding/.
- Microsoft 365 sync: keep accounts and shared mailboxes in step with the tenant.
- Microsoft 365 welcome emails: first sign-in steps for each new synced person.
- Shared mailbox access from Exchange Online: copy Full Access and Send As daily.
- Exchange mirror: a live copy of every mailbox from one journal rule.
- Standby test address and daily probe: prove the standby path every day.
- Standby switch: move incoming mail to cmail and back, one DNS change each.
- Copy-back: copy standby mail into Exchange after an outage.
How cmail works
- How cmail runs on Cloudflare: the deployables, bindings, schedules and migrations.
- How sending works.
- Delivery status and bounces.
- How receiving works.
- Reading mail safely.
- Inbox rules: how the engine works.
- Push notification reliability: a design, not built.
Governance
- Security, privacy, and assurance.
- ISO and ITIL alignment.
- Privacy and data handling.
- Branding.
- Downstream and private implementations.
- Project roadmap.
Contributors and maintainers
- Developer guide.
- Maintainer release guide.
- Reviews: security review, September 2026, dependency review, 22 September 2026, dependency review, 9 September 2026.
- Contributing, Support, Security policy, Code of Conduct.
Command reference
Run from the repository root:
| Command | Use |
|---|---|
pnpm run setup |
Create ignored local configuration from committed templates |
pnpm dev |
Start the SvelteKit development server |
pnpm dev:worker |
Start the email Worker with wrangler dev |
pnpm db:migrate:verify |
Apply every migration to a throwaway local D1 and check the schema |
pnpm test:mobile |
Run the Playwright mobile and accessibility suite (see the Developer guide) |
pnpm db:migrate:local |
Apply migrations to isolated local D1 state |
pnpm db:migrate:preview |
Apply migrations to the explicitly isolated preview D1 database |
pnpm config:check |
Verify committed and active Wrangler bindings remain isolated and fail closed |
pnpm deploy:email-worker:preview |
Deploy the isolated, non-sending preview email Worker |
pnpm push:keys |
Generate a VAPID pair for optional browser notifications |
pnpm validate |
Run source, lint, type, test, migration, build, and dependency checks |
pnpm release:check |
Run validation plus the reachable Git-history secret gate |
Page metadata
Each page starts with a metadata block between --- lines: title,
summary, applies_to (primary, standby or both), audience (any of operator, manager, user),
switch (the Admin label that turns the feature on, or none),
last_reviewed and related (file names). The docs site reads it for
search; GitHub shows it as a table.