#mails

• Keyword rules. Instead of running one command for every new message, each message is matched against rules and only matching rules fire. Rules can look at the subject, the decoded text body, the From and the To headers, and can combine keywords with match = "any" or match = "all".
• Encrypted passwords. mails.toml never contains the mailbox password in clear text. It stores an AES-256-GCM envelope; the key lives in .env next to the binary and never in the config file. mails encrypt does the sealing.

#Highlights

• Keyword rules, not just "new mail". Each message is matched against rules that inspect the subject, the decoded text body, From and To. Keywords can be combined with match = "any" or match = "all", compared case-insensitively, or treated as regular expressions. See Configuration.
• IMAP IDLE with a polling fallback. One connection per mailbox. When the server advertises IDLE, changes arrive immediately; when it does not, the client polls every minute. See How watching works.
• Encrypted passwords. mails.toml stores an AES-256-GCM envelope, never the password. The key lives in .env and can be a random 32-byte secret or a PBKDF2-derived passphrase. See Credentials.
• A single static binary. No Node.js, Python or libc version to worry about on Linux: the published binaries are linked against musl statically.
• Config beside the binary. mails.toml and .env are resolved relative to the mails executable, so one directory can be copied to another machine and keep working. There is no global config directory.
• Runs anything. A rule command can be a shell string (sh -c) or an argv array, with {{subject}}-style placeholders and MAILS_* environment variables. See Placeholders.
• Safe defaults. Messages are fetched with BODY.PEEK and never marked as read, commands have a timeout, and mails check verifies the config, the key and every IMAP login before you deploy it.

#Install

#npm, pnpm, yarn or bun

npm install -g @tomasko/mails
# pnpm add -g @tomasko/mails
# yarn global add @tomasko/mails
# bun add -g @tomasko/mails
# npx @tomasko/mails version      (run without installing)

mkdir -p ~/.config/mails
export MAILS_CONFIG=~/.config/mails/mails.toml
mails init

#MoonBit package registry

moon install kupas/mails/cmd/mails

#Install script

curl -LsSf https://raw.githubusercontent.com/tomasky/mails/master/install.sh | bash

#Prebuilt binary

curl -L -o mails \
  https://github.com/tomasky/mails/releases/latest/download/mails-linux-x86_64
chmod +x mails
./mails version

curl -L -O https://github.com/tomasky/mails/releases/latest/download/mails-linux-x86_64
curl -L -O https://github.com/tomasky/mails/releases/latest/download/mails-linux-x86_64.sha256
sha256sum -c mails-linux-x86_64.sha256

#From source

git clone https://github.com/tomasky/mails && cd mails
moon build --target native --release
mkdir -p ~/.local/bin
install -m 755 _build/native/release/build/cmd/mails/mails.exe ~/.local/bin/mails

#Releases

#Quick start

mails init                 # writes mails.toml next to the binary and prints the path
$EDITOR /path/printed/by/mails/init/mails.toml

mails keygen               # creates .env with a fresh MAILS_KEY
mails encrypt --account work --write
# prompts for the IMAP password, seals it, and edits mails.toml in place

mails check                # verify config, key and logins
mails watch                # run in the foreground; use a supervisor in production

#Configuration

[general]
startup_sync = false        # process existing mail on startup
idle_timeout = "29m"        # re-enter IDLE this often
reconnect_delay = "30s"     # first reconnect backoff, doubled up to 5m
max_body_bytes = 262144     # fetch at most this much of each body
command_timeout = "30s"     # default rule timeout
body_chars = 4000           # default {{body}} truncation

env_file = ".env"           # relative to this file
key_env = "MAILS_KEY"       # variable holding the encryption key

[[rules]]
name = "invoice"
keywords = ["invoice", "payment due"]
fields = ["subject", "body"]
match = "any"               # "any" (default) or "all"
case_sensitive = false      # default false
regex = false               # treat keywords as MoonBit regexes
command = 'notify-send "{{subject}}" "{{from}}"'

[[rules]]
name = "from-boss"
keyword = "boss@example.com"
fields = ["from"]
exec = ["/usr/local/bin/on-boss-mail", "--subject", "{{subject}}"]

[accounts.work]
host = "imap.example.com"
port = 993
username = "me@example.com"
password = "enc:v1:..."     # written by `mails encrypt`
mailboxes = ["INBOX", "Work"]
# tls = true
# tls_verify = true
# startup_sync = true
# idle_timeout = "10m"
# reconnect_delay = "1m"
# max_body_bytes = 1048576

#IMAP hosts for common providers

