For MailRules v0.3.0View this page on GitHub

Rules

Write rules in plain English or as conditions, choose what they do, test them on recent mail, and import or export them as YAML.

A rule says which emails it is for and what to do with them. It can describe the emails in plain English (“receipts and invoices for purchases”), with conditions (“sender domain is one of shop.example.com, billing.example.net”), or both.

  • A rule made only of conditions is decided on your machine, instantly and for free. No email is sent to a model.
  • A rule with a plain-English description needs the decision model (see Decision models and keys). If it also has conditions, the model is asked only about emails that match them.

How an email is decided

Rules are checked in the order shown on the Rules screen, top to bottom. For each new email:

  1. Your own mail is left alone. With Leave my own emails alone on in Settings (the default), mail sent from the mailbox’s own address is never sorted, trashed or sent to a model.
  2. Sender rules come first. If you have said what to do with this sender, or MailRules has learned it, that decides the email without a model. See Sender rules.
  3. Rules are walked in order. Rules that are off, apply to another mailbox, have conditions the email does not match, or have an “unless” that it does match, are skipped.
  4. The first condition-only rule that matches ends the walk. Plain-English rules above it that matched their conditions (or have none) become candidates. Plain-English rules below it are not considered.
  5. With no candidates, that condition-only rule acts, or, if none matched, nothing happens and the email stays where it is (“No rule matched”).
  6. With candidates, the decision model reads the email and picks the one it matches, or none of them, with a confidence between 0 and 1. If it is unsure, the fallback model is asked too.
    • At or above the rule’s threshold, the rule acts.
    • Below it, nothing is done and the email waits in Needs review.
    • If the model picks none, the condition-only rule from step 4 acts, if there was one.
  7. Stacking rules add to the result. A condition-only rule with Stacks on also applies after another rule matched, for example to flag anything that fails DMARC wherever it goes.

The default threshold is 75%, set in Settings as Act at … or above. A rule can set its own.

An email that no rule matches is not put in Needs review; it simply stays in the inbox. Needs review is for emails a model was unsure about, and for emails that only a plain-English rule could take while no model is set up.

Adding rules

Add rules in the sidebar offers three ways.

Describe it

Write what should happen in your own words, for example “Bank statements go to Finance and mark them read. Archive LinkedIn profile-view emails.” and click Turn into rules. The rule composer, an AI model, turns the text into one or more draft rules. Nothing is saved yet: each draft shows what it will do, whether it overlaps an existing rule, and, when a mailbox is connected, how many of your recent emails it would have matched. Rename drafts or skip the ones you do not want, then save them. Saved rules go to the bottom of the list and apply from the next email on.

The composer sees what you typed, your existing rules and your folder names, not your email. It needs a model, Claude Haiku 4.5 by default; see The rule composer.

When it checks drafts against your recent mail, it reads the newest 200 emails of the mailbox without marking them read. For drafts with a plain-English description it asks the decision model about each email that passes the conditions, and those calls are counted in Usage.

Build with conditions

Build a rule field by field:

  • Rule name.
  • Conditions (optional), matched when the email meets all or any of them. Click Add condition for another row.
  • And the email is about, a plain-English description checked by the decision model. Leave it empty for a condition-only rule.
  • Except when I’ve replied to the sender before.
  • Then: what to do (see Actions).
  • More options: which mailbox the rule applies to, whether it stacks, and its threshold.

The panel on the right shows the rule In plain words and whether it needs a model. New rules go to the bottom of the list.

Templates

Ready-made rules: Newsletters, Receipts, Login codes, Cold sales, Recruiters, Travel, Social notifications, Bank statements and Calendar invites. Each card says whether it is condition-only or needs the model, and what it does. Add rule saves it at the bottom of the list, switched on. Folders it moves mail to are created in your connected mailboxes; with dry-run on, a folder is created only when the first email is really moved there.

The mailbox wizard offers five of these as starter rules.

Cold sales trashes pitches at 90% confidence or above, but not from a sender you have replied to before, as with Recruiters.

Conditions

The builder offers these fields:

