Inbox categories

Purpose. Tabs over the Inbox that sort mail by the kind of sender: Primary, Promotions, Social, Updates and Forums, each with its unread count. Sorting happens on the server as mail arrives, from the message’s own headers; no AI is involved.

Behaviour.

• Off by default for every mailbox: its owner turns them on in the webmail’s Settings › Categories, with a switch for each category. A category switched off leaves its mail in Primary. An administrator can turn them off for a whole domain (the domain’s Policy › Categories section); then nothing is tagged for any of its mailboxes, and the webmail hides the tabs and the setting (MailAccount.categoriesAllowed).
• A category is an IMAP keyword on the message: $Category_Promotions, $Category_Social, $Category_Updates, $Category_Forums. Primary carries none. Nothing is moved, so every other mail client sees the Inbox as it always was. Four keywords count against Maildir’s 26 per folder, which is why the label cap is 15.
• How a message is sorted, one category at most, the first that fits in this order:
  1. Social: the sender’s domain is a social network’s own (SOCIAL_DOMAINS in packages/core/src/sieve.ts, with its subdomains: Facebook’s facebookmail.com, LinkedIn, X, Instagram, Reddit, Discord and others).
  2. Forums: a mailing list people reply to: List-Id with List-Post.
  3. Promotions: bulk mail that can be unsubscribed from (List-Unsubscribe with Precedence: bulk), or a send carrying a marketing platform’s own header (Mailchimp’s X-MC-User, SendGrid’s X-SG-EID, Mailgun’s, HubSpot’s and others).
  4. Updates: anything else a program sent: Auto-Submitted: auto-*, Precedence: bulk/junk/auto_reply, or a no-reply sender (no-reply@, noreply@, notifications@, alerts@ and the like).
  5. Everything else is Primary.
• Sorted by hand: More › Move to category on an open Inbox message changes its category at once, and the toast offers Always for . Accepted, the sender is listed under Settings › Categories › Sorted by hand (settings.categories.senders, at most 500) and its mail goes to that tab from then on, whatever its headers say, Primary included. Removing it there hands the sender back to the headers. A sender put in a category that is switched off stays in Primary.
• The tabs: /INBOX?category=promotions (Primary has no parameter). A search or a label filter shows the whole Inbox. Counts come from GET /api/v1/mail/categories ([{ tab, unseen }]), and the list from GET /mail/messages?category=<tab>.
• Only new mail is sorted. Turning categories on does not go back over the Inbox: what was there stays in Primary.

Limits & edge cases. Sorting reads headers only, so a newsletter sent without List-Unsubscribe or a platform’s header lands in Primary, and a person writing from a no-reply address lands in Updates. A sender the rules misjudge stays misfiled until it is sorted by hand. The social-network list is ours to keep. Categories are a webmail feature: an IMAP client sees the keywords only if it shows them.