mox

README

Mox is a modern full-featured open source secure mail server for low-maintenance self-hosted email.

For more details, see the mox website, https://www.xmox.nl.

See Quickstart below to get started.

Features

• Quick and easy to start/maintain mail server, for your own domain(s).
• SMTP (with extensions) for receiving, submitting and delivering email.
• IMAP4 (with extensions) for giving email clients access to email.
• Webmail for reading/sending email from the browser.
• SPF/DKIM/DMARC for authenticating messages/delivery, also DMARC aggregate reports.
• Reputation tracking, learning (per user) host-, domain- and sender address-based reputation from (Non-)Junk email classification.
• Bayesian spam filtering that learns (per user) from (Non-)Junk email.
• Slowing down senders with no/low reputation or questionable email content (similar to greylisting). Rejected emails are stored in a mailbox called Rejects for a short period, helping with misclassified legitimate synchronous signup/login/transactional emails.
• Internationalized email, with unicode in email address usernames ("localparts"), and in domain names (IDNA).
• Automatic TLS with ACME, for use with Let's Encrypt and other CA's.
• DANE and MTA-STS for inbound and outbound delivery over SMTP with STARTTLS, including REQUIRETLS and with incoming/outgoing TLSRPT reporting.
• Web admin interface that helps you set up your domains and accounts (instructions to create DNS records, configure SPF/DKIM/DMARC/TLSRPT/MTA-STS), for status information, managing accounts/domains, and modifying the configuration file.
• Account autodiscovery (with SRV records, Microsoft-style, Thunderbird-style, and Apple device management profiles) for easy account setup (though client support is limited).
• Webserver with serving static files and forwarding requests (reverse proxy), so port 443 can also be used to serve websites.
• Prometheus metrics and structured logging for operational insight.
• "mox localserve" subcommand for running mox locally for email-related testing/developing, including pedantic mode.
• Most non-server Go packages mox consists of are written to be reusable.

Mox is available under the MIT-license and was created by Mechiel Lukkien, mechiel@ueber.net. Mox includes BSD-3-claused code from the Go Authors, and the Public Suffix List by Mozilla under Mozilla Public License, v2.0.

Mox has automated tests, including for interoperability with Postfix for SMTP. Mox is manually tested with email clients: Mozilla Thunderbird, mutt, iOS Mail, macOS Mail, Android Mail, Microsoft Outlook. Mox is also manually tested to interoperate with popular cloud providers: gmail.com, outlook.com, yahoo.com, proton.me.

The code is heavily cross-referenced with the RFCs for readability/maintainability.

Quickstart

The easiest way to get started with serving email for your domain is to get a (virtual) machine dedicated to serving email, name it [host].[domain] (e.g. mail.example.com). Having a DNSSEC-verifying resolver installed, such as unbound, is highly recommended. Run as root:

# Create mox user and homedir (or pick another name or homedir):
useradd -m -d /home/mox mox

cd /home/mox
... compile or download mox to this directory, see below ...

# Generate config files for your address/domain:
./mox quickstart you@example.com

The quickstart:

• Creates configuration files mox.conf and domains.conf.
• Adds the domain and an account for the email address to domains.conf
• Generates an admin and account password.
• Prints the DNS records you need to add, for the machine and domain.
• Prints commands to start mox, and optionally install mox as a service.

A machine that doesn't already run a webserver is highly recommended because modern email requires HTTPS, and mox currently needs to run a webserver for automatic TLS with ACME. You could combine mox with an existing webserver, but it requires a lot more configuration. If you want to serve websites on the same machine, consider using the webserver built into mox. It's pretty good! If you want to run an existing webserver on port 443/80, see mox help quickstart.

After starting, you can access the admin web interface on internal IPs.

Download

Download a mox binary from https://beta.gobuilds.org/github.com/mjl-/mox@latest/linux-amd64-latest/.

Symlink or rename it to "mox".

The URL above always resolves to the latest release for linux/amd64 built with the latest Go toolchain. See the links at the bottom of that page for binaries for other platforms.

Compiling

You can easily (cross) compile mox yourself. You need a recent Go toolchain installed. Run go version, it must be >= 1.20. Download the latest version from https://go.dev/dl/ or see https://go.dev/doc/manage-install.

To download the source code of the latest release, and compile it to binary "mox":

GOBIN=$PWD CGO_ENABLED=0 go install github.com/mjl-/mox@latest

Mox only compiles for and fully works on unix systems. Mox also compiles for Windows, but "mox serve" does not yet work, though "mox localserve" (for a local test instance) and most other subcommands do. Mox does not compile for Plan 9.

Docker

Although not recommended, you can also run mox with docker image r.xmox.nl/mox, with tags like v0.0.1 and v0.0.1-go1.20.1-alpine3.17.2, see https://r.xmox.nl/r/mox/. See https://github.com/mjl-/mox/blob/main/docker-compose.yml to get started.

New docker images aren't (automatically) generated for new Go runtime/compile releases.

It is important to run with docker host networking, so mox can use the public IPs and has correct remote IP information for incoming connections (important for junk filtering and rate-limiting).

Future/development

Mox will receive funding for essentially full-time continued work from August 2023 to August 2024 through NLnet/EU's NGI0 Entrust, see https://nlnet.nl/project/Mox/.

Roadmap

• Webmail improvements
• HTTP-based API for sending messages and receiving delivery feedback
• Calendaring with CalDAV/iCal
• More IMAP extensions (PREVIEW, WITHIN, IMPORTANT, COMPRESS=DEFLATE, CREATE-SPECIAL-USE, SAVEDATE, UNAUTHENTICATE, REPLACE, QUOTA, NOTIFY, MULTIAPPEND, OBJECTID, MULTISEARCH, THREAD, SORT)
• ARC, with forwarded email from trusted source
• Forwarding (to an external address)
• Add special IMAP mailbox ("Queue?") that contains queued but undelivered messages, updated with IMAP flags/keywords/tags and message headers.
• Sieve for filtering (for now see Rulesets in the account config)
• Autoresponder (out of office/vacation)
• OAUTH2 support, for single sign on
• Privilege separation, isolating parts of the application to more restricted sandbox (e.g. new unauthenticated connections)
• Using mox as backup MX
• JMAP
• Milter support, for integration with external tools
• IMAP extensions for "online"/non-syncing/webmail clients (SORT (including DISPLAYFROM, DISPLAYTO), THREAD, PARTIAL, CONTEXT=SEARCH CONTEXT=SORT ESORT, FILTERS)
• IMAP Sieve extension, to run Sieve scripts after message changes (not only new deliveries)
• Improve support for mobile clients with extensions: IMAP URLAUTH, SMTP CHUNKING and BINARYMIME, IMAP CATENATE
• Mailing list manager