Field in the builder YAML field Operators in the builder
Sender address from is any of, contains any of, matches pattern
Sender domain from_domain is any of, contains any of, matches pattern
Sent to (alias) to is any of, contains any of, matches pattern
Subject subject is any of, contains any of, matches pattern
Body text body is any of, contains any of, matches pattern
Mailing list (List-Id) list_id is any of, contains any of, matches pattern
Has an attachment has_attachment is yes, is no
Attachment type attachment_ext is any of, contains any of, matches pattern
Size (KB) size_kb is more than, is less than
Sender is a contact is_contact is yes, is no
I’ve replied to sender replied_before is yes, is no
Bulk or newsletter is_bulk is yes, is no
DMARC result dmarc is any of

How they match:

  • Text comparisons ignore case. Several values are separated by commas in the builder, or written as a list in YAML; the condition matches if any value does.
  • Sender domain also matches subdomains: example.com matches mail from news.example.com.
  • Body text searches the first 2000 characters of the email’s plain text (the MAILRULES_BODY_CHARS setting).
  • Matches pattern is a regular expression (RE2 syntax, case-insensitive, at most 200 characters).
  • Attachment type is the file extension without the dot, such as pdf or ics.
  • Sender is a contact and I’ve replied to sender are both true when you have sent mail to the sender’s address. MailRules learns this from your Sent folder.
  • Bulk or newsletter is true when the email has a List-Unsubscribe header or a Precedence of bulk or list.
  • DMARC result is pass, fail or none, as your mail server recorded it.

YAML and the HTTP API can do more than the builder:

  • More fields: cc, delivered_to, is_noreply (the sender’s address is a no-reply one), age_days (days since the email arrived), account (the mailbox the email is in: in YAML its address, such as account: [email protected]; in the HTTP API its number), and header:<Name> for any header, such as header:X-Mailer.
  • More operators. Text fields take eq, ne, in, contains, contains_any, not_contains, matches and exists. Yes/no fields take eq and ne. Numbers take eq, ne, gt and lt. dmarc and account take eq, ne and in.
  • Nested all and any groups. There is no not; use ne, not_contains, exists: false, or the rule’s unless.

Editing such a rule with Edit conditions in the builder can lose what the builder cannot show, so keep those rules in YAML.

Actions

In the builder YAML What it does
Move to folder move:<folder> Moves the email to that folder, creating it if needed.
Archive archive Moves it to the folder your server marks as Archive. On a server with no Archive folder but a folder of all mail, such as Gmail’s All Mail, it moves it there.
Move to Trash trash Moves it to MailRules Trash, or to your real Trash (see below).
Keep in Inbox keep Leaves it where it is, and records that a rule took it.
Keep in Inbox and flag keep, flag Leaves it and flags it.
Also mark as read read Marks it read.
(YAML only) junk Moves it to the folder your server marks as Junk.
(YAML only) flag, unflag, unread Sets or clears the flag, or marks it unread.

Actions run in the order listed. If one fails, the rest are not tried, and the failure shows in Activity.

  • Archive and junk use only the folder your server marks with that role. MailRules never creates one; if your server has none, the action fails. The exception is a server that has a folder of all mail instead, such as Gmail: Archive moves mail there, which on Gmail takes it out of the inbox. Use a move to a named folder instead.
  • Trash goes to a folder named MailRules Trash by default, created the first time it is needed, not to your mailbox’s Trash. Providers empty Trash on their own (iCloud after 30 days), and a wrongly trashed email could be gone before you notice. MailRules never empties MailRules Trash; empty it yourself when you like. To use the real Trash, untick Send trashed mail to MailRules Trash in Settings.
  • A rule that trashes based on its plain-English description needs a threshold of at least 85%. When you add one in the UI without a threshold, it gets 90%.
  • Nothing is ever deleted permanently. Moves use IMAP MOVE where the server has it; otherwise MailRules copies the email and removes only that one message from the old folder.

Managing rules

