For MailRules v0.3.0View this page on GitHub
Settings reference
Every MailRules setting, as an environment variable and as a command-line flag, with its default.
Every setting is an environment variable, and also a flag of mailrules serve: the flag wins when both are set. The flag is the variable’s name in lower case, without MAILRULES_, with - for _. Give keys and passwords as environment variables, not flags: other users of the machine can see a program’s flags in the process list.
The decision models, their thresholds and the provider keys can also be set in the browser, under Settings. What is saved there wins over the environment; see Decision models and keys. Dry-run works the same way: see Dry-run and going live.
Where to put the variables depends on how you run MailRules; see Install. This page is generated from the daemon’s source, so it matches the release it comes with.
Daemon
| Variable |
Flag |
Default |
What it does |
MAILRULES_DATA_DIR |
--data-dir |
./data |
Directory for the database (mailrules.db) and the generated master.key. A relative path is relative to the directory MailRules starts in. |
MAILRULES_LISTEN |
--listen |
127.0.0.1:8080 |
Address (host:port) the web UI and API listen on. Any address other than a loopback one makes MailRules log a warning: put a reverse proxy with TLS in front. |
MAILRULES_MODE |
--mode |
selfhost |
selfhost or cloud. cloud is for the hosted service: it needs a build with a sign-in module (MailRules does not start without one), treats provider keys from the environment as the operator’s (used for a team with no key of its own, never shown to it, and its usage marked as the operator’s), connects only to mail servers on the public internet for the mailboxes people add (see Security), and hides the Self-hosting card in Settings. Leave it as selfhost. |
MAILRULES_MASTER_KEY |
--master-key |
none |
The master key itself: 32 bytes, base64-encoded. It encrypts the stored mailbox passwords and provider keys. Set this or MAILRULES_MASTER_KEY_FILE, not both; with neither, master.key in the data directory is used, and generated on first run. It is never generated while the database holds passwords or keys sealed under an earlier key; see MAILRULES_NEW_MASTER_KEY. |
MAILRULES_MASTER_KEY_FILE |
--master-key-file |
none |
A file holding the master key, to keep it outside the data directory. MailRules does not start if the file is missing. |
MAILRULES_NEW_MASTER_KEY |
--new-master-key |
false |
Start even though the master key is missing or cannot open any stored mailbox password or model key. Without it MailRules stops with a message instead. A missing master.key is then generated, and the stored passwords and keys stay unreadable until you enter them again. In a build whose module keeps the keys in a key service (the hosted service), it lets MailRules start without the master key while some stored keys still need it; those stay unreadable. Set it for one start only. |
MAILRULES_TENANT_KEY_CACHE |
--tenant-key-cache |
1h0m0s |
How long a team’s data key, which opens its stored passwords and keys, stays in memory once unwrapped, such as 1h or 15m; then it is unwrapped again. It matters in a build whose module keeps the keys in a key service (the hosted service): while that service cannot be reached, a team whose key has run out of time can use none of its stored passwords and keys, and its mailboxes wait in Key service unreachable until it answers. |
MAILRULES_DRY_RUN |
--dry-run |
true |
Dry-run until it is first switched: decisions are recorded and no mailbox is changed. Once dry-run has been switched in the browser or with mailrules dry-run on|off, that choice wins. |
LOG_LEVEL |
--log-level |
info |
debug, info, warn or error. Logs are JSON lines on standard error and never hold passwords, keys or the text of an email. |
LOG_REDACT_ADDRESSES |
--log-redact-addresses |
auto |
Replace every email address in the log, and in the errors handed to a module, with a tag such as <email:3f9a2c1b>: auto (yes when MAILRULES_MODE is cloud, no when it is selfhost), true or false. The same address always gets the same tag, keyed by log.key in the data directory (generated on first use; it opens nothing else). mailrules log-tag <address> prints an address’s tag, to find its lines. |
Database (hosted build)
| Variable |
Flag |
Default |
What it does |
MAILRULES_DATABASE_URL |
--database-url |
none |
For the hosted service only; self-hosting leaves it empty and keeps the database in the data directory. A Postgres URL (postgres://user:password@host:5432/mailrules?sslmode=require, Postgres 16 or later) for the web app and the daemon, signed in as a member of the mailrules_app role, which owns no table: row-level security keeps each team’s rows to that team. MailRules never migrates through it: run mailrules migrate first (see MAILRULES_MIGRATE_DATABASE_URL), and it does not start while the database’s schema is not the one it was built for. |
MAILRULES_WORKER_DATABASE_URL |
--worker-database-url |
none |
Hosted service only: a Postgres URL signed in as a member of mailrules_worker, for the mailbox workers and the jobs that hand work to modules. That role reads no password hash and no session. Empty uses MAILRULES_DATABASE_URL. |
MAILRULES_MIGRATE_DATABASE_URL |
--migrate-database-url |
none |
Hosted service only: a Postgres URL signed in as the role that owns the tables (it needs CREATEROLE the first time, to create the group roles). Only mailrules migrate reads it, so the owner’s password never reaches a running daemon: set it for that one command. |
Decision models
| Variable |
Flag |
Default |
What it does |
MAILRULES_DECIDER |
--decider |
jev |
The decision model, which picks the rule an email matches: jev, clef, anthropic, openai or ollama. |
MAILRULES_DECIDER_MODEL |
--decider-model |
none |
The decision model’s model name. Empty uses the provider’s default; openai and ollama have none, so they need one. |
MAILRULES_FALLBACK_MODEL |
--fallback-model |
claude-haiku-4-5 |
The Claude model asked for a second opinion when the decision model is unsure. It needs ANTHROPIC_API_KEY. Empty turns the fallback off. |
MAILRULES_COMPOSER_MODEL |
--composer-model |
claude-haiku-4-5 |
The model that writes rules from your words: a Claude model, or openai:<model> or ollama:<model>. |
MAILRULES_ESCALATE_BELOW |
--escalate-below |
0.75 |
When the decision model’s confidence is below this (0 to 1), the fallback model is asked too. |
MAILRULES_MIN_CONFIDENCE |
--min-confidence |
0.75 |
The confidence (0 to 1) a decision needs before a rule acts, unless the rule sets its own. Below it, the email waits in Needs review. |
MAILRULES_BODY_CHARS |
--body-chars |
2000 |
How many characters of an email’s plain text are sent to a model. |
MAILRULES_MODEL_CONCURRENCY |
--model-concurrency |
8 |
How many model calls may be in flight at once. |
MAILRULES_PRICES_FILE |
--prices-file |
none |
A JSON file of per-model prices, in USD per million tokens, laid over the built-in table the cost estimate uses. |
Provider keys
| Variable |
Flag |
Default |
What it does |
OPENROUTER_API_KEY |
--openrouter-api-key |
none |
OpenRouter API key, for Jev. |
CLOUDFLARE_ACCOUNT_ID |
--cloudflare-account-id |
none |
Cloudflare account ID, for Clef. |
CLOUDFLARE_API_TOKEN |
--cloudflare-api-token |
none |
Cloudflare API token, for Clef. |
ANTHROPIC_API_KEY |
--anthropic-api-key |
none |
Anthropic API key, for the fallback model, for the rule composer when its model is Claude, and for the anthropic decision model. |
ANTHROPIC_WORKSPACE_ID |
--anthropic-workspace-id |
none |
The Claude workspace (wrkspc_…) requests run in. Only a key that covers a whole organisation needs it. |
OPENAI_BASE_URL |
--openai-base-url |
none |
Base URL of an OpenAI-compatible endpoint. Empty means OpenAI itself. |
OPENAI_API_KEY |
--openai-api-key |
none |
API key for the OpenAI-compatible endpoint. |
OLLAMA_URL |
--ollama-url |
none |
URL of an Ollama server, such as http://localhost:11434. |
Web UI
| Variable |
Flag |
Default |
What it does |
MAILRULES_COOKIE_SECURE |
--cookie-secure |
auto |
Send the login cookie over HTTPS only: auto (yes unless MailRules listens on loopback only), true or false. Set true behind a TLS proxy; false only when the UI is opened over plain HTTP on this machine, as with Docker. |
MAILRULES_TRUSTED_PROXIES |
--trusted-proxies |
none |
Reverse proxies whose X-Forwarded-For header MailRules believes, as IP addresses or CIDR ranges separated by commas, such as 127.0.0.1,172.18.0.0/16. Sign-in limits then count the real visitor instead of the proxy. Empty trusts no one, which is right when nothing sits in front of MailRules; never list a range that visitors can reach directly. |
MAILRULES_PUBLIC_URL |
--public-url |
http://127.0.0.1:8080 |
Where you open MailRules; links in the summary email start with it. Set it to your proxy’s address, such as https://mailrules.example.com. |
Summary email
| Variable |
Flag |
Default |
What it does |
MAILRULES_SMTP_HOST |
--smtp-host |
none |
Outgoing mail server the summary email is sent through, such as smtp.example.com, without a scheme or port. A build that sells plans (the hosted service) also sends through it the warnings before a plan’s data is deleted, and does not start without it. |
MAILRULES_SMTP_PORT |
--smtp-port |
0 |
Its port. 0 uses the usual one: 587 for starttls, 465 for implicit, 25 for none. |
MAILRULES_SMTP_USER |
--smtp-user |
none |
User name to sign in to the mail server with. Empty sends without signing in. |
MAILRULES_SMTP_PASSWORD |
--smtp-password |
none |
Its password; an app password where the provider has them. |
MAILRULES_SMTP_PASSWORD_FILE |
--smtp-password-file |
none |
A file holding that password, instead of MAILRULES_SMTP_PASSWORD. |
MAILRULES_SMTP_FROM |
--smtp-from |
none |
The summary’s From address, such as MailRules <[email protected]>. Most servers want one of your own addresses. |
MAILRULES_SMTP_TLS |
--smtp-tls |
starttls |
starttls (the server must offer it), implicit (TLS from the start), or none, which is allowed only for a mail server on this machine. |
OpenTelemetry export
| Variable |
Flag |
Default |
What it does |
OTEL_EXPORTER_OTLP_ENDPOINT |
--otel-exporter-otlp-endpoint |
none |
Base URL of an OpenTelemetry (OTLP/HTTP) receiver, such as https://otel.example.com or http://localhost:4318. Set, MailRules sends it the metrics /metrics serves, Go runtime included, to /v1/metrics every minute (OTEL_METRIC_EXPORT_INTERVAL, in milliseconds, changes that), and every line of its log, redacted as the log is, to /v1/logs. Empty sends nothing and starts nothing. A receiver that is slow or down never holds up MailRules: log lines that cannot be sent are dropped and counted in mailrules_otel_log_records_dropped_total. |
OTEL_EXPORTER_OTLP_HEADERS |
--otel-exporter-otlp-headers |
none |
Headers sent with every export, as key=value pairs separated by commas, such as X-Obs-Key=<token>; values may be percent-encoded. Never logged. |
OTEL_EXPORTER_OTLP_PROTOCOL |
--otel-exporter-otlp-protocol |
http/protobuf |
How to send: only http/protobuf is supported. |
OTEL_SERVICE_NAME |
--otel-service-name |
mailrules |
The service.name the metrics and log lines are sent under. |
MAILRULES_ENVIRONMENT |
--environment |
none |
The deployment’s name, such as staging or production, sent as deployment.environment.name with the metrics and log lines. Empty sends none. |