There are many smaller improvements to make as well, search for "todo" in the code.

Not supported/planned

There is currently no plan to implement the following. Though this may change in the future.

• Functioning as SMTP relay
• POP3
• Delivery to (unix) OS system users
• Support for pluggable delivery mechanisms
• iOS Mail push notifications (with XAPPLEPUSHSERVICE undocumented imap extension and hard to get APNS certificate)

FAQ - Frequently Asked Questions

Why a new mail server implementation?

Mox aims to make "running a mail server" easy and nearly effortless. Excellent quality (open source) mail server software exists, but getting a working setup typically requires you configure half a dozen services (SMTP, IMAP, SPF/DKIM/DMARC, spam filtering), which are often written in C (where small bugs often have large consequences). That seems to lead to people no longer running their own mail servers, instead switching to one of the few centralized email providers. Email with SMTP is a long-time decentralized messaging protocol. To keep it decentralized, people need to run their own mail server. Mox aims to make that easy.

Where is the documentation?

To keep mox as a project maintainable, documentation is integrated into, and generated from the code.

A list of mox commands, and their help output, are at https://www.xmox.nl/commands/.

Mox is configured through configuration files, and each field comes with documentation. See https://www.xmox.nl/config/ for config files containing all fields and their documentation.

You can get the same information by running "mox" without arguments to list its subcommands and usage, and "mox help [subcommand]" for more details.

The example config files are printed by "mox config describe-static" and "mox config describe-dynamic".

If you're missing some documentation, please create an issue describing what is unclear or confusing, and we'll try to improve the documentation.

Is Mox affected by SMTP smuggling?

Mox itself is not affected: it only treats "\r\n.\r\n" as SMTP end-of-message. But read on for caveats.

SMTP smuggling exploits differences in handling by SMTP servers of: carriage returns (CR, or "\r"), newlines (line feeds, LF, "\n") in the context of "dot stuffing". SMTP is a text-based protocol. An SMTP transaction to send a message is finalized with a "\r\n.\r\n" sequence. This sequence could occur in the message being transferred, so any verbatim "." at the start of a line in a message is "escaped" with another dot ("dot stuffing"), to not trigger the SMTP end-of-message. SMTP smuggling takes advantage of bugs in some mail servers that interpret other sequences than "\r\n.\r\n" as SMTP end-of-message. For example "\n.\n" or even "\r.\r", and perhaps even other magic character combinations.

Before v0.0.9, mox accepted SMTP transactions with bare carriage returns (without newline) for compatibility with real-world email messages, considering them meaningless and therefore innocuous.

Since v0.0.9, SMTP transactions with bare carriage returns are rejected. Sending messages with bare carriage returns to buggy mail servers can cause those mail servers to materialize non-existent messages. Now that mox rejects messages with bare carriage returns, sending a message through mox can no longer be used to trigger those bugs.

Mox can still handle bare carriage returns in email messages, e.g. those imported from mbox files or Maildirs, or from messages added over IMAP. Mox still fixes up messages with bare newlines by adding the missing carriage returns.

Before v0.0.9, an SMTP transaction for a message containing "\n.\n" would result in a non-specific error message, and "\r\n.\n" would result in the dot being dropped. Since v0.0.9, these sequences are rejected with a message mentioning SMTP smuggling.

How do I import/export email?

Use the import functionality on the accounts web page to import a zip/tgz with maildirs/mbox files, or use the "mox import maildir" or "mox import mbox" subcommands. You could also use your IMAP email client, add your mox account, and copy or move messages from one account to the other.

Similarly, see the export functionality on the accounts web page and the "mox export maildir" and "mox export mbox" subcommands to export email.

Importing large mailboxes may require a lot of memory (a limitation of the current database). Splitting up mailboxes in smaller parts (e.g. 100k messages) would help.

How can I help?

Mox needs users and testing in real-life setups! So just give it a try, send and receive emails through it with your favourite email clients, and file an issue if you encounter a problem or would like to see a feature/functionality implemented.

Instead of switching email for your domain over to mox, you could simply configure mox for a subdomain, e.g. [you]@moxtest.[yourdomain].

If you have experience with how the email protocols are used in the wild, e.g. compatibility issues, limitations, anti-spam measures, specification violations, that would be interesting to hear about.

Pull requests for bug fixes and new code are welcome too. If the changes are large, it helps to start a discussion (create an "issue") before doing all the work. In practice, starting with a small contribution and growing from there has the highest chance of success.

By contributing (e.g. code), you agree your contributions are licensed under the MIT license (like mox), and have the rights to do so.

Where can I discuss mox?

Join #mox on irc.oftc.net, or #mox:matrix.org, or #mox on the "Gopher slack".

For bug reports, please file an issue at https://github.com/mjl-/mox/issues/new.

How do I change my password?

Regular users (doing IMAP/SMTP with authentication) can change their password at the account page, e.g. http://localhost/. Or you can set a password with "mox setaccountpassword".

The admin can change the password of any account through the admin page, at http://localhost/admin/ by default (leave username empty when logging in).

The account and admin pages are served on localhost for configs created with the quickstart. To access these from your browser, run ssh -L 8080:localhost:80 you@yourmachine locally and open http://localhost:8080/[...].

The admin password can be changed with "mox setadminpassword".

How do I configure a second mox instance as a backup MX?

Unfortunately, mox does not yet provide an option for that. Mox does spam filtering based on reputation of received messages. It will take a good amount of work to share that information with a backup MX. Without that information, spammers could use a backup MX to get their spam accepted.

Until mox has a proper solution, you can simply run a single SMTP server. The author has run a single mail server for over a decade without issues. Machines and network connectivity are stable nowadays, and email delivery will be retried for many hours during temporary errors (e.g. when rebooting a machine after updates).

How do I stay up to date?

Please set "CheckUpdates: true" in mox.conf. Mox will check for a new version through a DNS TXT request for _updates.xmox.nl once per 24h. Only if a new version is published will the changelog be fetched and delivered to the postmaster mailbox.

The changelog, including latest update instructions, is at https://updates.xmox.nl/changelog.