The Rules screen lists every rule in the order it is checked, with what it does, how often it matched this week, and when it last matched.

  • Drag a rule, or use its up and down buttons, to change the order.
  • Untick On to pause a rule without deleting it.
  • Click a rule to edit it:
    • Name, and the plain-English description under When the email is about.
    • Applies to: All mailboxes, or one mailbox.
    • Stacks: also applies after another rule matched (condition-only rules).
    • Notify (hosted version only): the destinations told each time this rule acts on an email. See Notifications below.
    • Model: Default, or a specific decision model for this rule: Jev, Clef, Claude Haiku 4.5, OpenAI-compatible… (openai:<model>), Ollama… (ollama:<model>) or Other (name:model)…. The last three ask for the model name and save it when you click Set model; MailRules shows its own message if the value is not accepted. A model set another way, such as in an imported YAML file, is shown as it is and is not changed unless you set another. The key or URL for that model must be set too. When several candidate rules name a model, the highest one in the list decides which model is asked.
    • Act when sure above: this rule’s threshold, from 50% to 99%. It applies only to rules with a description.
    • Edit conditions opens the rule in the builder.
    • Rewrite with AI: say what should change (“also skip anything from my bank”), compare Current rule and New draft, then Update rule or Discard.
    • Undo what it did today puts back every email this rule moved today (see Undo and activity).
    • Delete rule. Past decisions stay in Activity under the old name.

Notifications (hosted version)

The hosted version can tell you, or another program, when a rule acts. The free self-hosted build has no notifications, and shows none of this.

  1. In Settings, under Notifications and webhooks, add a destination: a name, the kind, and its address.
    • Slack: the incoming webhook URL of a Slack channel, https://hooks.slack.com/services/….
    • Webhook: any https address (an http one is refused, so the email’s sender and subject are encrypted on the way; a webhook added over http earlier shows Needs a new address and gets nothing until you add it again with https). MailRules sends it JSON for every email a rule that names it acts on, signed with a secret shown once, when you add it. Copy the secret to the server that receives the webhook, which uses it to tell that the notice came from MailRules; you cannot see it again.
  2. Open a rule, and under Notify tick the destinations it should tell. In the builder, the same boxes are under More options. A rule can tell several destinations.

A notice says which mailbox, which rule, what it did and to which folder, who sent the email, its subject, when, and a link to the email in Activity. It never contains the email’s text.

A rule notifies only when it really acts on new mail: not in dry-run, not when Cleanup sorts mail you already have, not when you undo or correct something, and not when one of your sender rules settled the email.

Settings shows the address of each destination cut short, never in full, and lists its Recent deliveries: the last 20, with the rule and whether it was sent or why it failed. Deliveries are kept for 30 days. Removing a destination takes it off every rule that named it.

Testing a rule on recent mail

Under a rule, or in the builder, Test on last 200 emails runs the rule over the newest emails in your inbox and reports how many it would match, and how many would go to the decision model or to Needs review. Change the number to test more or fewer, up to 2000.

A test changes nothing: it reads mail without marking it read, and dry-run does not matter. Rules with a description do call the decision model for each email that passes their conditions, and those calls are counted in Usage. A test needs a connected mailbox, and for rules with a description, a decision model.

To see what your rules (all of them, or only some) would do to mail that is already in a folder, on one mailbox or several, and then do it, use Cleanup (see Undo and activity).

When a mailbox is removed

Removing a mailbox on the Accounts screen never deletes a rule. In the same step:

  • A rule that applies only to that mailbox is kept, switched off, set to no mailbox, and marked Its mailbox was removed.
  • An account condition that names the mailbox is rewritten, so the rule does on your other mailboxes exactly what it did before. “Account is that mailbox” can no longer match and drops out of an any group; “account is not that mailbox” now always holds and drops out of an all group; the mailbox is taken out of an “is one of” list. Exceptions that can no longer apply are removed.
  • A rule that could then never act, because its conditions could only match that mailbox or an exception now always applies, is switched off and marked instead. Its conditions keep everything except the removed mailbox, so you can see what it was for.

