Rules
Philosophy
Section titled “Philosophy”Rules are data first. mxr lets you inspect, dry-run, enable, disable, and audit them before trusting them on live sync traffic.
mxr rulesmxr rules show RULE_IDmxr rulesmxr rules add "Archive newsletters" --when "label:newsletters unread" --then archivemxr rules edit RULE_ID --then mark-read --disablemxr rules validate --when "from:billing@example.com" --then "add-label:finance"mxr rules enable RULE_IDmxr rules disable RULE_IDmxr rules delete RULE_IDmxr rules dry-run RULE_IDmxr rules dry-run --allmxr rules historyWord matching
Section titled “Word matching”A plain word in a condition matches anywhere in the message body, ignoring
case, so invoice also fires on “invoices” and “reinvoiced”. This is unchanged
for existing rules.
+word matches the whole word, ignoring case: +invoice fires on “Your
invoice.” but not on “invoices”. Punctuation in the word is literal, so +c++
matches “c++” and nothing else.
The Rules page gives you:
- Rule list on the left
- Guided workspace on the right
- Overview, History, Dry Run, and Edit states
- Multiline condition/action editing
- Starter examples and validation help in the form flow
Open it from:
gthenRCtrl-pthenOpen Rules Page
Common actions:
c: new ruleE: edit rulee: enable or disableD: dry-runH: historyEnter: refresh overview for the selected ruleCtrl-s: save the current form#: delete
Sort mail into Messages, Updates or Reading
Section titled “Sort mail into Messages, Updates or Reading”mxr status --format jsoncat > sorting-rule.json <<'JSON'{ "id": null, "account_id": "ACCOUNT_UUID", "name": "Weekly reading", "condition": "from:editor@example.com subject:weekly", "action": "treatment:reading", "priority": 100, "enabled": true}JSONmxr rules --format json treatment-preview --form sorting-rule.jsonmxr rules --format json treatment-apply --form sorting-rule.json --preview-token PREVIEW_TOKENReplace ACCOUNT_UUID with the account_id from the matching entry in
sync_statuses (match on account_name) and PREVIEW_TOKEN with the preview
token. --form - reads JSON from stdin.
To preview a saved rule, pass its name or ID instead of --form; apply it with
mxr rules treatment-apply RULE PREVIEW_TOKEN. The preview returns a token and
up to 200 recent messages, each with its current place, proposed place and
reason. complete: false means older mail was excluded. Apply requires the
unchanged token; if mail, rules or personal choices changed, preview again.
Tokens remain valid for up to ten minutes and can be used once.
Sorting accepts header conditions such as sender, recipient, subject, labels, date and flags. Body and link-density conditions are rejected. The preview includes inbound inbox mail; archived, trashed and outbound mail is excluded. Lower numeric priority wins. Equal priorities use rule ID order, so the winner stays stable. Personal sender preferences and message corrections keep their existing precedence and appear in the preview when they prevent a change.
Saving a rule sorts future arrivals. Editing, disabling or deleting it leaves historical placements in place; apply a new preview to change the selected existing mail. Ordinary sync replay preserves those placements. The explanation names the source rule and identifies deleted, disabled or earlier versions. Account scope covers every action in the rule. Apply changes only sorting; label, archive and other existing actions retain their ordinary sync behavior.
In the TUI, choose c or E, set the account, condition and
treatment:messages, treatment:updates or treatment:reading. Space cycles
accounts in the Account field. Ctrl-d previews the draft; D previews a saved
rule. Press A on the preview to save and apply it. Ctrl-s saves for future
arrivals.
In the web Rules editor, select an account and Sort into Messages,
Sort into Updates or Sort into Reading. Review the before/after places
and reasons, then choose Apply to… and confirm. Save rule affects future
arrivals. The MCP tool mxr_sorting_rule accepts the same draft fields and a
messages, updates or reading treatment. Omit preview_token to preview;
pass the returned token to apply. mxr_rule_form reads an existing rule before
editing. The sorting tool preserves its other actions. Scoped MCP profiles can
read and edit only rules within their allowed accounts.
The bridge exposes POST /api/v1/platform/rules/treatment with a form object
and optional preview_token. It uses the bridge’s bearer-token authorization.
The response contains token, applied, rule_id and result, with the same
selection and explanations as the CLI and TUI.
Prefer a forward fix if sorting needs repair. Before downgrading to a binary
without sorting support, remove or migrate every account-scoped rule and
remove all set_treatment actions using the current binary. Disabling rules
is insufficient: older binaries deserialize every stored rule before filtering
by enabled state, and cannot read the new action. They also ignore account
scope, so remaining label, archive or shell actions could run across accounts.
The additive storage migration can remain; historical sorting is displayed
only by binaries supporting it.
Supported actions
Section titled “Supported actions”archivetrashstarmark-readmark-unreadadd-label:NAMEremove-label:NAMEshell:COMMANDtreatment:messages,treatment:updates,treatment:reading
Body-derived conditions
Section titled “Body-derived conditions”Rules can match on classifications computed from the message body during sync:
has:link— the body contains at least one external link (excluding trackers / unsubscribe / list-management URLs).has:link-heavy— link-dense newsletter-shaped mail. Useful for “auto-archive link-heavy mail from unknown senders”.has:link-none— body has no external links at all.
To populate the link classification on messages synced before mxr 0.6, run
mxr doctor --recompute-link-counts once. New mail is classified automatically
during sync.
Runtime behavior
Section titled “Runtime behavior”- Rules run after sync writes messages locally.
- Matching is deterministic and priority ordered.
- Execution history is stored in SQLite.
- Shell hooks are opt-in escape hatches, not the foundation.
- Sync-time execution and dry-run share the same rule model.
Preview selection and missing data
Section titled “Preview selection and missing data”mxr rules --format json dry-run RULE_IDmxr rules --format json dry-run --all --after 2026-03-10An ordinary dry run examines at most the newest 10,000 stored envelopes per
account, then applies --after (inclusive, midnight UTC). --all selects all
enabled rules; it does not scan the entire mailbox. Selecting a disabled rule
by name or ID previews it so you can check it before enabling it. Account-scoped
rules match only that account, and label conditions use provider label IDs.
Preview returns each rule’s matching message IDs and actions without executing
actions or hooks. It does not simulate effects from earlier actions.
Preview and sync use the stored link and word counts for has:link,
has:link-heavy and has:link-none, including negated conditions. Body text
conditions read the message text without HTML markup: the stored plain part and
the HTML part converted to text, the same text search matches. Tags, style
rules and script contents never match. Neither path fetches a missing body. For ordinary rules a missing body
makes a body predicate false, so its negation is true. Rules containing a
sorting action instead keep missing body data unknown, even under NOT; they
match only when the whole condition is known true. An empty stored string is
known data, not a missing body. The sorting editor requires header predicates
as described above.
Pass stored mail to a shell hook
Section titled “Pass stored mail to a shell hook”mxr rules edit RULE_ID --then 'shell:/absolute/path/to/process-message' --disablemxr rules --format json dry-run RULE_IDmxr rules enable RULE_IDmxr rules --format json history RULE_IDUse only commands you trust. An enabled matching rule runs its configured
command through sh -c with your OS privileges. The command receives private
mail as JSON on stdin; it can transmit that data if you configure it to do so.
Mail text is serialized data, never interpolated into the command.
The existing payload fields are:
id: stored message ID.from: stored sendername(ornull) andemail.subjectanddate: stored subject and RFC 3339 message date, not hook time.body_text: stored plain text;nullfor missing or HTML-only bodies. An empty plain-text body remains"". Unlike body matching, hooks do not put HTML into this plain-text field.attachments: storedfilename,size_bytesandlocal_pathfor each attachment. A path is included only if the cached file can currently be opened and is a regular file; otherwise it isnull. Files can disappear after this check, so the command must handle a missing file.
Hooks do not download bodies or attachments. [general].hook_timeout defaults
to 30 seconds and covers JSON preparation, stdin delivery and command waiting.
A stalled stdin is subject to the same deadline. On timeout mxr kills and
reaps its direct child, allowing up to one additional second for cleanup;
cancellation also kills that child. This does not supervise the command’s
descendants or detached processes. A hook finishes when its shell exits, even if
a background process it started still holds the output pipe open; a failed hook
keeps the stderr it wrote, collected for up to 250 ms after exit. Nonzero exits
and timeouts appear in rule history.
Recommended workflow
Section titled “Recommended workflow”- Create a rule with
mxr rules addorcin the TUI. - Validate it with
mxr rules validate. - Dry-run it before save or enable.
- Let sync execute it automatically.
- Inspect
mxr rules historyor the Rules history pane if anything looks off.