Rules

This page shows how to apply your mail rules to the mail that is already in a folder, to test them or to sort an old mailbox. The rules themselves are written in init.lua: see Rules for mail.

Try the rules first

tcli rules --dry-run

tcli rules loads the scripts, so the rules of init.lua are defined, and applies them to the newest 50 messages of INBOX. With --dry-run it changes nothing and shows each step as planned:

Dry run: nothing is changed.
Weekly digest (newsletter)
  mark_read: planned
  create_folder: planned Newsletter
  move: planned Newsletter
Looked at 2 message(s) in INBOX of work: 1 matched, 0 step(s) done, 0 failed.

Each message that a rule matched is listed with its subject, the names of the rules that matched and the steps (mark_read, flag, create_folder, move, and run, which is always skipped). The last line counts the messages looked at, the ones that matched and the steps.

Apply them

tcli rules

The same run without --dry-run writes the changes. A step has one of four states: done, planned (a dry run), skipped or failed. Close Tilde first if it works on the same Maildir.

Pick a rule, an account or a folder

tcli rules newsletter
tcli rules --account work --folder Lists --limit 200

• The name selects one rule. The other rules are not looked at, so the stop of one of them does not matter. A chat rule cannot be applied here: chat rules follow the messages that arrive, and the command says so (exit code 2).
• --account is the id of the mail account. Without it the only mail account is used; with more than one it is an error. The command connects only that account.
• --folder is the folder, INBOX by default. A rule with no folder condition sees only INBOX, so for another folder the rules need folder = "...".
• --limit is how many of the newest messages to look at (50 by default, at least 1).

What it does not do

• The run functions of the rules are not called. They are for the mail that arrives: tcli watch shows when a rule fired on it.
• When a script fails, no rule is applied, because a rule may be half defined. Fix the error with tcli scripts first.
• tcli rules publishes no event, so tcli watch does not show its steps.

Exit codes

• 0: the run finished.
• 1: a step failed, a script failed, the login failed or the folder does not exist.
• 2: the account, the rule or the limit cannot be used.

Every option is in the reference of tcli.