A marked rule cannot be switched on until you choose a mailbox for it under Applies to (a mailbox, or All mailboxes), or save new conditions with Edit conditions. Either clears the mark, and you can then turn it on.

Rules that still named a mailbox removed with an older version of MailRules are fixed the same way when the daemon starts.

Sender rules

A sender rule says what to do with all mail from one address, or one domain, before any other rule is looked at. It never asks a model.

Senders lists who emailed you in the last 30 days, with how many emails and the day each last wrote. For each sender choose:

  • Let my rules decide (the default);
  • Always keep in Inbox;
  • Always: <rule>, to send all their mail where that rule sends it;
  • Always move to <folder>, to file all their mail in one of your folders;
  • Always trash.

Like keeping and trashing, a folder chosen for a sender wins over every rule for that sender. Every folder of all your mailboxes is offered, Trash, Sent and Drafts included, except Inbox, which Always keep in Inbox covers. The choice applies on every mailbox the sender writes to: a mailbox that has no folder by that name gets one the first time an email is moved there. In dry-run nothing is moved and no folder is made; Activity shows what would have been moved, and a move can be undone like any other.

Unsubscribe appears beside a sender whose mail offers a one-click unsubscribe link (the kind most newsletters and shops add for Gmail and Yahoo). One click asks the sender’s site to take you off the list, for each of your mailboxes it writes to, and the row then shows Unsubscribed, also after a reload. If the sender had no choice set, its mail is then set to Always trash, so the few emails a list still sends while it takes you off go to Trash. A sender whose mail offers only an email address to write to, or no link at all, shows No unsubscribe link: MailRules never sends email for you, so choose Always trash for it instead. Unsubscribing does not change your mailbox, so it works with dry-run on. MailRules remembers the link only from mail it saw after this feature arrived; an older sender gets the button with its next email. If the site does not answer or refuses, the message says which site, and you can try again.

Learned from your corrections and consistent decisions lists the sender rules MailRules made by itself. Forget removes one.

MailRules learns a sender rule for an address when the model has sent that sender’s last three emails to the same rule, each with at least 90% confidence, and you corrected none of them. For bulk mail that passed DMARC, one such decision is enough. It learns only from decisions made with dry-run off. Correcting an email from a sender removes what was learned about that sender.

You can also make a sender rule when you correct an email or answer Needs review: tick Always do this for … and choose Everyone at <domain> or Only <address>. A rule for a whole domain is refused for public email providers, where anyone can have an address.

Import and export as YAML

Rules can be kept in a YAML file: to back them up, edit them in a text editor, or copy them to another install. On the Rules screen, Export rules downloads mailrules-rules.yaml and Import rules reads one.

defaults:
  decision_model: jev
  fallback_model: claude-haiku-4-5
  min_confidence: 0.75
rules:
  - id: Food
    said: "Put everything from the food delivery apps in Food"
    match:
      from_domain: [orders.example.com, delivery.example.net]
    actions: ["move:Food"]
  - id: Recruiters
    when: "Recruiter outreach about job openings"
    match:
      is_bulk: false
    unless:
      replied_before: true
    actions: ["move:Jobs"]
  - id: Newsletters
    match:
      any:
        - {field: list_id, op: exists}
        - {field: subject, op: matches, value: '^issue \d+'}
    actions: ["move:Reading", read]
  - id: Flag failed DMARC
    match:
      dmarc: fail
    actions: [flag]
    stack: true
  - id: Scams
    when: "Phishing, scams or fake bank alerts"
    actions: [trash]
    min_confidence: 0.9

Each rule has:

Key Meaning
id The rule’s name. Required and unique.
when The plain-English description the decision model checks.
match Conditions.
unless Conditions that exclude an email.
actions Required. A list such as ["move:Food", read]; a folder name with a colon must be quoted. {type: move, folder: "Money: 2026"} works too.
min_confidence The rule’s threshold, from 0 to 1.
model The decision model for this rule, such as jev, clef, anthropic, or ollama:<model>.
applies_to The address (login) of the mailbox the rule is limited to, as shown under Applies to in the rule’s options. Left out, the rule applies to every mailbox. See below.
stack true for a stacking rule. Stacking rules must be condition-only.
enabled false to import the rule switched off.
mailbox_removed true on a rule whose mailbox was removed (see When a mailbox is removed). Such a rule is imported switched off and marked, whatever enabled says, and cannot have applies_to. Left out for every other rule.
said Your original wording, shown under “You said”.
template The template the rule came from.