You can also monitor newly added releases on this repository with the github "watch" feature, or use the github RSS feed for tags (https://github.com/mjl-/mox/tags.atom) or releases (https://github.com/mjl-/mox/releases.atom), or monitor the docker images.

Keep in mind you have a responsibility to keep the internet-connected software you run up to date and secure.

How do I upgrade my mox installation?

We try to make upgrades effortless and you can typically just put a new binary in place and restart. If manual actions are required, the release notes mention them. Check the release notes of all version between your current installation and the release you're upgrading to.

Before upgrading, make a backup of the data directory with mox backup <destdir>. This writes consistent snapshots of the database files, and duplicates message files from the outgoing queue and accounts. Using the new mox binary, run mox verifydata <backupdir> (do NOT use the "live" data directory!) for a dry run. If this fails, an upgrade will probably fail too. Important: verifydata with the new mox binary can modify the database files (due to automatic schema upgrades). So make a fresh backup again before the actual upgrade. See the help output of the "backup" and "verifydata" commands for more details.

During backup, message files are hardlinked if possible, and copied otherwise. Using a destination directory like data/tmp/backup increases the odds hardlinking succeeds: the default mox systemd service file mounts the data directory separately, so hardlinks to outside the data directory are cross-device and will fail.

If an upgrade fails and you have to restore (parts) of the data directory, you should run mox verifydata <datadir> (with the original binary) on the restored directory before starting mox again. If problematic files are found, for example queue or account message files that are not in the database, run mox verifydata -fix <datadir> to move away those files. After a restore, you may also want to run mox bumpuidvalidity <account> for each account for which messages in a mailbox changed, to force IMAP clients to synchronize mailbox state.

How secure is mox?

Security is high on the priority list for mox. Mox is young, so don't expect no bugs at all. Mox does have automated tests for some security aspects, e.g. for login, and uses fuzzing. Mox is written in Go, so some classes of bugs such as buffer mishandling do not typically result in privilege escalation. Of course logic bugs will still exist. If you find any security issues, please email them to mechiel@ueber.net.

I'm now running an email server, but how does email work?

Congrats and welcome to the club! Running an email server on the internet comes with some responsibilities so you should understand how it works. See https://explained-from-first-principles.com/email/ for a thorough explanation.

What are the minimum requirements to run mox?

Mox does not need much. Nowadays most machines are larger than mox needs. You can start with a machine with 512MB RAM, any CPU will do. For storage you should account for the size of the email messages (no compression currently), an additional 15% overhead for the meta data, and add some more headroom. Expand as necessary.

Won't the big email providers block my email?

It is a common misconception that it is impossible to run your own email server nowadays. The claim is that the handful big email providers will simply block your email. However, you can run your own email server just fine, and your email will be accepted, provided you are doing it right.

If your email is rejected, it is often because your IP address has a bad email sending reputation. Email servers often use IP blocklists to reject email networks with a bad email sending reputation. These blocklists often work at the level of whole network ranges. So if you try to run an email server from a hosting provider with a bad reputation (which happens if they don't monitor their network or don't act on abuse/spam reports), your IP too will have a bad reputation and other mail servers (both large and small) may reject messages coming from you. During the quickstart, mox checks if your IPs are on a few often-used blocklists. It's typically not a good idea to host an email server on the cheapest or largest cloud providers: They often don't spend the resources necessary for a good reputation, or they simply block all outgoing SMTP traffic. It's better to look for a technically-focused local provider. They too may initially block outgoing SMTP connections on new machines to prevent spam from their networks. But they will either automatically open up outgoing SMTP traffic after a cool down period (e.g. 24 hours), or after you've contacted their support.

After you get past the IP blocklist checks, email servers use many more signals to determine if your email message could be spam and should be rejected. Mox helps you set up a system that doesn't trigger most of the technical signals (e.g. with SPF/DKIM/DMARC). But there are more signals, for example: Sending to a mail server or address for the first time. Sending from a newly registered domain (especially if you're sending automated messages, and if you send more messages after previous messages were rejected), domains that existed for a few weeks to a month are treated more friendly. Sending messages with content that resembles known spam messages.

Should your email be rejected, you will typically get an error message during the SMTP transaction that explains why. In the case of big email providers the error message often has instructions on how to prove to them you are a legitimate sender.

Can I use existing TLS certificates/keys?

Yes. The quickstart command creates a config that uses ACME with Let's Encrypt, but you can change the config file to use existing certificate and key files.

You'll see "ACME: letsencrypt" in the "TLS" section of the "public" Listener. Remove or comment out the ACME-line, and add a "KeyCerts" section, see https://www.xmox.nl/config/#cfg-mox-conf-Listeners-x-TLS-KeyCerts

You can have multiple certificates and keys: The line with the "-" (dash) is the start of a list item. Duplicate that line up to and including the line with KeyFile for each certificate/key you have. Mox makes a TLS config that holds all specified certificates/keys, and uses it for all services for that Listener (including a webserver), choosing the correct certificate for incoming requests.

Keep in mind that for each email domain you host, you will need a certificate for mta-sts.<domain>, autoconfig.<domain> and mail.<domain>, unless you disable MTA-STS, autoconfig and the client-settings-domain for that domain.

Mox opens the key and certificate files during initial startup, as root (and passes file descriptors to the unprivileged process). No special permissions are needed on the key and certificate files.

Can I directly access mailboxes through the file system?

No, mox only provides access to email through protocols like IMAP.

While it can be convenient for users/email clients to access email through conventions like Maildir, providing such access puts quite a burden on the server: The server has to continuously watch for changes made to the mail store by external programs, and sync its internal state. By only providing access to emails through mox, the storage/state management is simpler and easier to implement reliably.

Not providing direct file system access also allows future improvements in the storage mechanism. Such as encryption of all stored messages. Programs won't be able to access such messages directly.

Mox stores metadata about delivered messages in its per-account message index database, more than fits in a simple (filename-based) format like Maildir. The IP address of the remote SMTP server during delivery, SPF/DKIM/DMARC domains and validation status, and more...

For efficiency, mox doesn't prepend message headers generated during delivery (e.g. Authentication-Results) to the on-disk message file, but only stores it in the database. This prevents a rewrite of the entire message file. When reading a message, mox combines the prepended headers from the database with the message file.

Mox user accounts have no relation to operating system user accounts. Multiple system users reading their email on a single machine is not very common anymore. All data (for all accounts) stored by mox is accessible only by the mox process. Messages are currently stored as individual files in standard Internet Message Format (IMF), at data/accounts/<account>/msg/<dir>/<msgid>: msgid is a consecutive unique integer id assigned by the per-account message index database; dir groups 8k consecutive message ids into a directory, ensuring they don't become too large. The message index database file for an account is at data/accounts/<account>/index.db, accessed with the bstore database library, which uses bbolt (formerly BoltDB) for storage, a transactional key/value library/file format inspired by LMDB.

