Stanchion docs

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


Multiple mail domains

One cmail instance serves one organisation. That organisation may own more than one mail domain: a main domain and others for brands, products or older names. cmail treats all of them as its own, without a domain list to fill in.

Status: built and tested against every real migration, a fake Microsoft Graph and the real send, mirror and admin paths. Not yet run against a real tenant. Sending from domains other than MAIL_DOMAIN is not built yet (What does not change).

In this article

How the domains are found

Domains are discovered and proven, never typed in by a manager:

  1. MAIL_DOMAIN, the primary domain, always first.
  2. The Microsoft 365 tenant's verified mail domains, when the Microsoft 365 sync is on and its app has Domain.Read.All. The sync reads them with Microsoft Graph GET /domains and keeps those that are verified (isVerified), not the tenant's initial domain (isInitial), and set up for mail (supportedServices includes Email). A domain is verified in a tenant only after its owner proves it with a DNS record, so this list is proof of ownership.

Details:

Admin > Microsoft 365 sync shows the list under Status > Mail domains, when it was last read, and any problem.

What uses the list

Everything that used to ask "is this address on MAIL_DOMAIN?" now asks "is it on one of the organisation's domains?". No new switches: each part stays under the switch it already had.

Part With other domains Switch
Microsoft 365 sync People and shared mailboxes whose primary address is on any organisation domain get accounts and mailboxes. Shared mailbox detection and the group checks cover them too. Microsoft 365 sync
Alias import (Exchange mirror) smtp: addresses on every organisation domain become aliases. Alias import
Exchange mirror filing Journal copies are filed for mailboxes on every organisation domain. Once the sync has read the tenant's domains successfully, a mailbox on a domain that is not one of them is counted as unmatched (problem unmatched_domain), never filed. Before that, filing is by address exactly as before. Exchange mirror
Sending to colleagues With Send colleague mail through Exchange on, colleagues on every organisation domain are sent through the provider, so Exchange and Outlook get the message (details). Otherwise delivery is local as before. Exchange mirror + Send colleague mail through Exchange
Admin > Mailboxes, Admin > People A domain picker appears when there is more than one domain. A typed full address must be on one of them. The pickers say that only MAIL_DOMAIN can send for now. none
Delegates and the org chart People whose personal mailbox is on any organisation domain can be delegates; work emails may use any of them. none
Public directory (manager handbook) Public work emails on any organisation domain are listed. Public directory
Focused Inbox A proven sender (DMARC pass at the trusted boundary, an Exchange-authenticated internal submission, or internal cmail mail) on any organisation domain counts as a colleague. Focused Inbox

What does not change

Security

How to turn it on

There is no separate switch. With the Microsoft 365 sync already working:

  1. In the Microsoft Entra admin center, open the sync app's API permissions and add Microsoft Graph > Application permissions > Domain.Read.All, the least privileged permission for listing domains (permissions). Grant admin consent and check it shows "Granted". This is a tenant change: get the owner's yes first.
  2. In Admin > Microsoft 365 sync, turn dry run on, then press Sync now.
  3. Within 15 minutes, check Status > Mail domains lists the domains you expect, and the dry run report shows the accounts and shared mailboxes it would create on them, with no unexpected pauses.
  4. Turn dry run off. The next full reconciliation creates them. If the alias import and the Exchange mirror are on, aliases on the new domains follow on the next import, and journal reports for those mailboxes are filed.

How to roll it back

Troubleshoot

What you see Why What to do
Mail domains: "MAIL_DOMAIN only" and "can't be read: grant the sync app Domain.Read.All" The app has no Domain.Read.All, or no admin consent Step 1 of How to turn it on
A verified domain is missing The read has not run since it was verified Press Sync now
*.onmicrosoft.com is not listed By design Nothing
Mirror day shows unmatched_domain A mailbox is on a domain no longer in the list Check the tenant's domains; the mailbox's mail is still in Exchange
"Sending from @domain isn't set up yet" Sending from other domains is not built yet Send from a MAIL_DOMAIN address
A send to a colleague fails with the provider's setup message while the mirror is on The mirror needs the outbound provider to reach Exchange Set up sending, or turn the mirror off

Upgrade

No migration. The list lives in org_settings, which every instance has. Until the sync app has Domain.Read.All, an instance behaves exactly as before.

Code and tests