#Providers that require OAuth2

server rejected 'LOGIN "you@outlook.com" <redacted>': NO  Basic authentication is disabled.

• Use a provider that still accepts a password or an app password: Gmail (with 2FA + App Password), iCloud, Fastmail, Yahoo, Zoho, GMX, AOL, or a self-hosted server.
• Put an OAuth bridge in front of it. A local gateway such as DavMail signs in with OAuth2 and exposes a plain IMAP port on localhost; point mails at that port with a dummy password:

  [accounts.outlook]
  host = "127.0.0.1"
  port = 1143
  username = "you@outlook.com"
  password = "unused-bridge-placeholder"   # the bridge holds the OAuth token
  mailboxes = ["INBOX"]
  tls = false              # loopback only; do not expose this port

• Use the built-in OAuth2 support (see below), which needs no browser on the server.

#Headless OAuth2 sign-in

mails login --account outlook

outlook: sign in to microsoft
  1. open https://microsoft.com/devicelogin
  2. enter the code: H7K2-QP4LM
  waiting up to 15 minutes for approval (Ctrl-C to abort)...
  saved the refresh token to /etc/mails/.outlook.oauth
  IMAP login ok

[accounts.outlook]
host = "outlook.office365.com"
port = 993
username = "you@outlook.com"
auth = "xoauth2"
oauth_provider = "microsoft"
oauth_client_id = "<public client id>"
mailboxes = ["INBOX"]

[accounts.gmail]
host = "imap.gmail.com"
port = 993
username = "you@gmail.com"
auth = "xoauth2"
oauth_provider = "google"
oauth_client_id = "<public client id>"
mailboxes = ["INBOX"]

#Outlook / Microsoft 365, step by step

1. Open https://entra.microsoft.com → Applications → App registrations → New registration.
   • Name: mails.
   • Supported account types: pick what matches your mailbox — "Personal Microsoft accounts only" for @outlook.com/@hotmail.com, "Accounts in this organizational directory only" for one company tenant, or "Accounts in any organizational directory and personal Microsoft accounts" for both.
   • Redirect URI: leave empty; the device flow does not need one.
2. In the new app: Authentication → Advanced settings → Allow public client flows = Yes → Save. This is required, otherwise the token endpoint answers AADSTS7000218.
3. API permissions → Add a permission → APIs my organization uses → Office 365 Exchange Online → Delegated permissions → IMAP.AccessAsUser.All → Add permissions. (For a personal-accounts app this API may not be listed; consent is then requested at sign-in.)
4. Copy the Application (client) ID from the app's overview page.
5. Configure the account, matching oauth_tenant to the choice in step 1:

   [accounts.outlook]
   host = "outlook.office365.com"
   port = 993
   username = "you@outlook.com"
   auth = "xoauth2"
   oauth_provider = "microsoft"
   oauth_tenant = "consumers"      # personal accounts; "organizations" or the
                                   # tenant id for work accounts; "common" for both
   oauth_client_id = "00000000-0000-0000-0000-000000000000"
   mailboxes = ["INBOX"]

6. Run mails login --account outlook, open the printed URL on any device and enter the code. After approval the command stores the refresh token and prints IMAP login ok.
7. mails check now passes and mails watch keeps running without a browser.

[accounts.gmail]
host = "imap.gmail.com"
port = 993
username = "you@gmail.com"
password = "enc:v1:..."     # an App Password, sealed with `mails encrypt`
mailboxes = ["INBOX"]
tls = true
tls_verify = true

[accounts.fastmail]
host = "imap.fastmail.com"
port = 993
username = "you@fastmail.com"
password = "enc:v1:..."
mailboxes = ["INBOX", "Sent"]
tls = true
tls_verify = true

#Rule keys

#Placeholders

#Message text is untrusted input

# Shell-quoted placeholder: safe whatever the sender wrote.
command = 'printf "%s\n" {{body_q}} >> ~/mail.log'

# Or the environment, which a shell never parses.
command = 'printf "%s\n" "$MAILS_BODY" >> ~/mail.log'

body=$(printf '%s\n' "$MAILS_BODY" | awk 'NF { printf "%s\\n\\n", $0 }')
curl -s -H 'Content-Type: application/json' \
  -d "{\"msgtype\":\"markdown\",\"markdown\":{\"title\":\"$MAILS_SUBJECT\",\"text\":\"$body\"}}" \
  "$DINGTALK_WEBHOOK"

#Credentials