match and unless take either a short form, where each key is a field and every entry must hold (a single value means equals, a list means any of), or a full tree of all and any groups whose entries are {field, op, value}.

The order of the rules in the file is the order they are checked.

The defaults block holds three optional keys:

  • min_confidence applies to every rule in the file that sets none. An export does not write it: it writes each rule’s own threshold, and leaves a rule without one to follow Settings.
  • decision_model and fallback_model say which models the rules were written for. An import never changes them, because the models are settings of the install, and a file passed around must not change which paid model someone uses. An export writes the models in force. An import accepts a file whose models are the ones in force here (decision_model: jev also matches jev with any model of its own), and refuses one that names other models, saying which, so nothing is saved until you change the model in Settings or delete that line from the file.

applies_to names a mailbox by its address, not its number, so a file works on another install. The address is the account’s username, matched ignoring case. An import refuses a file when a rule’s mailbox is not connected here, or when two connected mailboxes have that address, so a rule never quietly starts acting on every mailbox: add the mailbox first. A file that says nothing leaves a rule’s mailbox as it is, so files from before this key existed are still importable. To widen a rule from a file, write applies_to: all.

An account condition, in match or unless and at any depth, names mailboxes the same way: account: [email protected], or a list such as account: [[email protected], [email protected]] for any of them. An import refuses an address that no connected mailbox has, or that two have, and refuses a number (account: 3), which would mean a different mailbox, or none, on another install.

How an import works:

  • It is all or nothing. If any rule is invalid, nothing is saved, and every problem is listed.
  • A rule whose name already exists is replaced. It keeps its place in the list; whether it is on comes from the file. It keeps its mailbox unless the file has applies_to, and it keeps the destinations it notifies, which a file never carries. A rule here that is marked Its mailbox was removed stays switched off and marked when the file has neither applies_to nor different match or unless for it, since the file chose no mailbox and no new conditions for it.
  • Rules with new names are added at the bottom, for the mailbox in applies_to or, without it, all mailboxes.
  • Rules that are not in the file are left alone. An import never deletes a rule.
  • A file can be at most 1 MB.
  • A rule with mailbox_removed: true and applies_to is refused: the file says both that the rule has no mailbox and which mailbox it has. Delete one of the two.

An export writes applies_to for every rule that is limited to a mailbox, the addresses of the mailboxes in account conditions, and the models in force under defaults. A rule whose mailbox was removed is written with enabled: false and mailbox_removed: true, and no applies_to. Removing a mailbox takes it out of every rule, so no rule names a mailbox that no longer exists and the export always works.

From the command line

mailrules rules export rules.yaml      # without a file name, it prints to standard output
mailrules rules import rules.yaml
mailrules rules validate rules.yaml
mailrules rules test rules.yaml --eml ./samples
  • export and import work on the database in the data directory (MAILRULES_DATA_DIR), and need the admin account to exist. A running daemon uses imported rules from the next email on.
  • validate checks a file without touching the database: it prints rules.yaml: 5 rules ok, or each problem with the rule’s number and name. It checks that account conditions name mailboxes by address, but not that those mailboxes are connected; import does that.
  • test runs the rules in a file over every .eml file directly inside a directory, with conditions only. It never asks a model and uses no database, so it prints which rule each email would go to, needs a model with the rules the model would choose between, or no rule matches. Attachments are not known from a .eml file, so has_attachment and attachment_ext never match, and is_contact and replied_before are always false. A .eml file is in no mailbox, so an account condition with eq or in never matches and one with ne always does.

With Docker, run these inside the container, for example docker exec mailrules /mailrules rules export; see Install for the other setups.

Tell your inbox what to do. Then stop thinking about it.