mailrules

mailrules

Docker app from Simon Lehmann's Repository

Sorts incoming email over IMAP, in real time, using rules you write in plain English or as structured conditions - a self-hosted mail filter with an AI model deciding which rule…

Requirements

The container runs as nobody:users (99:100), not root, and cannot fix folder ownership itself. If it stops on first start with a permission error in the log, open the Unraid terminal and run: chown -R 99:100 /mnt/user/appdata/mailrules (adjust the path if you changed Appdata), then start it again.
Overview
Sorts incoming email over IMAP, in real time, using rules you write in plain English or as structured conditions - a self-hosted mail filter with an AI model deciding which rule an email matches. Works with any IMAP mailbox that signs in with a password or app password (iCloud, Gmail, Fastmail, Yahoo, Zoho, your own server). Outlook.com and Microsoft 365 are not supported by the self-hosted build. Choose the model that decides: a local Ollama server on your LAN (nothing leaves your network), any OpenAI-compatible endpoint, Anthropic, or the hosted Jev/Clef models. Rules made only of conditions, and sender rules, need no model at all. It starts safe: dry-run is on, so it records what it would do and changes no mailbox until you switch dry-run off. It never deletes mail, and every action can be undone for 30 days. Runs as nobody:users (99:100), like other Unraid appdata, with a read-only root filesystem and all capabilities dropped. Back up the whole appdata folder: it holds master.key, without which every stored mailbox password and API key is unrecoverable.

MailRules

Self-hosted email sorting for Unraid. MailRules watches your mailboxes over IMAP and files new email in real time, using rules you write in plain English ("receipts and invoices go to Receipts") or as structured conditions. An AI model decides which plain-English rule an email matches, and it can be your own Ollama server, so no mail leaves your network. Built on TurtleByte-IN/mailrules, via the official ghcr.io/turtlebyte-in/mailrules image (amd64 and arm64).

Status: this template is a working starting point but hasn't yet been through a full install → persistence → upgrade test on real Unraid hardware, so it isn't submitted to Community Applications yet. See Before you rely on this below.

MailRules starts safe: dry-run is on, so it records what it would do and changes no mailbox until you switch dry-run off. It never permanently deletes mail, fetches without marking mail read, and every action can be undone for 30 days.

What works and what doesn't

  • Works: any IMAP mailbox that signs in with a password or app password: iCloud, Gmail/Google Workspace, Fastmail, Yahoo, Zoho, or your own mail server (including one on your LAN).
  • Doesn't work: Outlook.com and Microsoft 365, which only accept Microsoft's own sign-in. The self-hosted build doesn't include it.
  • Proton Mail: upstream says Proton Mail Bridge doesn't work from Docker, because Bridge listens on 127.0.0.1 and inside a container that's the container itself. A Bridge running in its own container and reachable on a LAN or Docker-network address might work, but this hasn't been tested.
  • Not included: "Suggest from my mail" is a feature of the hosted version at mailrules.app only. The free build hides it.

Example architecture

The setup this template is built for: MailRules runs on Unraid, uses an Ollama server you already have, and is reached in the browser through an HTTPS reverse proxy such as Nginx Proxy Manager. It's never exposed to the internet.

        Browser
           │ HTTPS  https://mailrules.home.arpa
           ▼
  Nginx Proxy Manager ──── internal DNS: mailrules.home.arpa → Unraid IP
           │ HTTP  [unraid-ip]:8080
           ▼
       MailRules  ──── IMAP over TLS ────▶  your mail provider(s)
           │
           │ HTTP  [ollama-ip]:11434
           ▼
        Ollama (local model)

None of it is required: MailRules works on its own at http://[unraid-ip]:8080, with a cloud model instead of Ollama, or with condition-only rules that need no model at all.

Installation

1. Install the template

Install from Apps once the template is in Community Applications, or manually before then (see the repository README).

The settings that matter on first install:

Setting Default Notes
WebUI Port 8080 Change it if another container already uses 8080.
Appdata /mnt/user/appdata/mailrules Must be writable by nobody:users (99:100), see Appdata permissions.
Secure Cookie false Leave it false until you have an HTTPS proxy in front, see HTTPS.
Ollama URL empty Optional, see Using Ollama.

Everything under Show more settings is optional. Model choice, thresholds and API keys are easier to set in MailRules' own Settings page, which overrides the environment variables anyway.

