#Running cmail

The repeatable jobs for a live deployment, in one place: upgrading, backing up, restoring, rolling back, watching for trouble, and rotating secrets. Most procedures already live in Deployment and verification; this page gives the order and links to them, and adds monitoring and secret rotation. Tick off the Operations checklist as you go.

Examples use the default resource names (cmail-web, cmail-db, cmail-storage, cmail-backup). Use your own.

#Upgrade

1. Start from a clean checkout (git status --short is empty) and read the changelog entries since your version. Note any new migration, binding, cron or secret.
2. Your wrangler.toml files are ignored by Git, so a pull never changes them. Compare each with its wrangler.toml.example and copy across any new binding, variable or cron by hand.
3. Record the current Pages deployment ID and email Worker version (see Roll back).
4. Take a fresh backup point (see Back up). If a migration is pending, also record a D1 Time Travel bookmark (see Restore).
5. Follow Updating an existing instance: pull, pnpm install --frozen-lockfile, pnpm release:check, pnpm db:migrate, then pnpm deploy (the email Worker, then Pages). pnpm deploy doesn't cover the backup Worker or the landing page: if they changed, redeploy them too (pnpm exec wrangler deploy in apps/backup-worker, and pnpm deploy:landing).
6. Smoke-test: the home page loads, /mail redirects when signed out, a test account can sign in, and a test message arrives and opens. Then work through "After deployment" in the operations checklist.
7. If anything fails, roll back straight away, then investigate.

Deploy one instance at a time when you run several, and finish verifying each before starting the next.

#Back up

• In the account: the optional backup Worker copies mail bodies and attachments hourly and dumps every D1 table daily into a private backup bucket. It needs no extra credentials.
• Outside the account: take a matching D1 export and R2 copy to separate, encrypted storage, as in Back up and rehearse recovery. Only this protects against losing the whole Cloudflare account.
• History: D1 Time Travel keeps 30 days on Workers Paid (7 on Free). It covers D1 only, not R2.

Rehearse a restore on preview or recovery resources before relying on any of these, and again after changing the backup setup.

#Restore

Pick the smallest restore that fixes the problem:

A restore of live data rewinds or replaces mail people may have read since. Get approval, pause Email Routing and interactive writes first, and compare row counts before re-enabling routing. If the incident touched both D1 and R2, restore both to the same point.

#Roll back

A bad code release is the most likely incident. Roll Pages back first, then the email Worker, using the IDs you recorded before deploying. Don't roll code back past a D1 migration unless the older code works with the newer schema; deploy a forward fix instead. Full procedure: Roll back a release.

#Monitor

cmail has no built-in alerting. These are the places to look, and what should make you act.

Uptime. An external check every few minutes:

• GET / returns 200.
• GET /mail redirects when signed out: a 302 to / for a fresh visitor (a browser that remembers a sign-in provider gets a 303 to that provider's sign-in instead).
• POST /mcp without a token returns 401, and GET /.well-known/oauth-protected-resource returns 200, if you use the MCP connector.

Scheduled jobs. Check each Worker's Cron Trigger past events in the Cloudflare dashboard, or its logs:

Mail flow.

• Management → Mail trace: accepted and rejected deliveries. Delivery recovery lists sends stuck in dispatching or ambiguous; reconcile them as the Operations checklist describes.
• Email Routing analytics for the domain: dropped or rejected inbound mail. Rejections at SMTP time leave no cmail trace record.
• Email Worker logs: live with wrangler tail or the dashboard's log stream. To keep them for later review, add [observability] with enabled = true to the email Worker's wrangler.toml (the template doesn't enable it; the backup Worker's does) and use Workers Logs. Watch for Inbound native rate-limit threshold observed, Inbox rules were skipped, Failed to clean up an inbound R2 object, Mail trace logging failed, and calendar or contact errors. One-off warnings are normal; a sustained run of any of them needs a look.
• Outbound provider dashboards for bounces and complaints, and DMARC aggregate reports (see Email authentication).

Growth. D1 size and R2 object count in the dashboard, and mailbox quota denials in the trace. The backup Worker suits up to tens of thousands of mail objects.

Logs hold no message content by design. Keep it that way when you add your own monitoring: don't log subjects, bodies or full addresses.

#Rotate secrets

Rotate on a schedule your organisation sets, and immediately if a value is printed, committed or shared. Generate a new value, store it, redeploy, then check sign-in and mail flow. Every secret is per environment: rotating production never touches preview.

Also review who holds Cloudflare, identity-provider and DNS access, and remove anyone who no longer needs it.

← Documentation home