Stanchion docs

Stanchion (formerly cMail): the docs and code keep the old name until the code is renamed.


How cmail runs on Cloudflare

cmail is four deployables that share one D1 database and one R2 bucket. This page lists each one, its bindings and schedules, and how they connect. The default resource names here (cmail-web, cmail-db and so on) come from the *.example Wrangler files; yours can differ. To set them up, follow Getting started and Deployment.

flowchart LR
  browser["Browser"] --> web["cmail-web (Pages)"]
  web -->|"EMAIL_SERVICE binding"| worker["cmail-email-worker"]
  worker -->|"send_email binding"| sending["Email Sending"]
  routing["Email Routing"] --> worker
  sending -.->|"events, optional"| queue["Queue"] -.-> worker
  web --> d1[("D1 cmail-db")]
  web --> r2[("R2 cmail-storage")]
  worker --> d1
  worker --> r2
  backup["cmail-backup-worker"] --> d1
  backup --> r2
  backup --> r2b[("R2 cmail-backup")]

The deployables

Web app: apps/web

A SvelteKit app on Cloudflare Pages, built with @sveltejs/adapter-cloudflare. It serves the mail UI, sign-in, administration and the MCP endpoint for AI apps.

Binding Type Default resource
DB D1 cmail-db (migrations in packages/shared/migrations)
STORAGE R2 cmail-storage
EMAIL_SERVICE Service binding cmail-email-worker

Pages can't hold a send_email binding, which is why outbound mail goes through the email Worker. Settings go in [vars] and Pages secrets; see the Configuration reference. The [env.preview] block points at separate preview resources and sets OUTBOUND_PROVIDER = "none", so a preview can never send real mail.

Email Worker: apps/email-worker

A Worker with four handlers in src/index.ts:

Handler Job
email() Receives mail from Email Routing. See How receiving works
fetch() Only POST /internal/send, reachable only over the service binding. See How sending works
queue() Optional. Delivery events. See Delivery status and bounces
scheduled() Retention at 17 3 * * * (when RETENTION_JOBS_ENABLED="true"), the link blocklist refresh at 7 * * * *, the optional Microsoft 365 sync, welcome emails, shared mailbox access, the Exchange mirror alias import and copy-back at */15 * * * *, and the optional standby probe at */10 * * * * (each returns at once unless a manager turned it on)

Bindings: DB, STORAGE, [[send_email]] name = "EMAIL", three rate-limit bindings (they only record activity, and never block mail), and the optional queue consumer. The Worker has no public URL: workers_dev = false, preview_urls = false, routes = [].

Secrets: INBOUND_SENDER_HASH_KEY (required; without it, sender rate limits fail closed) and VAPID_PRIVATE_KEY (only for push notifications).

A scheduled Worker (cron 23 * * * *) with no URL.

It is deployed separately: pnpm setup, pnpm deploy and config:check don't cover it. Restoring is a manual job; see Running cmail: restore.

Product page: landing/ (optional)

A static Pages site with no bindings. Deploy it with pnpm deploy:landing --project-name <name>. It contains upstream links and analytics settings, so a fork should review landing/insights.js and landing/_headers before deploying it.

Cloudflare products

Product Needed? Used for
Pages Yes Web app
Workers Yes Email Worker, backup Worker
D1 Yes All metadata
R2 Yes Bodies, attachments, staged sends, link list, backups
Email Routing Yes Inbound mail
Email Sending Recommended Outbound mail (Postmark is the alternative)
Cron Triggers Yes Retention, link list, backups
Queues Optional Delivery events and bounce notices
Turnstile Optional Bot check on the email-code sign-in form
Access Optional An extra gate in front of the site. See Staff sign-in
Containers and Durable Objects Optional (Workers Paid) The Exchange Online reader for shared mailbox access
D1 Time Travel Built in Point-in-time restore of the database

Check Cloudflare's current plan limits and prices before choosing a plan.

Database migrations

There are 29 forward-only migrations in packages/shared/migrations/, from 0001_initial.sql to 0029_m365_welcome_emails.sql. 0023_standby_probe.sql was merged after 0024; wrangler d1 migrations apply still applies it on a database that already has 0024, because it applies every file not yet listed in d1_migrations. There are no down migrations, so roll back with a backup or Time Travel.

Command Does
pnpm db:migrate Applies new migrations to production D1
pnpm db:migrate:local Applies them to local D1 state
pnpm db:migrate:preview Applies them to the preview D1
pnpm db:migrate:verify Applies all of them to a throwaway D1 and checks the tables, triggers and upgrade fixtures

The first three run config:check first.

What config:check enforces

scripts/verify-wrangler-config.mjs reads the example and active Wrangler files for the web app and the email Worker. It fails if:

It does not check [vars], crons, compatibility dates, queues or the backup Worker. See Upgrading and keeping your settings for what to check by hand.