2. First run

  1. Start the container and open the WebUI right away. The first visit shows Set up MailRules and creates the only admin account, so don't leave a fresh install sitting unclaimed on a shared network. The password must be at least 12 characters.
  2. Choose a decision model and give it a key, or skip that. Rules built only from conditions, and sender rules, need no model.
  3. Connect a mailbox with an app password (not your normal password, for providers that have them), and pick a few starter rules.
  4. Watch Activity while dry-run is on. When the decisions look right, switch dry-run off.

Upstream's First run guide covers each step in detail.

Appdata permissions

The image is distroless and has no root startup script, so unlike LinuxServer-style images it can't fix the ownership of its data folder itself. Upstream runs it as uid 65532. This template instead runs it as nobody:users (99:100), with --user 99:100 in Extra Parameters, so its appdata is owned like every other Unraid app's.

If the container stops on first start with a permission error in its log, the appdata folder isn't writable by 99:100. Open Terminal in the Unraid web UI and run (adjust the path if you changed Appdata):

chown -R 99:100 /mnt/user/appdata/mailrules

Then start the container again. Note that upstream's own docs say chown 65532:65532. That's for the image's default user, not for this template.

Using Ollama

MailRules talks to Ollama directly. It needs the server URL and a model name, and Ollama costs nothing per email.

  1. Make sure Ollama listens on more than loopback. For the Unraid Ollama container this is already the case. For a standalone install, set OLLAMA_HOST=0.0.0.0.
  2. Set Ollama URL in the template to the server's LAN address, e.g. http://192.168.1.10:11434. Don't use localhost or 127.0.0.1: inside the MailRules container that's the container itself. If both containers share a custom Docker network, the container name works too, e.g. http://ollama:11434.
  3. In MailRules, go to Settings → Decision model, choose Ollama on my server and enter a model name you've pulled (e.g. llama3.2). To do the same through the template instead, set Decision Model to ollama and Decision Model Name to the model.
  4. To have Ollama write rules from your plain-English descriptions too, set Rule composer model to ollama:<model>, e.g. ollama:llama3.2. Its default is Claude Haiku, which needs an Anthropic key, and without a working composer Describe it / Rewrite with AI don't work. Build with conditions and Templates still do.

Without an Anthropic API key, the fallback model (a Claude second opinion when the decision model is unsure) is inactive and MailRules logs a warning saying so. That's expected for an all-local setup: decisions then rest on the local model alone, and any below the Act at confidence threshold wait in Needs review. Upstream's Decision models and keys guide covers the other providers, thresholds and costs.

HTTPS with Nginx Proxy Manager

To use MailRules from other devices, put a TLS reverse proxy in front and reach it only through that. Don't forward the port to the internet: without TLS your password and session cookie travel unencrypted.

Proxy host in NPM:

  • Domain: mailrules.home.arpa (or your own local name), with a DNS record pointing at the proxy.

  • Forward: http → your Unraid IP → 8080 (the WebUI Port).

  • SSL: your internal certificate, e.g. one issued by step-ca via ACME. Turn on Force SSL.

  • Websockets: not needed. MailRules uses server-sent events on /api/events instead, and asks nginx not to buffer them. nginx's default 60s read timeout is enough, because MailRules sends a keep-alive every 25 seconds.

  • Advanced tab: keep the Prometheus metrics endpoint, which needs no sign-in, off the proxy:

    location = /metrics { return 404; }
    

Then update the template and apply:

Setting Value
Secure Cookie true. Signing in at http://[unraid-ip]:8080 stops working, which is what you want.
Public URL https://mailrules.home.arpa, so links in the summary email work.
Trusted Proxies The address MailRules sees requests from: see below.

Trusted Proxies. Failed sign-ins are rate-limited per client address. Behind a proxy every request comes from the proxy, so one person mistyping their password would lock everyone out for a minute. Listing the proxy lets MailRules read the real client address from X-Forwarded-For, which NPM sets. What to list depends on how NPM is networked:

  • NPM on Docker's default bridge network: 172.17.0.0/16.
  • NPM on a custom Docker network shared with MailRules: that network's subnet (docker network inspect <name>).
  • NPM on br0 (its own LAN IP) or on another machine: that single IP, e.g. 192.168.1.20.

Never list a range your LAN clients can reach MailRules from directly, e.g. your whole LAN subnet: anyone in it could then forge their address and get around the limit. MailRules refuses 0.0.0.0/0. Even without this setting, a separate per-account limit still stops password guessing.

Backup and restore

Back up the whole appdata folder, never just the database. It holds:

  • mailrules.db (plus -wal and -shm while running): rules, settings, activity, undo history, and your mailbox passwords and API keys in encrypted form.
  • master.key: the key that decrypts those passwords and keys. If it's lost, every stored mailbox password and API key is gone for good. Rules, settings and history survive, but every app password and key has to be entered again.

