Docs / Obsidian Mail Server / Mail flow
Mail flow rules
Mail flow rules act on messages while they pass through the server, before anyone receives them. Use them to tag mail from outside, add a disclaimer, block risky attachments, copy mail to a supervisor, or redirect mail for someone who has left. They are Exchange's transport rules. Each organization has its own rules, under Mail flow rules.
How rules work
- Every message is checked once, as soon as it is queued: mail arriving from the internet, mail people send from webmail, phones and mail apps, and mail forwarded by inbox rules. Reports the server writes itself (non-delivery reports, incident reports) are not checked.
- Rules run top to bottom. Use the arrows in the Order column to move a rule up or down. A later rule sees what earlier rules changed; for example, it can test a header an earlier rule set.
- A rule applies when all of its conditions are true. A list (of words, people or domains) matches when any entry matches. A rule without conditions applies to every message.
- Exceptions skip the rule: any single exception that is true is enough.
- Conditions about recipients (A recipient is outside the organization, A recipient is one of these people) are checked for each recipient. When a rule changes a message for only some recipients, those recipients get their own changed copy and everyone else gets the original. A disclaimer for outside recipients never appears in the copy colleagues receive.
- Stop checking more rules after this one matches ends the run for the recipients the rule matched.
The sender counts as inside the organization when they signed in to send (webmail, phones, mail apps with a password). Mail arriving from the internet always counts as from outside, even when it claims an address of your own domain; that is exactly the mail a Tag mail from outside rule should mark.
A recipient is inside the organization when the address belongs to a mailbox, group or public folder of the organization, or to one of its domains. Contacts (people outside shown in the address book) are outside.
Building a rule
- Open Mail flow rules and choose New rule.
- Pick a starting point: Tag mail from outside, Disclaimer on outgoing mail, Block dangerous attachments, Copy someone's mail, Redirect someone's mail, or Start from scratch.
- Under Apply this rule if, add conditions with Add a condition.... Type words, addresses or domains and press Enter after each one; addresses suggest people as you type.
- Under Do the following, add one or more actions.
- Optionally add exceptions, start and end dates, and a note about why the rule exists.
- Choose Create rule. It applies to messages queued from then on.
To check a rule before it affects anyone, set Mode to Test: matches are recorded in Track a message as Rule applied, with "matched in test mode" in the details, and nothing changes. Switch it to On when you are happy.
Try a message
Try a message shows which rules would act on a message you describe (sender, recipients, subject, text and attachment names), in order, and for which recipients. Nothing is sent.
Conditions
| Condition | Matches when |
|---|---|
| The sender is inside / outside the organization | See How rules work above |
| The sender is one of these people / a member of this group | Any address of that person counts; groups include nested groups |
| The sender's or a recipient's domain is | The domain or one of its subdomains (example.com also matches mail.example.com) |
| The sender's / a recipient's address includes | Part of the address, for example noreply |
| A recipient is inside / outside, one of these people, a member of this group | Checked per recipient |
| The subject (or body) includes any of these words | Whole words or phrases, upper or lower case alike |
| The subject (or body) matches a text pattern | A regular expression, for example invoice\s*#?\d{4,} |
| A message header includes / matches | The named header, for example X-Mailer |
| The message has attachments | Files attached, including pictures inside the message |
| An attachment's file type is | The extension without the dot: exe, js, zip |
| An attachment's name matches a text pattern | A regular expression on the file name |
| An attachment's content includes | Text inside text, CSV, HTML, Word, Excel and PowerPoint files |
| An attachment / the message is larger than | A size in KB or MB |
| The message is marked as | High, normal or low importance |
| The spam level is at least | The spam confidence level (0-9) the gateway gave the message |
| The message contains sensitive information | See Data loss prevention |
Actions
| Action | What happens |
|---|---|
| Add text to the start of the subject | Adds it once, for example [EXTERNAL] (keep the space at the end) |
| Add a disclaimer | Adds text at the end (or top) of the message, in both its plain and formatted versions |
| Set / remove a message header | For other systems that read headers |
| Add recipients to the To or Cc line | Adds them to the message and delivers to them too |
| Send a blind copy (Bcc) to | Delivers a copy nobody else sees |
| Redirect the message to | Delivers to these people instead of the matched recipients |
| Return it to the sender with a reason | The sender gets a non-delivery report with your reason |
| Delete it without telling anyone | The message is dropped for the matched recipients |
| Tell the sender | A notice to a sender inside the organization; can also stop the message |
| Send an incident report to | A report of what matched, with the message attached |
| Set the spam level | -1 skips junk filtering; 5 or more sends it to Junk Email |
Disclaimers on signed or encrypted mail
A signed or encrypted message cannot be changed without breaking it. For those, choose what the rule does instead: Wrap it (the default) sends a new message with your disclaimer and the original attached unchanged; Send it without the disclaimer; or Return it to the sender.
Seeing what rules did
- Track a message shows Rule applied with what the rule did, Copy made by a rule when recipients got separate copies, Redirected, and Deleted by a rule.
- The Matches column on Mail flow rules counts how often each rule matched, and when it last did.
- Creating, changing, reordering and deleting rules is recorded in Change history.
A rule that fails (for example a text pattern that takes too long) is skipped for that message and noted in Track a message; the message is still delivered.
From the command line
oms transportrule list <org>
oms transportrule show <org> "<name>" (prints the rule as JSON)
oms transportrule new <org> "<name>" --json rule.json [--priority 0]
oms transportrule set <org> "<name>" --json rule.json
oms transportrule enable|disable|remove <org> "<name>"The JSON has the same shape show prints, for example:
{ "conditions": { "fromScope": "NotInOrganization" }, "actions": { "prependSubject": "[EXTERNAL] " } }