Multi Tenancy Email Routing

Multi-tenancy: email routing & mailboxes

Part of the Multi-tenancy section. Built — live on the multi-tenancy branch. See the progress tracker.

When a multi-tenant install receives an email, it has to decide which company the ticket belongs to. This page explains how — and how it bends to very different ways of working. Everything below is now implemented (the only routing piece still to come is a per-company outbound reply identity override; replies already go out from the mailbox the ticket arrived on).

Domains belong to the company, not the mailbox

Each company registers the email domains it owns — acme.com, and maybe also acme.co.uk. A company can own several domains. Mailboxes do not own domains; companies do.

Every mailbox is one of two types

This is the heart of it — and a perfect example of flexibility living in the entity rather than a global switch. Each mailbox is set up as one of:

1. Pinned mailbox — "this inbox belongs to one company"

• You assign the mailbox to a specific company (and optionally a department).
• The mailbox decides the company. The sender's address is irrelevant — everything arriving here belongs to that company.
• It's also the reply identity: replies to its tickets go back out from this mailbox, so the client sees their own helpdesk end to end.
• Great for: a single company's own helpdesk, or an MSP that dedicates a separate inbox to each client.

2. Shared intake mailbox — "one inbox, sorted by sender"

• The mailbox is not pinned to a company.
• An arriving email is filed by matching the sender's domain against the companies' registered domains (someone@acme.com → Acme).
• An unmatched sender drops into the triage queue (below) — never lost.
• Great for: an MSP running a single professional address like support@themsp.com for all clients. This is the recommended default for MSPs.

A ticket remembers which mailbox it came in on, and replies always go back out from that same mailbox — the mailbox is the company's email identity, both inbound and outbound.

A company can use both at once

A company isn't locked into "one mode". Acme might receive most mail via the shared support@themsp.com and have a dedicated helpdesk-acme@themsp.com for VIPs. Both feed Acme. That's exactly why the pinned-vs-shared choice lives on the mailbox, not on the company.

How an incoming email finds its company (in order)

1. Is it a reply to an existing ticket? → it joins that ticket and inherits its company. (A thread stays glued to one company even if someone replies from a different address.)
2. Did it arrive in a pinned mailbox? → that mailbox's company. Sender ignored.
3. It arrived in a shared intake — most-specific match wins:
   1. The exact sender address is mapped to a company (e.g. jane@gmail.com → Acme) → that company. Checked before the domain, so a personal/webmail address can still reach the right company.
   2. otherwise the sender's domain is matched to a company (someone@acme.com → Acme) → that company.
   3. no match → triage.

In a single-company install only step 2 ever fires, which is why none of this is visible until you add a second company.

The triage queue (the safety net)

When a shared-intake email matches no company domain, it lands in a Triage / Unassigned queue rather than vanishing. From there an analyst can, in one click:

• Create a new company from this domain — and the queued email (plus any others from that domain) is filed under it, with all future mail auto-routing from then on.
• Assign it to an existing company — e.g. a client that just started using a new domain.

Mapping a domain sweeps both ways: it re-files every queued email already waiting from that domain and auto-routes future mail.

Free-email / public senders

Addresses like gmail.com or outlook.com also land in triage — and you should never map a free-email domain to a company (two different clients will both have users on Gmail). In the queue these are tagged Public email and the "route this domain" option is hidden. Instead you get a freemail-safe alternative: "always file mail from this address here", which maps that one exact address to the company (sweeping its other queued mail and auto-routing its future mail) while leaving everyone else on Gmail untouched. See Pitfalls.

The triage queue is reached from the company switcher in the header, which shows a count badge when mail is waiting.

Specific senders (mapping an individual address)

Beyond whole domains, each company can list specific sender addresses (under System → Companies). This is the address-level twin of domain registration, and it's matched before the domain. It exists for the case domains can't cover: a freelancer or micro-client emailing from a personal address (jane@gmail.com) — that one address routes to their company, even though gmail.com itself can never be mapped. You can set these up directly on the company, or create them with one click from the triage queue (above).

Customising the public-email list

The built-in list of public providers (Gmail, Outlook, Yahoo, iCloud, …) is what stops those domains being mapped. If your clients use a regional ISP or webmail host that isn't built in, an admin can add it on System → Companies ("Public email domains") so it's treated the same way. The list is add-only — the built-in providers are locked and can never be un-protected.

Checking routing before you rely on it

Two read-only tools help you see what will happen, without sending anything:

• "How email reaches this company" — on each company's editor (System → Companies), a derived summary of every way mail reaches that company (which pinned mailboxes, which shared intakes, the domains and addresses they match), with warnings for half-configured routes.
• Email routing test (System → Email routing test) — pick a mailbox, type a sender address, and it shows exactly which company a new ticket would land in (or that it'd go to triage) and which rule decided it. It creates nothing; it runs the real routing logic so it can't drift from live behaviour.