Stanchion docs

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


Focused Inbox

Focused and Other tabs above the Inbox, like Outlook's Focused Inbox. Mail from people stays in Focused; newsletters, notifications and other automated mail go to Other. It works for every cmail mailbox, personal or shared, whatever the mail came through (Cloudflare Email Routing, the Exchange mirror, or another cmail mailbox).

Status: built, off by default, covered by unit, database and browser tests. Not yet tried on a live deployment.

What people see

Turning it on and off

There are two switches.

Switch Where Default Who
Organisation Admin > Settings > Focused Inbox Off Managers
Per mailbox Mail > Settings > Focused Inbox On, once the organisation switch is on Anyone with Full access to that mailbox

Both switches are recorded in the audit log (org.focused_inbox_toggled, focus.mailbox_toggled).

How a message is sorted

Only a message that is still going to the Inbox after the organisation's spam filing (Spam and quarantine) and the mailbox's inbox rules is sorted. A message a rule files to Archive, or that lands in Spam, gets no tab.

Sorting is deterministic and explainable. It uses the sender address, a few standard headers, and this mailbox's own history. No message content is read, no AI is used, and nothing leaves cmail. The first signal that applies decides, in this order:

# Signal Goes to Reason code
1 The mailbox has an entry for this exact sender address the entry's tab sender_override
2 The mailbox has an entry for the sender's domain (or a parent domain: example.org covers news.example.org) the entry's tab domain_override
3 The message is a delivery status report (Content-Type: multipart/report; report-type=delivery-status, RFC 3464): a bounce about mail you sent Focused delivery_report
4 Auto-Submitted with any value but no (RFC 3834): out-of-office and other machine replies Other auto_submitted
5 Authenticated sender this mailbox has sent mail to (To, Cc or Bcc of its newest 2,000 Sent messages), even if the message has list headers Focused correspondent
6 List-Id (RFC 2919) or List-Unsubscribe (RFC 2369) Other mailing_list
7 Precedence: bulk, list or junk (widely used, not a standard) Other bulk_precedence
8 Authenticated sender whose domain is exactly MAIL_DOMAIN (or, for mail from another cmail mailbox, that mailbox's domain) Focused internal
9 The sender address looks automated: the part before @, without +tag and . _ -, starts with noreply or donotreply, or is notification(s), newsletter(s), news, marketing or mailer Other automated_sender
10 Personal mailboxes only: 20 or more of the mailbox's newest 500 Inbox messages are from this exact address, and it has never been written to Other frequent_sender
11 Anything else Focused default

Authenticated means the From address is proven:

So a forged From never earns a place in Focused as a "correspondent" or "colleague", and the message view never says "The sender is in your organisation" for an unproven sender.

Focused is the safe default: a person in Other costs more than a newsletter in Focused, so every Other signal is specific, and a person's own entries always win. moved marks a message someone moved by hand.

Notes on the signals:

Learning: move and "always move"

Sorting mail that already arrived

When sorting is on for a mailbox, its newest 1,000 never-sorted Inbox messages are sorted once, in the background:

What does not change

Storage, privacy and audit

Where What
messages.focus_class focused, other, or NULL (never sorted)
messages.focus_reason One reason code from the table above (at most 32 characters)
focus_mailbox_settings One row per mailbox that changed its setting or was sorted: on/off, and the state of the one-off sort
focus_sender_overrides The per-mailbox entries: kind (address or domain), the lower-cased address or domain, the tab, who added it and when
org_settings key focused_inbox_enabled The organisation switch (true = on)

Logs carry no addresses, subjects or content. Audit details carry counts and kinds only.

What it costs, on and off

With the organisation switch off (nothing is cached; each request reads the switch afresh, so turning it off takes effect at once):

With the switch on, each Inbox delivery's lookup also reads the mailbox's entries and, when needed, scans its newest 2,000 Sent messages and counts the sender in its newest 500 Inbox messages; the decision is one extra UPDATE in the same D1 batch as the message row. On the Exchange mirror each Inbox copy then counts one more subrequest against M365_JOURNAL_SUBREQUEST_BUDGET. If the lookup fails (for example, the migration is not applied), the message is delivered with no tab and one line is logged per isolate.

The switch read is not cached between requests: a per-request cache saves nothing (each request reads it once), and an isolate-level cache would keep showing tabs for a while after a manager turns the feature off.

Upgrade

Migration 0031_focused_inbox.sql: additive only. Two nullable columns on messages, one partial index (idx_messages_inbox_focus, Inbox rows only), two new tables and one trigger. No existing row changes. Apply with the normal pnpm db:migrate before (or together with) deploying the web app and the email Worker. SQLite checks each ADD COLUMN ... CHECK against every existing row, and building the index reads the table again: three passes over messages. On a large database, run it outside busy hours.

Code deployed before the migration is safe: with the tables missing, the switch reads as off and nothing new is written.

Limits and known gaps

Code and tests