Documentation

Overview

Command mox is a modern, secure, full-featured, open source mail server for low-maintenance self-hosted email.

Mox is started with the "serve" subcommand, but mox also has many other subcommands.

Many of those commands talk to a running mox instance, through the ctl file in the data directory. Specify the configuration file (that holds the path to the data directory) through the -config flag or MOXCONF environment variable.

Commands that don't talk to a running mox instance are often for testing/debugging email functionality. For example for parsing an email message, or looking up SPF/DKIM/DMARC records.

Below is the usage information as printed by the command when started without any parameters. Followed by the help and usage information for each command.

Usage

mox [-config config/mox.conf] [-pedantic] ...
mox serve
mox quickstart [-existing-webserver] [-hostname host] user@domain [user | uid]
mox stop
mox setaccountpassword account
mox setadminpassword
mox loglevels [level [pkg]]
mox queue list
mox queue kick [-id id] [-todomain domain] [-recipient address] [-transport transport]
mox queue drop [-id id] [-todomain domain] [-recipient address]
mox queue dump id
mox import maildir accountname mailboxname maildir
mox import mbox accountname mailboxname mbox
mox export maildir dst-dir account-path [mailbox]
mox export mbox dst-dir account-path [mailbox]
mox localserve
mox help [command ...]
mox backup dest-dir
mox verifydata data-dir
mox config test
mox config dnscheck domain
mox config dnsrecords domain
mox config describe-domains >domains.conf
mox config describe-static >mox.conf
mox config account add account address
mox config account rm account
mox config address add address account
mox config address rm address
mox config domain add domain account [localpart]
mox config domain rm domain
mox config describe-sendmail >/etc/moxsubmit.conf
mox config printservice >mox.service
mox config ensureacmehostprivatekeys
mox example [name]
mox checkupdate
mox cid cid
mox clientconfig domain
mox dane dial host:port
mox dane dialmx domain [destination-host]
mox dane makerecord usage selector matchtype [certificate.pem | publickey.pem | privatekey.pem]
mox dns lookup [ptr | mx | cname | ips | a | aaaa | ns | txt | srv | tlsa] name
mox dkim gened25519 >$selector._domainkey.$domain.ed25519.privatekey.pkcs8.pem
mox dkim genrsa >$selector._domainkey.$domain.rsa2048.privatekey.pkcs8.pem
mox dkim lookup selector domain
mox dkim txt <$selector._domainkey.$domain.key.pkcs8.pem
mox dkim verify message
mox dkim sign message
mox dmarc lookup domain
mox dmarc parsereportmsg message ...
mox dmarc verify remoteip mailfromaddress helodomain < message
mox dmarc checkreportaddrs domain
mox dnsbl check zone ip
mox dnsbl checkhealth zone
mox mtasts lookup domain
mox retrain accountname
mox sendmail [-Fname] [ignoredflags] [-t] [<message]
mox spf check domain ip
mox spf lookup domain
mox spf parse txtrecord
mox tlsrpt lookup domain
mox tlsrpt parsereportmsg message ...
mox version
mox bumpuidvalidity account [mailbox]
mox reassignuids account [mailboxid]
mox fixuidmeta account
mox fixmsgsize [account]
mox reparse [account]
mox ensureparsed account
mox recalculatemailboxcounts account
mox message parse message.eml
mox reassignthreads [account]

mox serve

Start mox, serving SMTP/IMAP/HTTPS.

Incoming email is accepted over SMTP. Email can be retrieved by users using IMAP. HTTP listeners are started for the admin/account web interfaces, and for automated TLS configuration. Missing essential TLS certificates are immediately requested, other TLS certificates are requested on demand.

Only implemented on unix systems, not Windows.

usage: mox serve

mox quickstart

Quickstart generates configuration files and prints instructions to quickly set up a mox instance.

Quickstart writes configuration files, prints initial admin and account passwords, DNS records you should create. If you run it on Linux it writes a systemd service file and prints commands to enable and start mox as service.

The user or uid is optional, defaults to "mox", and is the user or uid/gid mox will run as after initialization.

Quickstart assumes mox will run on the machine you run quickstart on and uses its host name and public IPs. On many systems the hostname is not a fully qualified domain name, but only the first dns "label", e.g. "mail" in case of "mail.example.org". If so, quickstart does a reverse DNS lookup to find the hostname, and as fallback uses the label plus the domain of the email address you specified. Use flag -hostname to explicitly specify the hostname mox will run on.

Mox is by far easiest to operate if you let it listen on port 443 (HTTPS) and 80 (HTTP). TLS will be fully automatic with ACME with Let's Encrypt.

You can run mox along with an existing webserver, but because of MTA-STS and autoconfig, you'll need to forward HTTPS traffic for two domains to mox. Run "mox quickstart -existing-webserver ..." to generate configuration files and instructions for configuring mox along with an existing webserver.

But please first consider configuring mox on port 443. It can itself serve domains with HTTP/HTTPS, including with automatic TLS with ACME, is easily configured through both configuration files and admin web interface, and can act as a reverse proxy (and static file server for that matter), so you can forward traffic to your existing backend applications. Look for "WebHandlers:" in the output of "mox config describe-domains" and see the output of "mox example webhandlers".

usage: mox quickstart [-existing-webserver] [-hostname host] user@domain [user | uid]
  -existing-webserver
    	use if a webserver is already running, so mox won't listen on port 80 and 443; you'll have to provide tls certificates/keys, and configure the existing webserver as reverse proxy, forwarding requests to mox.
  -hostname string
    	hostname mox will run on, by default the hostname of the machine quickstart runs on; if specified, the IPs for the hostname are configured for the public listener

mox stop

Shut mox down, giving connections maximum 3 seconds to stop before closing them.

While shutting down, new IMAP and SMTP connections will get a status response indicating temporary unavailability. Existing connections will get a 3 second period to finish their transaction and shut down. Under normal circumstances, only IMAP has long-living connections, with the IDLE command to get notified of new mail deliveries.

usage: mox stop

mox setaccountpassword

Set new password an account.

The password is read from stdin. Secrets derived from the password, but not the password itself, are stored in the account database. The stored secrets are for authentication with: scram-sha-256, scram-sha-1, cram-md5, plain text (bcrypt hash).

