#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"]

[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

command = 'logger -t mails "$MAILS_SUBJECT"'

#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.

#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.
• No persistent cursor. The last seen UID lives in memory. After a restart with startup_sync = false, mail that arrived while mails was down is skipped; run mails sync (or set startup_sync = true) if you need it.
• Text charsets. UTF-8, US-ASCII and ISO-8859-1 are decoded. Other charsets fall back to a lossy UTF-8 interpretation, so keywords in, for example, GBK mail may not match.
• 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.
• 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