Rules

A rule tags, flags, marks read or moves a new message that meets its conditions. This page explains how to write rules, how they combine and how they treat folders.

A first rule

Declare rules in init.lua with rules.on: a name, the conditions a message has to meet, and the actions to take on it.

rules.on("newsletter", { from = "news@example.com", subject = "test 123", header = { ["List-Unsubscribe"] = true } }, { tag = "vista", mark_read = true, move = "Newsletter" })

rules.list()             -- { "newsletter" }
rules.off("newsletter")  -- removes it; an unknown name is ignored

Try it on the messages already in a folder with a dry run, which changes nothing:

tmail rules run personal INBOX --dry-run

Where rules run

The Lua side only records the definitions; the rule service in the library matches them and acts on the messages.

tmail watch calls the rule service for every new message, after the new_mail handlers have run. It does not rely on IRuleService.OnNewMailAsync, which is there for a host that wants to subscribe the rules to the new-mail watcher on its own.
tmail rules run applies the rules to the newest messages of a folder.

Conditions

Every condition given must hold: they are combined with AND. A rule needs at least one.

Key	Tests	Accepts
`from`	the `From` header as tmail reads it (display name and address)	a string or a list of strings
`to`	the `To` header only; a `Cc` header does not count	a string or a list of strings
`subject`	the subject	a string or a list of strings
`header`	the named headers	a table `{ [name] = value }`, where `value` is a string, a list of strings, or `true`

How they match:

A string matches when the field contains it, ignoring case. It is a substring test: subject = "test" matches “Latest TEST results”.
A list matches when any of its elements does.
header requires every named header to be present. With a string or a list, the header’s value must also contain one of the texts; true only requires that the header exists. Header names are case-insensitive.
When a message has the same header more than once, only the first value is matched.
The body is not matched.
to and header need the message headers. tmail rules run fetches them only when a rule uses one of these keys, by downloading the whole message; from and subject are read from the message list.

Actions

Key	Does	Accepts
`tag`	adds IMAP keywords (tags) to the message	a string or a list of strings
`mark_read`	sets the `Seen` flag	a boolean
`flag`	sets the `Flagged` flag	a boolean
`move`	moves the message to a folder of its account, created when missing	a folder name
`stop`	ends the walk over the rules after this one	a boolean

How several rules combine

A new message is checked against every rule, in the order the rules were defined:

Every matching rule contributes its actions. A rule that does not match contributes nothing, its stop included.
A matching rule with stop = true ends the walk after its own actions. The rules after it are not checked.
Tags are the union of the tags of the matching rules, in order of first appearance, with case-insensitive duplicates removed.
mark_read and flag apply when any matching rule asks for them.
move is the move of the first matching rule that has one; later ones are ignored.

The actions then run in this order, each one a separate call to the server: one keyword per tag, mark read, flag, folder creation when needed, and the move.

Folders

Creation. A move to a folder that is not in the account’s folder list creates the folder first. Created folders are not subscribed.
Names. Names are compared exactly, case included. On a server that treats names case-insensitively, the existing folder is used, and the create folder line of a dry run may be shown although nothing is created.
INBOX. INBOX is the exception: it is matched ignoring case (move = "Inbox" is INBOX) and is never created.
Prefixes. On a server that keeps every folder under a prefix such as INBOX., write the prefix (INBOX.Newsletter). A name without it is refused before anything is created.
Nested names are created one level at a time, split on the hierarchy delimiter the server reports for the personal namespace. With / as the delimiter, Lists/Dev creates Lists when missing, then Lists/Dev. With . as the delimiter, the same name is one folder whose name contains a /. On a server without a hierarchy the whole name is one folder. A name with an empty part, such as Lists//Dev, is an error.
Maildir. On a Maildir account, a move creates the missing Maildir folder with its cur, new and tmp directories.
Once per run. A folder created or found during a run is remembered for the rest of that run, so it is created once. A run reads the folder list at most once, and only when a move needs it.
Already there. A message already in the target folder is not moved, and no step is recorded for it. INBOX counts as the same folder in any case.

Errors and dry runs

Each step is independent. A failing step is logged and reported with its message, and the next step still runs: a tag the server refuses does not stop the move.
The exception is the folder creation and the move: if the folder cannot be created, the move is not attempted and the message stays where it is.
A dry run (tmail rules run --dry-run) lists the steps and makes no change: no tag, flag, folder or move is sent. The folder list is still read, so create folder appears only for a folder that does not exist yet.

Validation

rules.on checks a rule before it registers it:

A rule needs at least one condition and at least one action. A false boolean is not an action, so { mark_read = false } alone is refused. { stop = true } is an action, so a rule whose only action is stop = true is allowed.
An unknown key in either table is an error that lists the valid ones, for example rule 'n': unknown condition 'subjct'; valid conditions: from, to, subject, header.
Wrong types, empty or blank strings (from = "", from = " "), empty lists (from = {}), non-string list elements, an empty or blank move and an invalid tag are errors too. Each error names the rule.
A refused rule is not registered. The rules.on call raises an error; tmail rules run prints it and exits with 1.

Redefining and reloading

rules.on with the name of an existing rule replaces that rule and keeps its place in the order. Names are case-sensitive and must not be blank.
A reload of the scripts forgets every rule; init.lua defines them again.