The parameter is an account name, as configured under Accounts in domains.conf and as present in the data/accounts/ directory, not a configured email address for an account.

usage: mox setaccountpassword account

mox setadminpassword

Set a new admin password, for the web interface.

The password is read from stdin. Its bcrypt hash is stored in a file named "adminpasswd" in the configuration directory.

usage: mox setadminpassword

mox loglevels

Print the log levels, or set a new default log level, or a level for the given package.

By default, a single log level applies to all logging in mox. But for each "pkg", an overriding log level can be configured. Examples of packages: smtpserver, smtpclient, queue, imapserver, spf, dkim, dmarc, junk, message, etc.

Specify a pkg and an empty level to clear the configured level for a package.

Valid labels: error, info, debug, trace, traceauth, tracedata.

usage: mox loglevels [level [pkg]]

mox queue list

List messages in the delivery queue.

This prints the message with its ID, last and next delivery attempts, last error.

usage: mox queue list

mox queue kick

Schedule matching messages in the queue for immediate delivery.

Messages deliveries are normally attempted with exponential backoff. The first retry after 7.5 minutes, and doubling each time. Kicking messages sets their next scheduled attempt to now, it can cause delivery to fail earlier than without rescheduling.

With the -transport flag, future delivery attempts are done using the specified transport. Transports can be configured in mox.conf, e.g. to submit to a remote queue over SMTP.

usage: mox queue kick [-id id] [-todomain domain] [-recipient address] [-transport transport]
  -id int
    	id of message in queue
  -recipient string
    	recipient email address
  -todomain string
    	destination domain of messages
  -transport string
    	transport to use for the next delivery

mox queue drop

Remove matching messages from the queue.

Dangerous operation, this completely removes the message. If you want to store the message, use "queue dump" before removing.

usage: mox queue drop [-id id] [-todomain domain] [-recipient address]
  -id int
    	id of message in queue
  -recipient string
    	recipient email address
  -todomain string
    	destination domain of messages

mox queue dump

Dump a message from the queue.

The message is printed to stdout and is in standard internet mail format.

usage: mox queue dump id

mox import maildir

Import a maildir into an account.

The mbox/maildir archive is accessed and imported by the running mox process, so it must have access to the archive files. The default suggested systemd service file isolates mox from most of the file system, with only the "data/" directory accessible, so you may want to put the mbox/maildir archive files in a directory like "data/import/" to make it available to mox.

By default, messages will train the junk filter based on their flags and, if "automatic junk flags" configuration is set, based on mailbox naming.

If the destination mailbox is the Sent mailbox, the recipients of the messages are added to the message metadata, causing later incoming messages from these recipients to be accepted, unless other reputation signals prevent that.

Users can also import mailboxes/messages through the account web page by uploading a zip or tgz file with mbox and/or maildirs.

Mailbox flags, like "seen", "answered", will be imported. An optional dovecot-keywords file can specify additional flags, like Forwarded/Junk/NotJunk.

usage: mox import maildir accountname mailboxname maildir

mox import mbox

Import an mbox into an account.

Using mbox is not recommended, maildir is a better defined format.

The mbox/maildir archive is accessed and imported by the running mox process, so it must have access to the archive files. The default suggested systemd service file isolates mox from most of the file system, with only the "data/" directory accessible, so you may want to put the mbox/maildir archive files in a directory like "data/import/" to make it available to mox.

By default, messages will train the junk filter based on their flags and, if "automatic junk flags" configuration is set, based on mailbox naming.

If the destination mailbox is the Sent mailbox, the recipients of the messages are added to the message metadata, causing later incoming messages from these recipients to be accepted, unless other reputation signals prevent that.

Users can also import mailboxes/messages through the account web page by uploading a zip or tgz file with mbox and/or maildirs.

usage: mox import mbox accountname mailboxname mbox

mox export maildir

Export one or all mailboxes from an account in maildir format.

Export bypasses a running mox instance. It opens the account mailbox/message database file directly. This may block if a running mox instance also has the database open, e.g. for IMAP connections. To export from a running instance, use the accounts web page.

usage: mox export maildir dst-dir account-path [mailbox]

mox export mbox

Export messages from one or all mailboxes in an account in mbox format.

Using mbox is not recommended. Maildir is a better format.

Export bypasses a running mox instance. It opens the account mailbox/message database file directly. This may block if a running mox instance also has the database open, e.g. for IMAP connections. To export from a running instance, use the accounts web page.

For mbox export, "mboxrd" is used where message lines starting with the magic "From " string are escaped by prepending a >. All ">*From " are escaped, otherwise reconstructing the original could lose a ">".

usage: mox export mbox dst-dir account-path [mailbox]

mox localserve

Start a local SMTP/IMAP server that accepts all messages, useful when testing/developing software that sends email.

Localserve starts mox with a configuration suitable for local email-related software development/testing. It listens for SMTP/Submission(s), IMAP(s) and HTTP(s), on the regular port numbers + 1000.

Data is stored in the system user's configuration directory under "mox-localserve", e.g. $HOME/.config/mox-localserve/ on linux, but can be overridden with the -dir flag. If the directory does not yet exist, it is automatically initialized with configuration files, an account with email address mox@localhost and password moxmoxmox, and a newly generated self-signed TLS certificate.

All incoming email to any address is accepted (if checks pass), unless the recipient localpart ends with:

- "temperror": fail with a temporary error code - "permerror": fail with a permanent error code - [45][0-9][0-9]: fail with the specific error code - "timeout": no response (for an hour)

If the localpart begins with "mailfrom" or "rcptto", the error is returned during those commands instead of during "data".

usage: mox localserve
  -dir string
    	configuration storage directory (default "$userconfigdir/mox-localserve")
  -initonly
    	write configuration files and exit
  -ip string
    	serve on this ip instead of default 127.0.0.1 and ::1. only used when writing configuration, at first launch.

mox help

Prints help about matching commands.

If multiple commands match, they are listed along with the first line of their help text. If a single command matches, its usage and full help text is printed.

usage: mox help [command ...]

mox backup

Creates a backup of the data directory.

Backup creates consistent snapshots of the databases and message files and copies other files in the data directory. Empty directories are not copied. These files can then be stored elsewhere for long-term storage, or used to fall back to should an upgrade fail. Simply copying files in the data directory while mox is running can result in unusable database files.

