Skip to content

Rules

Rules are data first. mxr lets you inspect, dry-run, enable, disable, and audit them before trusting them on live sync traffic.

Terminal window
mxr rules
mxr rules show RULE_ID
mxr rules
mxr rules add "Archive newsletters" --when "label:newsletters unread" --then archive
mxr rules edit RULE_ID --then mark-read --disable
mxr rules validate --when "from:billing@example.com" --then "add-label:finance"
mxr rules enable RULE_ID
mxr rules disable RULE_ID
mxr rules delete RULE_ID
mxr rules dry-run RULE_ID
mxr rules dry-run --all
mxr rules history

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:

  • g then R
  • Ctrl-p then Open Rules Page

Common actions:

  • c: new rule
  • E: edit rule
  • e: enable or disable
  • D: dry-run
  • H: history
  • Enter: refresh overview for the selected rule
  • Ctrl-s: save the current form
  • #: delete

Sort mail into Messages, Updates or Reading

Section titled “Sort mail into Messages, Updates or Reading”
Terminal window
mxr status --format json
cat > 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
}
JSON
mxr rules --format json treatment-preview --form sorting-rule.json
mxr rules --format json treatment-apply --form sorting-rule.json --preview-token PREVIEW_TOKEN

Replace 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.

  • archive
  • trash
  • star
  • mark-read
  • mark-unread
  • add-label:NAME
  • remove-label:NAME
  • shell:COMMAND
  • treatment:messages, treatment:updates, treatment:reading

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.

  • 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.
Terminal window
mxr rules --format json dry-run RULE_ID
mxr rules --format json dry-run --all --after 2026-03-10

An 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.

Terminal window
mxr rules edit RULE_ID --then 'shell:/absolute/path/to/process-message' --disable
mxr rules --format json dry-run RULE_ID
mxr rules enable RULE_ID
mxr rules --format json history RULE_ID

Use 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 sender name (or null) and email.
  • subject and date: stored subject and RFC 3339 message date, not hook time.
  • body_text: stored plain text; null for 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: stored filename, size_bytes and local_path for each attachment. A path is included only if the cached file can currently be opened and is a regular file; otherwise it is null. 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.

  1. Create a rule with mxr rules add or c in the TUI.
  2. Validate it with mxr rules validate.
  3. Dry-run it before save or enable.
  4. Let sync execute it automatically.
  5. Inspect mxr rules history or the Rules history pane if anything looks off.