The database is written continuously, so copy it with the container stopped. The Appdata Backup plugin does this by default. Treat the backup as sensitive as the passwords themselves: database and key together unlock them.

Upgrades migrate the database on first start, and there's no way to undo that, so back up before every upgrade. The template uses latest, which upstream only moves after a release has passed its install tests. To upgrade only when you choose, change Repository to a pinned version such as ghcr.io/turtlebyte-in/mailrules:0.3.0.

Restore: stop the container, replace the folder's contents with the backup, including master.key, fix ownership, then start:

chown -R 99:100 /mnt/user/appdata/mailrules

If master.key is missing and the database holds stored passwords, MailRules deliberately refuses to start rather than create a new key, and says so in the log. Put the key back and start again. If the key is truly gone, start once with an extra variable MAILRULES_NEW_MASTER_KEY=true (Add another Path, Port, Variable… in the template), then remove it and re-enter your passwords and keys. Details are in upstream's Backup and the master key.

Security considerations

The template applies the same hardening as upstream's Docker Compose file: --read-only root filesystem with a /tmp tmpfs, --cap-drop=ALL, and no-new-privileges. The container runs as non-root nobody:users (99:100) instead of the image's uid 65532, see Appdata permissions.

  • Unraid publishes the port on all interfaces. Upstream's own setup publishes it to 127.0.0.1 only, which doesn't suit a NAS reached from other machines. Keep it LAN-only, and once you use a proxy, set Secure Cookie to true so the plain-HTTP port can't be used to sign in.
  • Secure Cookie = false is only appropriate while you sign in over plain HTTP on a network you trust. It's the template default so the WebUI button works out of the box.
  • API keys entered as template variables are visible to anyone who can run docker inspect. Entering them in MailRules' Settings page instead stores them encrypted with master.key.
  • /healthz, /readyz and /metrics answer without sign-in. They hold no mail or account data.

Troubleshooting

  • Container stops right after starting with a permission error in the log: the appdata folder isn't writable by 99:100. See Appdata permissions.

  • Can't stay signed in / login loops: Secure Cookie is true (or auto) but you're using plain HTTP. Use the HTTPS proxy address, or set it to false for direct LAN access.

  • "the master key is missing": see Backup and restore.

  • Ollama model unreachable: check Ollama URL isn't localhost, and that the Unraid host can reach it: curl http://<ollama-ip>:11434/api/tags.

  • Forgot the admin password: there's no email reset. From the Unraid terminal (the container has no shell, so the Console button won't work):

    docker exec -it mailrules /mailrules users reset-password
    
  • Logs: the container log (Docker tab → mailrules icon → Logs) is JSON lines, and never contains passwords, keys or email text. Set Log Level to debug for more detail.

Upstream's Troubleshooting guide covers mailbox-specific errors (iCloud, Gmail, Reconnect needed, Certificate changed, …).

Before you rely on this

This template hasn't yet been validated end-to-end on a real Unraid host, in particular: whether a fresh appdata folder is writable by 99:100 without a manual chown, sign-in over plain HTTP and through Nginx Proxy Manager, the Ollama connection, and that the database and master.key survive container recreation and an image upgrade. TESTING.md tracks that. If you hit anything that doesn't match what's documented here, please open an issue.

Links

Categories

Related apps

Links

Details

Repository
ghcr.io/turtlebyte-in/mailrules:latest
Last Updated2026-11-19
First Seen2026-11-19

Runtime arguments

Web UI
http://[IP]:[PORT:8080]/
Network
bridge
Privileged
false
Extra Params
--user 99:100 --read-only --tmpfs /tmp --cap-drop=ALL --security-opt=no-new-privileges:true

Template configuration

WebUI PortPorttcp

Port for the web UI and API (plain HTTP). Don't forward it to the internet - put a TLS reverse proxy in front for access from other devices.

Target
8080
Default
8080
AppdataPathrw

SQLite database and master.key. Must be writable by nobody:users (99:100). Back up the whole folder: losing master.key loses every stored mailbox password and API key.

Target
/data
Default
/mnt/user/appdata/mailrules
Secure CookieVariable

Mark the login cookie HTTPS-only (true/false/auto). Leave 'false' to sign in over plain HTTP at http://[IP]:PORT on your LAN. Set 'true' once you reach MailRules only through an HTTPS reverse proxy - signing in over plain HTTP then stops working. 'auto' means true inside Docker.