Message files never change (they are read-only, though can be removed) and are hard-linked so they don't consume additional space. If hardlinking fails, for example when the backup destination directory is on a different file system, a regular copy is made. Using a destination directory like "data/tmp/backup" increases the odds hardlinking succeeds: the default systemd service file specifically mounts the data directory, causing attempts to hardlink outside it to fail with an error about cross-device linking.

All files in the data directory that aren't recognized (i.e. other than known database files, message files, an acme directory, the "tmp" directory, etc), are stored, but with a warning.

A clean successful backup does not print any output by default. Use the -verbose flag for details, including timing.

To restore a backup, first shut down mox, move away the old data directory and move an earlier backed up directory in its place, run "mox verifydata", possibly with the "-fix" option, and restart mox. After the restore, you may also want to run "mox bumpuidvalidity" for each account for which messages in a mailbox changed, to force IMAP clients to synchronize mailbox state.

Before upgrading, to check if the upgrade will likely succeed, first make a backup, then use the new mox binary to run "mox verifydata" on the backup. This can change the backup files (e.g. upgrade database files, move away unrecognized message files), so you should make a new backup before actually upgrading.

usage: mox backup dest-dir
  -verbose
    	print progress

mox verifydata

Verify the contents of a data directory, typically of a backup.

Verifydata checks all database files to see if they are valid BoltDB/bstore databases. It checks that all messages in the database have a corresponding on-disk message file and there are no unrecognized files. If option -fix is specified, unrecognized message files are moved away. This may be needed after a restore, because messages enqueued or delivered in the future may get those message sequence numbers assigned and writing the message file would fail. Consistency of message/mailbox UID, UIDNEXT and UIDVALIDITY is verified as well.

Because verifydata opens the database files, schema upgrades may automatically be applied. This can happen if you use a new mox release. It is useful to run "mox verifydata" with a new binary before attempting an upgrade, but only on a copy of the database files, as made with "mox backup". Before upgrading, make a new backup again since "mox verifydata" may have upgraded the database files, possibly making them potentially no longer readable by the previous version.

usage: mox verifydata data-dir
  -fix
    	fix fixable problems, such as moving away message files not referenced by their database
  -skip-size-check
    	skip the check for message size

mox config test

Parses and validates the configuration files.

If valid, the command exits with status 0. If not valid, all errors encountered are printed.

usage: mox config test

mox config dnscheck

Check the DNS records with the configuration for the domain, and print any errors/warnings.

usage: mox config dnscheck domain

mox config dnsrecords

Prints annotated DNS records as zone file that should be created for the domain.

The zone file can be imported into existing DNS software. You should review the DNS records, especially if your domain previously/currently has email configured.

usage: mox config dnsrecords domain

mox config describe-domains

Prints an annotated empty configuration for use as domains.conf.

The domains configuration file contains the domains and their configuration, and accounts and their configuration. This includes the configured email addresses. The mox admin web interface, and the mox command line interface, can make changes to this file. Mox automatically reloads this file when it changes.

Like the static configuration, the example domains.conf printed by this command needs modifications to make it valid.

usage: mox config describe-domains >domains.conf

mox config describe-static

Prints an annotated empty configuration for use as mox.conf.

The static configuration file cannot be reloaded while mox is running. Mox has to be restarted for changes to the static configuration file to take effect.

This configuration file needs modifications to make it valid. For example, it may contain unfinished list items.

usage: mox config describe-static >mox.conf

mox config account add

Add an account with an email address and reload the configuration.

Email can be delivered to this address/account. A password has to be configured explicitly, see the setaccountpassword command.

usage: mox config account add account address

mox config account rm

Remove an account and reload the configuration.

Email addresses for this account will also be removed, and incoming email for these addresses will be rejected.

usage: mox config account rm account

mox config address add

Adds an address to an account and reloads the configuration.

If address starts with a @ (i.e. a missing localpart), this is a catchall address for the domain.

usage: mox config address add address account

mox config address rm

Remove an address and reload the configuration.

Incoming email for this address will be rejected after removing an address.

usage: mox config address rm address

mox config domain add

Adds a new domain to the configuration and reloads the configuration.

The account is used for the postmaster mailboxes the domain, including as DMARC and TLS reporting. Localpart is the "username" at the domain for this account. If must be set if and only if account does not yet exist.

usage: mox config domain add domain account [localpart]

mox config domain rm

Remove a domain from the configuration and reload the configuration.

This is a dangerous operation. Incoming email delivery for this domain will be rejected.

usage: mox config domain rm domain

mox config describe-sendmail

Describe configuration for mox when invoked as sendmail.

usage: mox config describe-sendmail >/etc/moxsubmit.conf

mox config printservice

Prints a systemd unit service file for mox.

This is the same file as generated using quickstart. If the systemd service file has changed with a newer version of mox, use this command to generate an up to date version.

usage: mox config printservice >mox.service

mox config ensureacmehostprivatekeys

Ensure host private keys exist for TLS listeners with ACME.

In mox.conf, each listener can have TLS configured. Long-lived private key files can be specified, which will be used when requesting ACME certificates. Configuring these private keys makes it feasible to publish DANE TLSA records for the corresponding public keys in DNS, protected with DNSSEC, allowing TLS certificate verification without depending on a list of Certificate Authorities (CAs). Previous versions of mox did not pre-generate private keys for use with ACME certificates, but would generate private keys on-demand. By explicitly configuring private keys, they will not change automatedly with new certificates, and the DNS TLSA records stay valid.

This command looks for listeners in mox.conf with TLS with ACME configured. For each missing host private key (of type rsa-2048 and ecdsa-p256) a key is written to config/hostkeys/. If a certificate exists in the ACME "cache", its private key is copied. Otherwise a new private key is generated. Snippets for manually updating/editing mox.conf are printed.

After running this command, and updating mox.conf, run "mox config dnsrecords" for a domain and create the TLSA DNS records it suggests to enable DANE.

usage: mox config ensureacmehostprivatekeys

mox example

List available examples, or print a specific example.

usage: mox example [name]

mox checkupdate

Check if a newer version of mox is available.

A single DNS TXT lookup to _updates.xmox.nl tells if a new version is available. If so, a changelog is fetched from https://updates.xmox.nl, and the individual entries verified with a builtin public key. The changelog is printed.

usage: mox checkupdate

mox cid

Turn an ID from a Received header into a cid, for looking up in logs.

A cid is essentially a connection counter initialized when mox starts. Each log line contains a cid. Received headers added by mox contain a unique ID that can be decrypted to a cid by admin of a mox instance only.

usage: mox cid cid

mox clientconfig

Print the configuration for email clients for a domain.

