Stanchion docs

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


Microsoft 365 welcome emails

Status: built, off by default, not yet tested against a real tenant, real DNS or a real Exchange Online inbox. Tested with every real migration on node:sqlite and a mocked Cloudflare Email Sending binding.

When the Microsoft 365 sync creates a person in cmail (or links an existing account that is still pending), cmail can email them once with plain first sign-in steps. A manager turns it on in Admin > Microsoft 365 sync > Welcome emails. Off, it changes nothing: the cron reads one settings row and returns, and no mail is sent.

In this article

Who gets one

A welcome email goes to a person when all of these hold, checked when it is queued and again just before it is sent:

  1. the sync linked them (m365_sync_links, kind person) and they are still in scope in Microsoft 365;
  2. their cmail account is a standard account, pending, has never signed in (last_sign_in empty) and has no sign-in identity of any kind (Google, Microsoft, email code or Access);
  3. their address is not a shared mailbox's address;
  4. they have no welcome record yet (once only), or a manager pressed Resend;
  5. their sync link was created at or after the switch's cut-off (see below), unless a manager pressed Send or Resend.

Shared mailboxes never get one. The sync creates shared mailboxes as mailboxes with no account, so they never match rule 1; rule 3 also excludes an account whose address is a shared mailbox. Managers, paused, offboarded and out-of-scope people, and accounts the sync did not create, never match.

A synced account is pending with no sign-in identity. While the sync is on, the person signs in for the first time with Sign in with Microsoft on cmail's own sign-in page: cmail verifies the Microsoft ID token and binds the person's Microsoft identity to the account the sync created for them, by the token's tenant (tid) and Entra object id (oid), never by email. Details and rules: Microsoft 365 sync: First sign-in. The Cloudflare Access bridge, if used, also adopts such accounts. Either way the email carries no token or magic link: only the address of cmail.

So the switch needs one of: Microsoft sign-in configured on the web app with the sync's tenant known (M365_TENANT_ID on the web app, or a tenant GUID in MICROSOFT_TENANT_ID), or the Access bridge. Without either, Admin shows "Cannot send: people created by the sync cannot sign in yet" and the switch stays off.

Which address it is sent to

The person's account email, which the sync keeps equal to their Microsoft 365 primary SMTP address (mail). This is deliberate:

