For MailRules v0.3.0View this page on GitHub

MailRules user guide

How to install, set up and run MailRules, the self-hosted daemon that sorts your email over IMAP with rules you write in plain English.

MailRules watches one or more IMAP mailboxes and sorts each new email as it arrives, using rules you write in plain English or as structured conditions. A decision model reads the email when a rule needs one; rules made only of conditions need no model at all. Everything runs on your own machine as one program with the web UI built in.

It starts safe. It listens on this machine only, and dry-run is on, so it records what it would do and changes nothing in your mailbox until you switch dry-run off.

Getting started

  1. Install: Docker, Docker Compose, Homebrew, a single binary, or a systemd service.
  2. First run: create the admin account, choose a decision model and connect a mailbox.
  3. Rules: write rules in plain English or as conditions, test them, and import or export them as YAML.
  4. Dry-run and going live: check what MailRules would do, then let it act.

Running it day to day

  • Decision models and keys: Jev, Clef, Claude, OpenAI-compatible endpoints and Ollama; thresholds; keys; what it costs.
  • Undo and activity: see every decision, correct mistakes, undo one email or a whole batch.
  • Summary email: a daily or weekly email of what was sorted, sent through your own mail server.
  • Backup and the master key: what to back up, how to restore, and what losing the key means.
  • Security: the defaults, putting MailRules behind a reverse proxy, and reporting a vulnerability.
  • Troubleshooting: sign-in failures, mail that is not sorted, and reading the logs.
  • Settings reference: every environment variable and flag, with its default.

Other documentation

Every page

  1. InstallRun MailRules with Docker, Docker Compose, Homebrew, a release binary or a systemd service, and upgrade it later.
  2. First runCreate the admin account, choose a decision model, connect your first mailbox and learn what MailRules does next.
  3. RulesWrite rules in plain English or as conditions, choose what they do, test them on recent mail, and import or export them as YAML.
  4. Dry-run and going liveHow dry-run records what MailRules would do without changing your mailbox, how to check its decisions, and how to switch it off.
  5. Decision models and keysChoose the model that decides which rule an email matches, set its keys and thresholds, and see what it costs.
  6. Undo and activitySee every decision MailRules makes, correct the wrong ones, answer Needs review, and undo one email, the last hour, a rule's day or a whole batch.
  7. Summary emailGet a daily or weekly email of what MailRules sorted, trashed and left for review, sent through your own mail server.
  8. Backup and the master keyWhat the data directory holds, how to back it up and restore it, and what happens if the master key is lost.
  9. SecurityMailRules' safe defaults, how sign-in works, how to delete your account in the hosted version, how to put it behind a reverse proxy with TLS, how mail server certificates are checked, which mail servers the hosted version connects to, what is never logged, and how to report a vulnerability.
  10. TroubleshootingFix mailbox sign-in failures, find out why mail is not being sorted, work through Needs review and read the logs.
  11. Settings referenceEvery MailRules setting, as an environment variable and as a command-line flag, with its default.

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