mails keygen                        # writes MAILS_KEY to .env (mode 0600)
mails encrypt --account work        # prints the envelope to paste
mails encrypt --account work --write  # edits mails.toml in place
mails encrypt --account work --new-key --write  # rotate the key first

• MAILS_KEY=b64:... — a random 32-byte key (what keygen writes), used directly.
• MAILS_KEY=pass:correct horse battery staple — a passphrase; the AES key is derived with PBKDF2-HMAC-SHA256 (100k iterations) and the per-secret salt.

#Commands

mails <command> [options]

watch       follow mailboxes with IMAP IDLE
sync        process existing matching mail once, then exit
check       verify config, key, logins and mailbox counts
encrypt     seal an account password with the key in .env
keygen      create or rotate the encryption key in .env
rules       list configured rules
env         show .env with secret values masked
init        write a commented mails.toml next to the binary
version     print the version
help        print usage

#Environment variables

#Exit status

#How watching works

1. Enter IDLE with idle_timeout. The server pushes EXISTS/RECENT when something changes; on timeout the client sends DONE and re-enters IDLE.
2. On a change, re-SELECT the mailbox to refresh UIDVALIDITY and UIDNEXT.
3. UID SEARCH UID <last+1>:*, then UID FETCH each new UID for its header and a bounded slice of its text body.
4. Parse MIME, run every matching rule's command, and advance last_uid, which is also written to .<account>.<mailbox>.<digest>.cursor next to mails.toml, after every message. The digest keeps mailboxes whose names differ only in characters that are unsafe in a file name (Sent Items versus Sent/Items) from sharing one cursor.

#Running as a service

# ~/.config/systemd/user/mails.service
[Unit]
Description=mails IMAP watcher
After=network-online.target

[Service]
ExecStart=%h/.local/bin/mails watch --config %h/.local/bin/mails.toml
Restart=always
RestartSec=30

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable --now mails
journalctl --user -u mails -f

#Building

moon build --target native --release
# binary: _build/native/release/build/cmd/mails/mails.exe

moon build --target native
./_build/native/debug/build/cmd/mails/mails.exe version

moon test --target native
moon check --target native --deny-warn
moon fmt --check

#Static Linux build

sudo apt-get install musl-tools
./scripts/build-linux-static.sh dist/mails-linux-x86_64

#Differences from goimapnotify

• Config is TOML, lives next to the binary, and is not searched for in $XDG_CONFIG_HOME.
• Desktop notifications are not built in; a rule command can call notify-send, terminal-notifier, or anything else.
• Passwords are encrypted at rest; goimapnotify stores them in clear text.
• Matching is keyword-based with subject/body/from/to fields, not just "run a command for every new message".
• IMAP only. JMAP is not implemented.

#Limitations

• IMAP only. JMAP and POP3 are not implemented. Authentication is LOGIN or AUTHENTICATE XOAUTH2 (both with TLS); see Providers that require OAuth2.
• OAuth2 needs a one-time mails login. The device code flow refreshes the access token automatically afterwards, but a revoked or expired refresh token has to be replaced by running mails login again.
• The cursor is a file next to the config. .<account>.<mailbox>.cursor (mode 0600) records the last handled UID, so a dropped connection resumes instead of replaying mail. It is per account and per mailbox. A fresh mails process still follows startup_sync, so mail that arrived while it was down is skipped when that is false; run mails sync to handle it.
• Text charsets. UTF-8 plus everything the WHATWG Encoding Standard knows about: GBK/GB2312/GB18030, Big5, Shift_JIS, EUC-JP/KR, ISO-2022-JP and the ISO-8859/windows-125x single-byte families, so Chinese mail from QQ, 163 and Exmail matches and renders correctly. A text/html part with no charset parameter inherits the one its <meta> tag declares. Unknown charsets still fall back to a lossy UTF-8 read.
• One connection per mailbox, and rule commands for a mailbox run sequentially. A slow command delays processing of later messages on that mailbox; use timeout to bound it.
• Message text is untrusted. {{subject}}, {{from}} and {{body}} are substituted raw into sh -c, so use {{..._q}} or the MAILS_* environment; both mails check and mails watch warn about rules that do not.
• A single environment value stops at 128 KiB. MAILS_BODY_FULL is capped at 60 000 bytes (and sets MAILS_BODY_TRUNCATED=1), because Linux refuses a larger execve environment. Write the message to a file when you need every byte.
• Plain passwords are still accepted for compatibility with password helpers, but they are not encrypted at rest. Prefer mails encrypt.
• No desktop notification backend. Call notify-send, terminal-notifier, logger or your own script from a rule.

#License