Sending email is typically not done on the SMTP port 25, but on submission ports 465 (with TLS) and 587 (without initial TLS, but usually added to the connection with STARTTLS). For IMAP, the port with TLS is 993 and without is 143.

Without TLS/STARTTLS, passwords are sent in clear text, which should only be configured over otherwise secured connections, like a VPN.

usage: mox clientconfig domain

mox dane dial

Dial the address using TLS with certificate verification using DANE.

Data is copied between connection and stdin/stdout until either side closes the connection.

usage: mox dane dial host:port
  -usages string
    	allowed usages for dane, comma-separated list (default "pkix-ta,pkix-ee,dane-ta,dane-ee")

mox dane dialmx

Connect to MX server for domain using STARTTLS verified with DANE.

If no destination host is specified, regular delivery logic is used to find the hosts to attempt delivery too. This involves following CNAMEs for the domain, looking up MX records, and possibly falling back to the domain name itself as host.

If a destination host is specified, that is the only candidate host considered for dialing.

With a list of destinations gathered, each is dialed until a successful SMTP session verified with DANE has been initialized, including EHLO and STARTTLS commands.

Once connected, data is copied between connection and stdin/stdout, until either side closes the connection.

This command follows the same logic as delivery attempts made from the queue, sharing most of its code.

usage: mox dane dialmx domain [destination-host]
  -ehlohostname string
    	hostname to send in smtp ehlo command (default "localhost")

mox dane makerecord

Print TLSA record for given certificate/key and parameters.

Valid values: - usage: pkix-ta (0), pkix-ee (1), dane-ta (2), dane-ee (3) - selector: cert (0), spki (1) - matchtype: full (0), sha2-256 (1), sha2-512 (2)

Common DANE TLSA record parameters are: dane-ee spki sha2-256, or 3 1 1, followed by a sha2-256 hash of the DER-encoded "SPKI" (subject public key info) from the certificate. An example DNS zone file entry:

_25._tcp.example.com. TLSA 3 1 1 133b919c9d65d8b1488157315327334ead8d83372db57465ecabf53ee5748aee