Target
MAILRULES_COOKIE_SECURE
Default
false
Ollama URLVariable

Optional. URL of your Ollama server, e.g. http://192.168.1.10:11434 - use the LAN IP or container name, not localhost (that is this container). Ollama must listen on more than loopback (OLLAMA_HOST=0.0.0.0). Then choose Ollama and a model in MailRules' Settings, or set Decision Model below.

Target
OLLAMA_URL
Public URLVariable

Where you open MailRules, e.g. https://mailrules.home.arpa. Links in the summary email start with it. Empty uses http://127.0.0.1:8080.

Target
MAILRULES_PUBLIC_URL
Trusted ProxiesVariable

Behind a reverse proxy: the proxy's IP or CIDR range (comma-separated), e.g. 172.17.0.0/16 for a proxy on Docker's default bridge, so failed sign-in limits count each visitor rather than the proxy. Empty trusts no proxy. Never list a range your LAN clients can reach MailRules from directly.

Target
MAILRULES_TRUSTED_PROXIES
Dry RunVariable

Initial dry-run state (true/false). Empty means true: decisions are recorded but no mailbox is changed. Once you switch dry-run in the web UI, that choice wins over this.

Target
MAILRULES_DRY_RUN
Decision ModelVariable

The model that picks which rule an email matches: jev, clef, anthropic, openai or ollama. Empty means jev. Easier to set in Settings in the web UI, which wins over this.

Target
MAILRULES_DECIDER
Decision Model NameVariable

Model name for the decision model, e.g. llama3.2 for Ollama. Required for openai and ollama; empty uses the provider's default for the others.

Target
MAILRULES_DECIDER_MODEL
Rule Composer ModelVariable

Model that writes rules from your words: a Claude model name, openai:MODEL or ollama:MODEL (e.g. ollama:llama3.2). Empty means claude-haiku-4-5, which needs an Anthropic API key.

Target
MAILRULES_COMPOSER_MODEL
Fallback ModelVariable

Claude model asked for a second opinion when the decision model is unsure. Empty means claude-haiku-4-5. Only active when an Anthropic API key is set; to turn it off, clear it in Settings in the web UI.

Target
MAILRULES_FALLBACK_MODEL
OpenRouter API KeyVariable

For the Jev decision model. Keys can instead be entered in Settings in the web UI, where they are stored encrypted (recommended - variables here are visible in docker inspect).

Target
OPENROUTER_API_KEY
Anthropic API KeyVariable

For the fallback model, the Claude rule composer and the anthropic decision model. Can instead be entered in the web UI.

Target
ANTHROPIC_API_KEY
OpenAI-compatible Base URLVariable

Base URL of an OpenAI-compatible endpoint (e.g. LiteLLM, vLLM, LM Studio). Empty means OpenAI itself.

Target
OPENAI_BASE_URL
OpenAI-compatible API KeyVariable

API key for the OpenAI-compatible endpoint. Can instead be entered in the web UI.

Target
OPENAI_API_KEY
Cloudflare Account IDVariable

For the Clef decision model (Cloudflare Workers AI).

Target
CLOUDFLARE_ACCOUNT_ID
Cloudflare API TokenVariable

For the Clef decision model. Can instead be entered in the web UI.

Target
CLOUDFLARE_API_TOKEN
SMTP HostVariable

Optional. Outgoing mail server for the summary email, e.g. smtp.fastmail.com (no scheme or port). Empty disables the summary email.

Target
MAILRULES_SMTP_HOST
SMTP PortVariable

Empty uses the usual port for SMTP TLS: 587 for starttls, 465 for implicit, 25 for none.

Target
MAILRULES_SMTP_PORT
SMTP TLSVariable

starttls, implicit or none. Empty means starttls.

Target
MAILRULES_SMTP_TLS
SMTP UserVariable

User name for the mail server. Empty sends without signing in.

Target
MAILRULES_SMTP_USER
SMTP PasswordVariable

Password for the mail server; an app password where the provider has them.

Target
MAILRULES_SMTP_PASSWORD
SMTP FromVariable

The summary's From address, e.g. MailRules me@example.com. Most servers want one of your own addresses.

Target
MAILRULES_SMTP_FROM
Log LevelVariable

debug, info, warn or error. Empty means info. Logs never contain passwords, keys or email text.

Target
LOG_LEVEL
Redact Addresses in LogVariable

true replaces every email address in the log with a stable tag such as email:3f9a2c1b. Empty keeps addresses (self-hosted default).

Target
LOG_REDACT_ADDRESSES