Not yet verified live: that Cloudflare Email Sending does not short-cut delivery to a domain that is also on Email Routing in the same account, and that Exchange Online Protection accepts the message into the Inbox. The From address is on your own domain but the message comes from Cloudflare, so it must pass DMARC (Cloudflare signs with DKIM for the onboarded sending domain; Microsoft's email authentication overview explains how Exchange Online treats a message from your own domain that fails it). On the first live run, check one welcome email in Exchange message trace and in the person's Inbox (not Junk) before sending to everyone.

The From address must pass DMARC

The From address is the same one manager invitations use: the system email from Admin > Settings when it is on MAIL_DOMAIN, else noreply@MAIL_DOMAIN. Requirements, checked or shown in Admin:

cmail cannot read your DNS or Cloudflare account, so it cannot prove DMARC passes before the first send: check the first welcome email's headers (Authentication-Results: dmarc=pass) in Exchange.

The switch (Admin > Microsoft 365 sync > Welcome emails)

Managers only. Off by default.

Cannot send. The switch is disabled, with the reason, while any of these is true: migration 0029 is missing; the web app has no outbound provider (OUTBOUND_PROVIDER resolves to none, shown on page load); the email Worker has no EMAIL send binding or cannot be asked ("Cannot send: outbound mail not configured"; checked when turning on and by Check sending: the page load itself never calls the Worker or writes a setting); MAIL_DOMAIN is not set (the Worker refuses to send too); synced people cannot sign in (no Microsoft sign-in for the sync's tenant and no Access bridge); APP_URL, the organisation name or a valid From address exactly on MAIL_DOMAIN is missing. An unknown answer from the Worker counts as "cannot send".

Turning it on shows a warning first, with the number of people who would be emailed right now: people the sync created, who have never signed in and were never sent a welcome email. The manager then picks:

Turning it on is audited (org.m365_welcome_toggled) with the choice and N.

Turning it off stops all sending and cancels emails not sent yet (their records are removed, so those people count as waiting again). Sent records stay. Turning it on again asks the same question with the new count.

Sync off or dry run. Nothing is sent while the sync is off. In sync dry run nothing is queued or sent; each run records how many people would be emailed and lists up to 200 of them in Admin. A Resend pressed during dry run waits until dry run is off.

Exactly once, retries and limits

Admin shows counts (Sent, Waiting to send, Failed, Skipped, Not sent), the last run's result and problem, the dry-run list, a preview of the email, and up to 200 people with status, attempts, last attempt and error. Resend (or Send for someone never queued) is offered for people who are still eligible and not already waiting; it re-queues that one person, audited.

The email

Plain and short, HTML and text parts, lang="en", an ordered list for the steps, link colours that meet WCAG AA contrast (the brand colour is used for text only when it reaches 4.5:1 on white, otherwise a standard blue; it is always used for the top border). No images (no logo: Gmail and Outlook strip SVG and data-URI images, and an external image would be a tracking request), no tracking pixel, no external resources, no token: the only links are APP_URL and the contact's mailto:. Every value is HTML-escaped and header values are kept on one line.

Template text, with passkey sign-in on and no standby sentence (the example values are placeholders):

From: Example Org Mail <noreply@example.com> Subject: Your Example Org mail account is ready

Example Org

Hello Alex,

You now have a mail account at Example Org in cmail.

To sign in for the first time:

1. Open https://mail.example.com
2. Choose Sign in with Microsoft and use your work account (alex@example.com).
3. If you are asked to accept the IT policy, read it and accept it.
4. Add a passkey: in the left menu choose Settings > Passkeys, then Add passkey. Do this soon after you sign in. A passkey lets you sign in with your fingerprint, face or PIN if Microsoft sign-in is ever unavailable.

Questions? Contact desk@example.com.

Example Org will never ask for your password by email.

--
Sent by Example Org with cmail.

How to customise

What Where
Organisation name, From address and name, contact Admin > Settings (org name, system email, system From name, support email), or ORG_NAME, SYSTEM_EMAIL, SYSTEM_FROM_NAME, SUPPORT_EMAIL
Link APP_URL
Product name in the text and footer Admin > Settings app name, or APP_NAME
Colour BRAND_PRIMARY_COLOR
Standby sentence Admin > Microsoft 365 sync > Welcome emails
Wording renderWelcomeEmail in packages/shared/src/m365-welcome.ts, in your own fork or deployment branch (keep the tests in welcome.sql.node.test.ts passing: no images, no external links, passkey step only when on)

The web app owns the organisation details, APP_URL and the sign-in settings (Microsoft sign-in and tenant, or the Access bridge), so it saves a snapshot of them (m365_welcome_profile in org_settings) for the Worker when the switch is turned on and when a manager presses Check sending and save organisation details (any welcome action saves it too). Opening the page only reads: after changing them in Admin > Settings or redeploying with new values, the page says the Worker still has the old details; press that button. The preview always shows the current details.

Configuration

Email Worker (apps/email-worker/wrangler.toml, [vars]):

Setting Default Notes
M365_WELCOME_MAX_PER_HOUR 50 Sends per rolling hour, 1 to 500
EMAIL ([[send_email]] binding) — Required. The same binding the web app's outbound mail uses through EMAIL_SERVICE
MAIL_DOMAIN — Required. The From address must be on it or a subdomain

Web app: APP_URL; MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET and M365_TENANT_ID (or a tenant GUID in MICROSOFT_TENANT_ID) for first sign-in, or ACCESS_TEAM_DOMAIN and ACCESS_AUD for the Access bridge; OUTBOUND_PROVIDER, the organisation settings above, and the EMAIL_SERVICE binding (Admin asks the Worker over it whether it can send).

No new cron: it runs on the sync's */15 * * * * schedule.

Runbook

Onboarding a Microsoft 365 organisation end to end? See the onboarding guide, step 8.

  1. Apply migration 0029 (pnpm db:migrate; owner's yes for a live database). Deploy the email Worker, then the web app.
  2. Make sure first sign-in works (see First sign-in: try it with one synced test account), the sync and Cloudflare Email Sending for the From domain all work. Send yourself a normal test message first.
  3. Open Admin > Microsoft 365 sync. Read the preview; set the standby sentence if you want one.
  4. With the sync in dry run, turn welcome emails on ("only people created from now on"). The next run lists who would be emailed.
  5. Before the first live send, pick one test account in Microsoft 365, let the sync create it (dry run off), and check the email in Exchange message trace and in that Inbox.
  6. Then, if you want, use Send on the people already waiting, a few at a time, or turn the switch off and on again with "also the N already waiting".

Failed rows. E_RECIPIENT_SUPPRESSED: the address bounced before; check it, unblock it in Cloudflare, then Resend. outcome_unknown: check Exchange message trace before pressing Resend. Last result "stopped by Cloudflare Email Sending" with E_SENDER_*: the From domain is not (or no longer) onboarded to Email Sending.

Limits