The first usable information from the pem file is used to compose the TLSA record. In case of selector "cert", a certificate is required. Otherwise the "subject public key info" (spki) of the first certificate or public or private key (pkcs#8, pkcs#1 or ec private key) is used.

usage: mox dane makerecord usage selector matchtype [certificate.pem | publickey.pem | privatekey.pem]

mox dns lookup

Lookup DNS name of given type.

Lookup always prints whether the response was DNSSEC-protected.

Examples:

mox dns lookup ptr 1.1.1.1 mox dns lookup mx xmox.nl mox dns lookup txt _dmarc.xmox.nl. mox dns lookup tlsa _25._tcp.xmox.nl

usage: mox dns lookup [ptr | mx | cname | ips | a | aaaa | ns | txt | srv | tlsa] name

mox dkim gened25519

Generate a new ed25519 key for use with DKIM.

Ed25519 keys are much smaller than RSA keys of comparable cryptographic strength. This is convenient because of maximum DNS message sizes. At the time of writing, not many mail servers appear to support ed25519 DKIM keys though, so it is recommended to sign messages with both RSA and ed25519 keys.

usage: mox dkim gened25519 >$selector._domainkey.$domain.ed25519.privatekey.pkcs8.pem

mox dkim genrsa

Generate a new 2048 bit RSA private key for use with DKIM.

The generated file is in PEM format, and has a comment it is generated for use with DKIM, by mox.

usage: mox dkim genrsa >$selector._domainkey.$domain.rsa2048.privatekey.pkcs8.pem

mox dkim lookup

Lookup and print the DKIM record for the selector at the domain.

usage: mox dkim lookup selector domain

mox dkim txt

Print a DKIM DNS TXT record with the public key derived from the private key read from stdin.

The DNS should be configured as a TXT record at $selector._domainkey.$domain.

usage: mox dkim txt <$selector._domainkey.$domain.key.pkcs8.pem

mox dkim verify

Verify the DKIM signatures in a message and print the results.

The message is parsed, and the DKIM-Signature headers are validated. Validation of older messages may fail because the DNS records have been removed or changed by now, or because the signature header may have specified an expiration time that was passed.

usage: mox dkim verify message

mox dkim sign

Sign a message, adding DKIM-Signature headers based on the domain in the From header.

The message is parsed, the domain looked up in the configuration files, and DKIM-Signature headers generated. The message is printed with the DKIM-Signature headers prepended.

usage: mox dkim sign message

mox dmarc lookup

Lookup dmarc policy for domain, a DNS TXT record at _dmarc.<domain>, validate and print it.

usage: mox dmarc lookup domain

mox dmarc parsereportmsg

Parse a DMARC report from an email message, and print its extracted details.

DMARC reports are periodically mailed, if requested in the DMARC DNS record of a domain. Reports are sent by mail servers that received messages with our domain in a From header. This may or may not be legatimate email. DMARC reports contain summaries of evaluations of DMARC and DKIM/SPF, which can help understand email deliverability problems.

usage: mox dmarc parsereportmsg message ...

mox dmarc verify

Parse an email message and evaluate it against the DMARC policy of the domain in the From-header.

mailfromaddress and helodomain are used for SPF validation. If both are empty, SPF validation is skipped.

mailfromaddress should be the address used as MAIL FROM in the SMTP session. For DSN messages, that address may be empty. The helo domain was specified at the beginning of the SMTP transaction that delivered the message. These values can be found in message headers.

usage: mox dmarc verify remoteip mailfromaddress helodomain < message

mox dmarc checkreportaddrs

For each reporting address in the domain's DMARC record, check if it has opted into receiving reports (if needed).

A DMARC record can request reports about DMARC evaluations to be sent to an email/http address. If the organizational domains of that of the DMARC record and that of the report destination address do not match, the destination address must opt-in to receiving DMARC reports by creating a DMARC record at <dmarcdomain>._report._dmarc.<reportdestdomain>.

usage: mox dmarc checkreportaddrs domain

mox dnsbl check

Test if IP is in the DNS blocklist of the zone, e.g. bl.spamcop.net.

If the IP is in the blocklist, an explanation is printed. This is typically a URL with more information.

usage: mox dnsbl check zone ip

mox dnsbl checkhealth

Check the health of the DNS blocklist represented by zone, e.g. bl.spamcop.net.

The health of a DNS blocklist can be checked by querying for 127.0.0.1 and 127.0.0.2. The second must and the first must not be present.

usage: mox dnsbl checkhealth zone

mox mtasts lookup

Lookup the MTASTS record and policy for the domain.

MTA-STS is a mechanism for a domain to specify if it requires TLS connections for delivering email. If a domain has a valid MTA-STS DNS TXT record at _mta-sts.<domain> it signals it implements MTA-STS. A policy can then be fetched at https://mta-sts.<domain>/.well-known/mta-sts.txt. The policy specifies the mode (enforce, testing, none), which MX servers support TLS and should be used, and how long the policy can be cached.

usage: mox mtasts lookup domain

mox retrain

Recreate and retrain the junk filter for the account.

Useful after having made changes to the junk filter configuration, or if the implementation has changed.

usage: mox retrain accountname

mox sendmail

Sendmail is a drop-in replacement for /usr/sbin/sendmail to deliver emails sent by unix processes like cron.

If invoked as "sendmail", it will act as sendmail for sending messages. Its intention is to let processes like cron send emails. Messages are submitted to an actual mail server over SMTP. The destination mail server and credentials are configured in /etc/moxsubmit.conf, see mox config describe-sendmail. The From message header is rewritten to the configured address. When the addressee appears to be a local user, because without @, the message is sent to the configured default address.

If submitting an email fails, it is added to a directory moxsubmit.failures in the user's home directory.

Most flags are ignored to fake compatibility with other sendmail implementations. A single recipient or the -t flag with a To-header is required. With the -t flag, Cc and Bcc headers are not handled specially, so Bcc is not removed and the addresses do not receive the email.

/etc/moxsubmit.conf should be group-readable and not readable by others and this binary should be setgid that group:

groupadd moxsubmit
install -m 2755 -o root -g moxsubmit mox /usr/sbin/sendmail
touch /etc/moxsubmit.conf
chown root:moxsubmit /etc/moxsubmit.conf
chmod 640 /etc/moxsubmit.conf
# edit /etc/moxsubmit.conf

usage: mox sendmail [-Fname] [ignoredflags] [-t] [<message]

mox spf check

Check the status of IP for the policy published in DNS for the domain.

IPs may be allowed to send for a domain, or disallowed, and several shades in between. If not allowed, an explanation may be provided by the policy. If so, the explanation is printed. The SPF mechanism that matched (if any) is also printed.

usage: mox spf check domain ip

mox spf lookup

Lookup the SPF record for the domain and print it.

usage: mox spf lookup domain

mox spf parse

Parse the record as SPF record. If valid, nothing is printed.

usage: mox spf parse txtrecord

mox tlsrpt lookup

Lookup the TLSRPT record for the domain.

A TLSRPT record typically contains an email address where reports about TLS connectivity should be sent. Mail servers attempting delivery to our domain should attempt to use TLS. TLSRPT lets them report how many connection successfully used TLS, and how what kind of errors occurred otherwise.

usage: mox tlsrpt lookup domain

mox tlsrpt parsereportmsg

Parse and print the TLSRPT in the message.

The report is printed in formatted JSON.

usage: mox tlsrpt parsereportmsg message ...

mox version

Prints this mox version.

usage: mox version

mox bumpuidvalidity

Change the IMAP UID validity of the mailbox, causing IMAP clients to refetch messages.

This can be useful after manually repairing metadata about the account/mailbox.

Opens account database file directly. Ensure mox does not have the account open, or is not running.

usage: mox bumpuidvalidity account [mailbox]

mox reassignuids

Reassign UIDs in one mailbox or all mailboxes in an account and bump UID validity, causing IMAP clients to refetch messages.

Opens account database file directly. Ensure mox does not have the account open, or is not running.

usage: mox reassignuids account [mailboxid]

mox fixuidmeta

Fix inconsistent UIDVALIDITY and UIDNEXT in messages/mailboxes/account.

The next UID to use for a message in a mailbox should always be higher than any existing message UID in the mailbox. If it is not, the mailbox UIDNEXT is updated.

Each mailbox has a UIDVALIDITY sequence number, which should always be lower than the per-account next UIDVALIDITY to use. If it is not, the account next UIDVALIDITY is updated.

Opens account database file directly. Ensure mox does not have the account open, or is not running.

usage: mox fixuidmeta account

mox fixmsgsize

Ensure message sizes in the database matching the sum of the message prefix length and on-disk file size.

Messages with an inconsistent size are also parsed again.

If an inconsistency is found, you should probably also run "mox bumpuidvalidity" on the mailboxes or entire account to force IMAP clients to refetch messages.

usage: mox fixmsgsize [account]

mox reparse

Parse all messages in the account or all accounts again

Can be useful after upgrading mox with improved message parsing. Messages are parsed in batches, so other access to the mailboxes/messages are not blocked while reparsing all messages.

usage: mox reparse [account]

mox ensureparsed

Ensure messages in the database have a pre-parsed MIME form in the database.

usage: mox ensureparsed account
  -all
    	store new parsed message for all messages

mox recalculatemailboxcounts

Recalculate message counts for all mailboxes in the account, and total message size for quota.

When a message is added to/removed from a mailbox, or when message flags change, the total, unread, unseen and deleted messages are accounted, the total size of the mailbox, and the total message size for the account. In case of a bug in this accounting, the numbers could become incorrect. This command will find, fix and print them.

usage: mox recalculatemailboxcounts account

mox message parse

Parse message, print JSON representation.

usage: mox message parse message.eml

mox reassignthreads

Reassign message threads.

For all accounts, or optionally only the specified account.

Threading for all messages in an account is first reset, and new base subject and normalized message-id saved with the message. Then all messages are evaluated and matched against their parents/ancestors.

Messages are matched based on the References header, with a fall-back to an In-Reply-To header, and if neither is present/valid, based only on base subject.

A References header typically points to multiple previous messages in a hierarchy. From oldest ancestor to most recent parent. An In-Reply-To header would have only a message-id of the parent message.

A message is only linked to a parent/ancestor if their base subject is the same. This ensures unrelated replies, with a new subject, are placed in their own thread.

The base subject is lower cased, has whitespace collapsed to a single space, and some components removed: leading "Re:", "Fwd:", "Fw:", or bracketed tag (that mailing lists often add, e.g. "[listname]"), trailing "(fwd)", or enclosing "[fwd: ...]".

Messages are linked to all their ancestors. If an intermediate parent/ancestor message is deleted in the future, the message can still be linked to the earlier ancestors. If the direct parent already wasn't available while matching, this is stored as the message having a "missing link" to its stored ancestors.

usage: mox reassignthreads [account]