2Command mox is a modern, secure, full-featured, open source mail server for
3low-maintenance self-hosted email.
5Mox is started with the "serve" subcommand, but mox also has many other
8Many of those commands talk to a running mox instance, through the ctl file in
9the data directory. Specify the configuration file (that holds the path to the
10data directory) through the -config flag or MOXCONF environment variable.
12Commands that don't talk to a running mox instance are often for
13testing/debugging email functionality. For example for parsing an email message,
14or looking up SPF/DKIM/DMARC records.
16Below is the usage information as printed by the command when started without
17any parameters. Followed by the help and usage information for each command.
21 mox [-config config/mox.conf] [-pedantic] ...
23 mox quickstart [-skipdial] [-existing-webserver] [-hostname host] user@domain [user | uid]
25 mox setaccountpassword account
27 mox loglevels [level [pkg]]
28 mox queue holdrules list
29 mox queue holdrules add [ruleflags]
30 mox queue holdrules remove ruleid
31 mox queue list [filtersortflags]
32 mox queue hold [filterflags]
33 mox queue unhold [filterflags]
34 mox queue schedule [filterflags] [-now] duration
35 mox queue transport [filterflags] transport
36 mox queue requiretls [filterflags] {yes | no | default}
37 mox queue fail [filterflags]
38 mox queue drop [filterflags]
40 mox queue retired list [filtersortflags]
41 mox queue retired print id
42 mox queue suppress list [-account account]
43 mox queue suppress add account address
44 mox queue suppress remove account address
45 mox queue suppress lookup [-account account] address
46 mox queue webhook list [filtersortflags]
47 mox queue webhook schedule [filterflags] duration
48 mox queue webhook cancel [filterflags]
49 mox queue webhook print id
50 mox queue webhook retired list [filtersortflags]
51 mox queue webhook retired print id
52 mox import maildir accountname mailboxname maildir
53 mox import mbox accountname mailboxname mbox
54 mox export maildir [-single] dst-dir account-path [mailbox]
55 mox export mbox [-single] dst-dir account-path [mailbox]
57 mox help [command ...]
59 mox verifydata data-dir
62 mox config dnscheck domain
63 mox config dnsrecords domain
64 mox config describe-domains >domains.conf
65 mox config describe-static >mox.conf
66 mox config account add account address
67 mox config account rm account
68 mox config address add address account
69 mox config address rm address
70 mox config domain add domain account [localpart]
71 mox config domain rm domain
72 mox config tlspubkey list [account]
73 mox config tlspubkey get fingerprint
74 mox config tlspubkey add address [name] < cert.pem
75 mox config tlspubkey rm fingerprint
76 mox config tlspubkey gen stem
77 mox config alias list domain
78 mox config alias print alias
79 mox config alias add alias@domain rcpt1@domain ...
80 mox config alias update alias@domain [-postpublic false|true -listmembers false|true -allowmsgfrom false|true]
81 mox config alias rm alias@domain
82 mox config alias addaddr alias@domain rcpt1@domain ...
83 mox config alias rmaddr alias@domain rcpt1@domain ...
84 mox config describe-sendmail >/etc/moxsubmit.conf
85 mox config printservice >mox.service
86 mox config ensureacmehostprivatekeys
87 mox config example [name]
90 mox clientconfig domain
91 mox dane dial host:port
92 mox dane dialmx domain [destination-host]
93 mox dane makerecord usage selector matchtype [certificate.pem | publickey.pem | privatekey.pem]
94 mox dns lookup [ptr | mx | cname | ips | a | aaaa | ns | txt | srv | tlsa] name
95 mox dkim gened25519 >$selector._domainkey.$domain.ed25519.privatekey.pkcs8.pem
96 mox dkim genrsa >$selector._domainkey.$domain.rsa2048.privatekey.pkcs8.pem
97 mox dkim lookup selector domain
98 mox dkim txt <$selector._domainkey.$domain.key.pkcs8.pem
99 mox dkim verify message
100 mox dkim sign message
101 mox dmarc lookup domain
102 mox dmarc parsereportmsg message ...
103 mox dmarc verify remoteip mailfromaddress helodomain < message
104 mox dmarc checkreportaddrs domain
105 mox dnsbl check zone ip
106 mox dnsbl checkhealth zone
107 mox mtasts lookup domain
108 mox retrain [accountname]
109 mox sendmail [-Fname] [ignoredflags] [-t] [<message]
110 mox spf check domain ip
111 mox spf lookup domain
112 mox spf parse txtrecord
113 mox tlsrpt lookup domain
114 mox tlsrpt parsereportmsg message ...
116 mox webapi [method [baseurl-with-credentials]
118 mox bumpuidvalidity account [mailbox]
119 mox reassignuids account [mailboxid]
120 mox fixuidmeta account
121 mox fixmsgsize [account]
122 mox reparse [account]
123 mox ensureparsed account
124 mox recalculatemailboxcounts account
125 mox message parse message.eml
126 mox reassignthreads [account]
130Start mox, serving SMTP/IMAP/HTTPS.
132Incoming email is accepted over SMTP. Email can be retrieved by users using
133IMAP. HTTP listeners are started for the admin/account web interfaces, and for
134automated TLS configuration. Missing essential TLS certificates are immediately
135requested, other TLS certificates are requested on demand.
137Only implemented on unix systems, not Windows.
143Quickstart generates configuration files and prints instructions to quickly set up a mox instance.
145Quickstart writes configuration files, prints initial admin and account
146passwords, DNS records you should create. If you run it on Linux it writes a
147systemd service file and prints commands to enable and start mox as service.
149All output is written to quickstart.log for later reference.
151The user or uid is optional, defaults to "mox", and is the user or uid/gid mox
152will run as after initialization.
154Quickstart assumes mox will run on the machine you run quickstart on and uses
155its host name and public IPs. On many systems the hostname is not a fully
156qualified domain name, but only the first dns "label", e.g. "mail" in case of
157"mail.example.org". If so, quickstart does a reverse DNS lookup to find the
158hostname, and as fallback uses the label plus the domain of the email address
159you specified. Use flag -hostname to explicitly specify the hostname mox will
162Mox is by far easiest to operate if you let it listen on port 443 (HTTPS) and
16380 (HTTP). TLS will be fully automatic with ACME with Let's Encrypt.
165You can run mox along with an existing webserver, but because of MTA-STS and
166autoconfig, you'll need to forward HTTPS traffic for two domains to mox. Run
167"mox quickstart -existing-webserver ..." to generate configuration files and
168instructions for configuring mox along with an existing webserver.
170But please first consider configuring mox on port 443. It can itself serve
171domains with HTTP/HTTPS, including with automatic TLS with ACME, is easily
172configured through both configuration files and admin web interface, and can act
173as a reverse proxy (and static file server for that matter), so you can forward
174traffic to your existing backend applications. Look for "WebHandlers:" in the
175output of "mox config describe-domains" and see the output of
176"mox config example webhandlers".
178 usage: mox quickstart [-skipdial] [-existing-webserver] [-hostname host] user@domain [user | uid]
180 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.
182 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
184 skip check for outgoing smtp (port 25) connectivity
188Shut mox down, giving connections maximum 3 seconds to stop before closing them.
190While shutting down, new IMAP and SMTP connections will get a status response
191indicating temporary unavailability. Existing connections will get a 3 second
192period to finish their transaction and shut down. Under normal circumstances,
193only IMAP has long-living connections, with the IDLE command to get notified of
198# mox setaccountpassword
200Set new password an account.
202The password is read from stdin. Secrets derived from the password, but not the
203password itself, are stored in the account database. The stored secrets are for
204authentication with: scram-sha-256, scram-sha-1, cram-md5, plain text (bcrypt
207The parameter is an account name, as configured under Accounts in domains.conf
208and as present in the data/accounts/ directory, not a configured email address
211 usage: mox setaccountpassword account
213# mox setadminpassword
215Set a new admin password, for the web interface.
217The password is read from stdin. Its bcrypt hash is stored in a file named
218"adminpasswd" in the configuration directory.
220 usage: mox setadminpassword
224Print the log levels, or set a new default log level, or a level for the given package.
226By default, a single log level applies to all logging in mox. But for each
227"pkg", an overriding log level can be configured. Examples of packages:
228smtpserver, smtpclient, queue, imapserver, spf, dkim, dmarc, junk, message,
231Specify a pkg and an empty level to clear the configured level for a package.
233Valid labels: error, info, debug, trace, traceauth, tracedata.
235 usage: mox loglevels [level [pkg]]
237# mox queue holdrules list
239List hold rules for the delivery queue.
241Messages submitted to the queue that match a hold rule will be marked as on hold
242and not scheduled for delivery.
244 usage: mox queue holdrules list
246# mox queue holdrules add
248Add hold rule for the delivery queue.
250Add a hold rule to mark matching newly submitted messages as on hold. Set the
251matching rules with the flags. Don't specify any flags to match all submitted
254 usage: mox queue holdrules add [ruleflags]
256 account submitting the message
262# mox queue holdrules remove
264Remove hold rule for the delivery queue.
266Remove a hold rule by its id.
268 usage: mox queue holdrules remove ruleid
272List matching messages in the delivery queue.
274Prints the message with its ID, last and next delivery attempts, last error.
276 usage: mox queue list [filtersortflags]
278 account that queued the message
280 sort ascending instead of descending (default)
282 from address of message, use "@example.com" to match all messages for a domain
284 true or false, whether to match only messages that are (not) on hold
286 comma-separated list of message IDs
288 number of messages to return
290 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
292 field to sort by, "nextattempt" (default) or "queued"
294 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
296 recipient address of message, use "@example.com" to match all messages for a domain
298 transport to use for messages, empty string sets the default behaviour
302Mark matching messages on hold.
304Messages that are on hold are not delivered until marked as off hold again, or
305otherwise handled by the admin.
307 usage: mox queue hold [filterflags]
309 account that queued the message
311 from address of message, use "@example.com" to match all messages for a domain
313 true or false, whether to match only messages that are (not) on hold
315 comma-separated list of message IDs
317 number of messages to return
319 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
321 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
323 recipient address of message, use "@example.com" to match all messages for a domain
325 transport to use for messages, empty string sets the default behaviour
329Mark matching messages off hold.
331Once off hold, messages can be delivered according to their current next
332delivery attempt. See the "queue schedule" command.
334 usage: mox queue unhold [filterflags]
336 account that queued the message
338 from address of message, use "@example.com" to match all messages for a domain
340 true or false, whether to match only messages that are (not) on hold
342 comma-separated list of message IDs
344 number of messages to return
346 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
348 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
350 recipient address of message, use "@example.com" to match all messages for a domain
352 transport to use for messages, empty string sets the default behaviour
356Change next delivery attempt for matching messages.
358The next delivery attempt is adjusted by the duration parameter. If the -now
359flag is set, the new delivery attempt is set to the duration added to the
360current time, instead of added to the current scheduled time.
362Schedule immediate delivery with "mox queue schedule -now 0".
364 usage: mox queue schedule [filterflags] [-now] duration
366 account that queued the message
368 from address of message, use "@example.com" to match all messages for a domain
370 true or false, whether to match only messages that are (not) on hold
372 comma-separated list of message IDs
374 number of messages to return
376 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
378 schedule for duration relative to current time instead of relative to current next delivery attempt for messages
380 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
382 recipient address of message, use "@example.com" to match all messages for a domain
384 transport to use for messages, empty string sets the default behaviour
388Set transport for matching messages.
390By default, the routing rules determine how a message is delivered. The default
391and common case is direct delivery with SMTP. Messages can get a previously
392configured transport assigned to use for delivery, e.g. using submission to
393another mail server or with connections over a SOCKS proxy.
395 usage: mox queue transport [filterflags] transport
397 account that queued the message
399 from address of message, use "@example.com" to match all messages for a domain
401 true or false, whether to match only messages that are (not) on hold
403 comma-separated list of message IDs
405 number of messages to return
407 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
409 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
411 recipient address of message, use "@example.com" to match all messages for a domain
413 transport to use for messages, empty string sets the default behaviour
415# mox queue requiretls
417Set TLS requirements for delivery of matching messages.
419Value "yes" is handled as if the RequireTLS extension was specified during
422Value "no" is handled as if the message has a header "TLS-Required: No". This
423header is not added by the queue. If messages without this header are relayed
424through other mail servers they will apply their own default TLS policy.
426Value "default" is the default behaviour, currently for unverified opportunistic
429 usage: mox queue requiretls [filterflags] {yes | no | default}
431 account that queued the message
433 from address of message, use "@example.com" to match all messages for a domain
435 true or false, whether to match only messages that are (not) on hold
437 comma-separated list of message IDs
439 number of messages to return
441 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
443 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
445 recipient address of message, use "@example.com" to match all messages for a domain
447 transport to use for messages, empty string sets the default behaviour
451Fail delivery of matching messages, delivering DSNs.
453Failing a message is handled similar to how delivery is given up after all
454delivery attempts failed. The DSN (delivery status notification) message
455contains a line saying the message was canceled by the admin.
457 usage: mox queue fail [filterflags]
459 account that queued the message
461 from address of message, use "@example.com" to match all messages for a domain
463 true or false, whether to match only messages that are (not) on hold
465 comma-separated list of message IDs
467 number of messages to return
469 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
471 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
473 recipient address of message, use "@example.com" to match all messages for a domain
475 transport to use for messages, empty string sets the default behaviour
479Remove matching messages from the queue.
481Dangerous operation, this completely removes the message. If you want to store
482the message, use "queue dump" before removing.
484 usage: mox queue drop [filterflags]
486 account that queued the message
488 from address of message, use "@example.com" to match all messages for a domain
490 true or false, whether to match only messages that are (not) on hold
492 comma-separated list of message IDs
494 number of messages to return
496 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
498 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
500 recipient address of message, use "@example.com" to match all messages for a domain
502 transport to use for messages, empty string sets the default behaviour
506Dump a message from the queue.
508The message is printed to stdout and is in standard internet mail format.
510 usage: mox queue dump id
512# mox queue retired list
514List matching messages in the retired queue.
516Prints messages with their ID and results.
518 usage: mox queue retired list [filtersortflags]
520 account that queued the message
522 sort ascending instead of descending (default)
524 from address of message, use "@example.com" to match all messages for a domain
526 comma-separated list of retired message IDs
528 filter by time of last activity relative to now, value must start with "<" (before now) or ">" (after now)
530 number of messages to return
532 "success" or "failure" as result of delivery
534 field to sort by, "lastactivity" (default) or "queued"
536 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
538 recipient address of message, use "@example.com" to match all messages for a domain
540 transport to use for messages, empty string sets the default behaviour
542# mox queue retired print
544Print a message from the retired queue.
546Prints a JSON representation of the information from the retired queue.
548 usage: mox queue retired print id
550# mox queue suppress list
552Print addresses in suppression list.
554 usage: mox queue suppress list [-account account]
556 only show suppression list for this account
558# mox queue suppress add
560Add address to suppression list for account.
562 usage: mox queue suppress add account address
564# mox queue suppress remove
566Remove address from suppression list for account.
568 usage: mox queue suppress remove account address
570# mox queue suppress lookup
572Check if address is present in suppression list, for any or specific account.
574 usage: mox queue suppress lookup [-account account] address
576 only check address in specified account
578# mox queue webhook list
580List matching webhooks in the queue.
582Prints list of webhooks, their IDs and basic information.
584 usage: mox queue webhook list [filtersortflags]
586 account that queued the message/webhook
588 sort ascending instead of descending (default)
590 event this webhook is about: incoming, delivered, suppressed, delayed, failed, relayed, expanded, canceled, unrecognized
592 comma-separated list of webhook IDs
594 number of webhooks to return
596 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
598 field to sort by, "nextattempt" (default) or "queued"
600 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
602# mox queue webhook schedule
604Change next delivery attempt for matching webhooks.
606The next delivery attempt is adjusted by the duration parameter. If the -now
607flag is set, the new delivery attempt is set to the duration added to the
608current time, instead of added to the current scheduled time.
610Schedule immediate delivery with "mox queue schedule -now 0".
612 usage: mox queue webhook schedule [filterflags] duration
614 account that queued the message/webhook
616 event this webhook is about: incoming, delivered, suppressed, delayed, failed, relayed, expanded, canceled, unrecognized
618 comma-separated list of webhook IDs
620 number of webhooks to return
622 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
624 schedule for duration relative to current time instead of relative to current next delivery attempt for webhooks
626 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
628# mox queue webhook cancel
630Fail delivery of matching webhooks.
632 usage: mox queue webhook cancel [filterflags]
634 account that queued the message/webhook
636 event this webhook is about: incoming, delivered, suppressed, delayed, failed, relayed, expanded, canceled, unrecognized
638 comma-separated list of webhook IDs
640 number of webhooks to return
642 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
644 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
646# mox queue webhook print
648Print details of a webhook from the queue.
650The webhook is printed to stdout as JSON.
652 usage: mox queue webhook print id
654# mox queue webhook retired list
656List matching webhooks in the retired queue.
658Prints list of retired webhooks, their IDs and basic information.
660 usage: mox queue webhook retired list [filtersortflags]
662 account that queued the message/webhook
664 sort ascending instead of descending (default)
666 event this webhook is about: incoming, delivered, suppressed, delayed, failed, relayed, expanded, canceled, unrecognized
668 comma-separated list of retired webhook IDs
670 filter by time of last activity relative to now, value must start with "<" (before now) or ">" (after now)
672 number of webhooks to return
674 field to sort by, "lastactivity" (default) or "queued"
676 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
678# mox queue webhook retired print
680Print details of a webhook from the retired queue.
682The retired webhook is printed to stdout as JSON.
684 usage: mox queue webhook retired print id
688Import a maildir into an account.
690The mbox/maildir archive is accessed and imported by the running mox process, so
691it must have access to the archive files. The default suggested systemd service
692file isolates mox from most of the file system, with only the "data/" directory
693accessible, so you may want to put the mbox/maildir archive files in a
694directory like "data/import/" to make it available to mox.
696By default, messages will train the junk filter based on their flags and, if
697"automatic junk flags" configuration is set, based on mailbox naming.
699If the destination mailbox is the Sent mailbox, the recipients of the messages
700are added to the message metadata, causing later incoming messages from these
701recipients to be accepted, unless other reputation signals prevent that.
703Users can also import mailboxes/messages through the account web page by
704uploading a zip or tgz file with mbox and/or maildirs.
706Messages are imported even if already present. Importing messages twice will
707result in duplicate messages.
709Mailbox flags, like "seen", "answered", will be imported. An optional
710dovecot-keywords file can specify additional flags, like Forwarded/Junk/NotJunk.
712 usage: mox import maildir accountname mailboxname maildir
716Import an mbox into an account.
718Using mbox is not recommended, maildir is a better defined format.
720The mbox/maildir archive is accessed and imported by the running mox process, so
721it must have access to the archive files. The default suggested systemd service
722file isolates mox from most of the file system, with only the "data/" directory
723accessible, so you may want to put the mbox/maildir archive files in a
724directory like "data/import/" to make it available to mox.
726By default, messages will train the junk filter based on their flags and, if
727"automatic junk flags" configuration is set, based on mailbox naming.
729If the destination mailbox is the Sent mailbox, the recipients of the messages
730are added to the message metadata, causing later incoming messages from these
731recipients to be accepted, unless other reputation signals prevent that.
733Users can also import mailboxes/messages through the account web page by
734uploading a zip or tgz file with mbox and/or maildirs.
736Messages are imported even if already present. Importing messages twice will
737result in duplicate messages.
739 usage: mox import mbox accountname mailboxname mbox
743Export one or all mailboxes from an account in maildir format.
745Export bypasses a running mox instance. It opens the account mailbox/message
746database file directly. This may block if a running mox instance also has the
747database open, e.g. for IMAP connections. To export from a running instance, use
748the accounts web page or webmail.
750 usage: mox export maildir [-single] dst-dir account-path [mailbox]
752 export single mailbox, without any children. disabled if mailbox isn't specified.
756Export messages from one or all mailboxes in an account in mbox format.
758Using mbox is not recommended. Maildir is a better format.
760Export bypasses a running mox instance. It opens the account mailbox/message
761database file directly. This may block if a running mox instance also has the
762database open, e.g. for IMAP connections. To export from a running instance, use
763the accounts web page or webmail.
765For mbox export, "mboxrd" is used where message lines starting with the magic
766"From " string are escaped by prepending a >. All ">*From " are escaped,
767otherwise reconstructing the original could lose a ">".
769 usage: mox export mbox [-single] dst-dir account-path [mailbox]
771 export single mailbox, without any children. disabled if mailbox isn't specified.
775Start a local SMTP/IMAP server that accepts all messages, useful when testing/developing software that sends email.
777Localserve starts mox with a configuration suitable for local email-related
778software development/testing. It listens for SMTP/Submission(s), IMAP(s) and
779HTTP(s), on the regular port numbers + 1000.
781Data is stored in the system user's configuration directory under
782"mox-localserve", e.g. $HOME/.config/mox-localserve/ on linux, but can be
783overridden with the -dir flag. If the directory does not yet exist, it is
784automatically initialized with configuration files, an account with email
785address mox@localhost and password moxmoxmox, and a newly generated self-signed
788Incoming messages are delivered as normal, falling back to accepting and
789delivering to the mox account for unknown addresses.
790Submitted messages are added to the queue, which delivers by ignoring the
791destination servers, always connecting to itself instead.
793Recipient addresses with the following localpart suffixes are handled specially:
795- "temperror": fail with a temporary error code
796- "permerror": fail with a permanent error code
797- [45][0-9][0-9]: fail with the specific error code
798- "timeout": no response (for an hour)
800If the localpart begins with "mailfrom" or "rcptto", the error is returned
801during those commands instead of during "data".
803 usage: mox localserve
805 configuration storage directory (default "$userconfigdir/mox-localserve")
807 write configuration files and exit
809 serve on this ip instead of default 127.0.0.1 and ::1. only used when writing configuration, at first launch.
813Prints help about matching commands.
815If multiple commands match, they are listed along with the first line of their help text.
816If a single command matches, its usage and full help text is printed.
818 usage: mox help [command ...]
822Creates a backup of the data directory.
824Backup creates consistent snapshots of the databases and message files and
825copies other files in the data directory. Empty directories are not copied.
826These files can then be stored elsewhere for long-term storage, or used to fall
827back to should an upgrade fail. Simply copying files in the data directory
828while mox is running can result in unusable database files.
830Message files never change (they are read-only, though can be removed) and are
831hard-linked so they don't consume additional space. If hardlinking fails, for
832example when the backup destination directory is on a different file system, a
833regular copy is made. Using a destination directory like "data/tmp/backup"
834increases the odds hardlinking succeeds: the default systemd service file
835specifically mounts the data directory, causing attempts to hardlink outside it
836to fail with an error about cross-device linking.
838All files in the data directory that aren't recognized (i.e. other than known
839database files, message files, an acme directory, the "tmp" directory, etc),
840are stored, but with a warning.
842Remove files in the destination directory before doing another backup. The
843backup command will not overwrite files, but print and return errors.
845Exit code 0 indicates the backup was successful. A clean successful backup does
846not print any output, but may print warnings. Use the -verbose flag for
847details, including timing.
849To restore a backup, first shut down mox, move away the old data directory and
850move an earlier backed up directory in its place, run "mox verifydata",
851possibly with the "-fix" option, and restart mox. After the restore, you may
852also want to run "mox bumpuidvalidity" for each account for which messages in a
853mailbox changed, to force IMAP clients to synchronize mailbox state.
855Before upgrading, to check if the upgrade will likely succeed, first make a
856backup, then use the new mox binary to run "mox verifydata" on the backup. This
857can change the backup files (e.g. upgrade database files, move away
858unrecognized message files), so you should make a new backup before actually
861 usage: mox backup dest-dir
867Verify the contents of a data directory, typically of a backup.
869Verifydata checks all database files to see if they are valid BoltDB/bstore
870databases. It checks that all messages in the database have a corresponding
871on-disk message file and there are no unrecognized files. If option -fix is
872specified, unrecognized message files are moved away. This may be needed after
873a restore, because messages enqueued or delivered in the future may get those
874message sequence numbers assigned and writing the message file would fail.
875Consistency of message/mailbox UID, UIDNEXT and UIDVALIDITY is verified as
878Because verifydata opens the database files, schema upgrades may automatically
879be applied. This can happen if you use a new mox release. It is useful to run
880"mox verifydata" with a new binary before attempting an upgrade, but only on a
881copy of the database files, as made with "mox backup". Before upgrading, make a
882new backup again since "mox verifydata" may have upgraded the database files,
883possibly making them potentially no longer readable by the previous version.
885 usage: mox verifydata data-dir
887 fix fixable problems, such as moving away message files not referenced by their database
889 skip the check for message size
893Print licenses of mox source code and dependencies.
899Parses and validates the configuration files.
901If valid, the command exits with status 0. If not valid, all errors encountered
904 usage: mox config test
908Check the DNS records with the configuration for the domain, and print any errors/warnings.
910 usage: mox config dnscheck domain
912# mox config dnsrecords
914Prints annotated DNS records as zone file that should be created for the domain.
916The zone file can be imported into existing DNS software. You should review the
917DNS records, especially if your domain previously/currently has email
920 usage: mox config dnsrecords domain
922# mox config describe-domains
924Prints an annotated empty configuration for use as domains.conf.
926The domains configuration file contains the domains and their configuration,
927and accounts and their configuration. This includes the configured email
928addresses. The mox admin web interface, and the mox command line interface, can
929make changes to this file. Mox automatically reloads this file when it changes.
931Like the static configuration, the example domains.conf printed by this command
932needs modifications to make it valid.
934 usage: mox config describe-domains >domains.conf
936# mox config describe-static
938Prints an annotated empty configuration for use as mox.conf.
940The static configuration file cannot be reloaded while mox is running. Mox has
941to be restarted for changes to the static configuration file to take effect.
943This configuration file needs modifications to make it valid. For example, it
944may contain unfinished list items.
946 usage: mox config describe-static >mox.conf
948# mox config account add
950Add an account with an email address and reload the configuration.
952Email can be delivered to this address/account. A password has to be configured
953explicitly, see the setaccountpassword command.
955 usage: mox config account add account address
957# mox config account rm
959Remove an account and reload the configuration.
961Email addresses for this account will also be removed, and incoming email for
962these addresses will be rejected.
964All data for the account will be removed.
966 usage: mox config account rm account
968# mox config address add
970Adds an address to an account and reloads the configuration.
972If address starts with a @ (i.e. a missing localpart), this is a catchall
973address for the domain.
975 usage: mox config address add address account
977# mox config address rm
979Remove an address and reload the configuration.
981Incoming email for this address will be rejected after removing an address.
983 usage: mox config address rm address
985# mox config domain add
987Adds a new domain to the configuration and reloads the configuration.
989The account is used for the postmaster mailboxes the domain, including as DMARC and
990TLS reporting. Localpart is the "username" at the domain for this account. If
991must be set if and only if account does not yet exist.
993 usage: mox config domain add domain account [localpart]
995# mox config domain rm
997Remove a domain from the configuration and reload the configuration.
999This is a dangerous operation. Incoming email delivery for this domain will be
1002 usage: mox config domain rm domain
1004# mox config tlspubkey list
1006List TLS public keys for TLS client certificate authentication.
1008If account is absent, the TLS public keys for all accounts are listed.
1010 usage: mox config tlspubkey list [account]
1012# mox config tlspubkey get
1014Get a TLS public key for a fingerprint.
1016Prints the type, name, account and address for the key, and the certificate in
1019 usage: mox config tlspubkey get fingerprint
1021# mox config tlspubkey add
1023Add a TLS public key to the account of the given address.
1025The public key is read from the certificate.
1027The optional name is a human-readable descriptive name of the key. If absent,
1028the CommonName from the certificate is used.
1030 usage: mox config tlspubkey add address [name] < cert.pem
1032 Don't automatically switch new IMAP connections authenticated with this key to "authenticated" state after the TLS handshake. For working around clients that ignore the untagged IMAP PREAUTH response and try to authenticate while already authenticated.
1034# mox config tlspubkey rm
1036Remove TLS public key for fingerprint.
1038 usage: mox config tlspubkey rm fingerprint
1040# mox config tlspubkey gen
1042Generate an ed25519 private key and minimal certificate for use a TLS public key and write to files starting with stem.
1044The private key is written to $stem.$timestamp.ed25519privatekey.pkcs8.pem.
1045The certificate is written to $stem.$timestamp.certificate.pem.
1046The private key and certificate are also written to
1047$stem.$timestamp.ed25519privatekey-certificate.pem.
1049The certificate can be added to an account with "mox config account tlspubkey add".
1051The combined file can be used with "mox sendmail".
1053The private key is also written to standard error in raw-url-base64-encoded
1054form, also for use with "mox sendmail". The fingerprint is written to standard
1055error too, for reference.
1057 usage: mox config tlspubkey gen stem
1059# mox config alias list
1061Show aliases (lists) for domain.
1063 usage: mox config alias list domain
1065# mox config alias print
1067Print settings and members of alias (list).
1069 usage: mox config alias print alias
1071# mox config alias add
1073Add new alias (list) with one or more addresses and public posting enabled.
1075An alias is used for delivering incoming email to multiple recipients. If you
1076want to add an address to an account, don't use an alias, just add the address
1079 usage: mox config alias add alias@domain rcpt1@domain ...
1081# mox config alias update
1083Update alias (list) configuration.
1085 usage: mox config alias update alias@domain [-postpublic false|true -listmembers false|true -allowmsgfrom false|true]
1086 -allowmsgfrom string
1087 whether alias address can be used in message from header
1089 whether list members can list members
1091 whether anyone or only list members can post
1093# mox config alias rm
1097 usage: mox config alias rm alias@domain
1099# mox config alias addaddr
1101Add addresses to alias (list).
1103 usage: mox config alias addaddr alias@domain rcpt1@domain ...
1105# mox config alias rmaddr
1107Remove addresses from alias (list).
1109 usage: mox config alias rmaddr alias@domain rcpt1@domain ...
1111# mox config describe-sendmail
1113Describe configuration for mox when invoked as sendmail.
1115 usage: mox config describe-sendmail >/etc/moxsubmit.conf
1117# mox config printservice
1119Prints a systemd unit service file for mox.
1121This is the same file as generated using quickstart. If the systemd service file
1122has changed with a newer version of mox, use this command to generate an up to
1125 usage: mox config printservice >mox.service
1127# mox config ensureacmehostprivatekeys
1129Ensure host private keys exist for TLS listeners with ACME.
1131In mox.conf, each listener can have TLS configured. Long-lived private key files
1132can be specified, which will be used when requesting ACME certificates.
1133Configuring these private keys makes it feasible to publish DANE TLSA records
1134for the corresponding public keys in DNS, protected with DNSSEC, allowing TLS
1135certificate verification without depending on a list of Certificate Authorities
1136(CAs). Previous versions of mox did not pre-generate private keys for use with
1137ACME certificates, but would generate private keys on-demand. By explicitly
1138configuring private keys, they will not change automatedly with new
1139certificates, and the DNS TLSA records stay valid.
1141This command looks for listeners in mox.conf with TLS with ACME configured. For
1142each missing host private key (of type rsa-2048 and ecdsa-p256) a key is written
1143to config/hostkeys/. If a certificate exists in the ACME "cache", its private
1144key is copied. Otherwise a new private key is generated. Snippets for manually
1145updating/editing mox.conf are printed.
1147After running this command, and updating mox.conf, run "mox config dnsrecords"
1148for a domain and create the TLSA DNS records it suggests to enable DANE.
1150 usage: mox config ensureacmehostprivatekeys
1154List available config examples, or print a specific example.
1156 usage: mox config example [name]
1160Check if a newer version of mox is available.
1162A single DNS TXT lookup to _updates.xmox.nl tells if a new version is
1163available. If so, a changelog is fetched from https://updates.xmox.nl, and the
1164individual entries verified with a builtin public key. The changelog is
1167 usage: mox checkupdate
1171Turn an ID from a Received header into a cid, for looking up in logs.
1173A cid is essentially a connection counter initialized when mox starts. Each log
1174line contains a cid. Received headers added by mox contain a unique ID that can
1175be decrypted to a cid by admin of a mox instance only.
1181Print the configuration for email clients for a domain.
1183Sending email is typically not done on the SMTP port 25, but on submission
1184ports 465 (with TLS) and 587 (without initial TLS, but usually added to the
1185connection with STARTTLS). For IMAP, the port with TLS is 993 and without is
1188Without TLS/STARTTLS, passwords are sent in clear text, which should only be
1189configured over otherwise secured connections, like a VPN.
1191 usage: mox clientconfig domain
1195Dial the address using TLS with certificate verification using DANE.
1197Data is copied between connection and stdin/stdout until either side closes the
1200 usage: mox dane dial host:port
1202 allowed usages for dane, comma-separated list (default "pkix-ta,pkix-ee,dane-ta,dane-ee")
1206Connect to MX server for domain using STARTTLS verified with DANE.
1208If no destination host is specified, regular delivery logic is used to find the
1209hosts to attempt delivery too. This involves following CNAMEs for the domain,
1210looking up MX records, and possibly falling back to the domain name itself as
1213If a destination host is specified, that is the only candidate host considered
1216With a list of destinations gathered, each is dialed until a successful SMTP
1217session verified with DANE has been initialized, including EHLO and STARTTLS
1220Once connected, data is copied between connection and stdin/stdout, until
1221either side closes the connection.
1223This command follows the same logic as delivery attempts made from the queue,
1224sharing most of its code.
1226 usage: mox dane dialmx domain [destination-host]
1227 -ehlohostname string
1228 hostname to send in smtp ehlo command (default "localhost")
1230# mox dane makerecord
1232Print TLSA record for given certificate/key and parameters.
1235- usage: pkix-ta (0), pkix-ee (1), dane-ta (2), dane-ee (3)
1236- selector: cert (0), spki (1)
1237- matchtype: full (0), sha2-256 (1), sha2-512 (2)
1239Common DANE TLSA record parameters are: dane-ee spki sha2-256, or 3 1 1,
1240followed by a sha2-256 hash of the DER-encoded "SPKI" (subject public key info)
1241from the certificate. An example DNS zone file entry:
1243 _25._tcp.example.com. TLSA 3 1 1 133b919c9d65d8b1488157315327334ead8d83372db57465ecabf53ee5748aee
1245The first usable information from the pem file is used to compose the TLSA
1246record. In case of selector "cert", a certificate is required. Otherwise the
1247"subject public key info" (spki) of the first certificate or public or private
1248key (pkcs#8, pkcs#1 or ec private key) is used.
1250 usage: mox dane makerecord usage selector matchtype [certificate.pem | publickey.pem | privatekey.pem]
1254Lookup DNS name of given type.
1256Lookup always prints whether the response was DNSSEC-protected.
1260mox dns lookup ptr 1.1.1.1
1261mox dns lookup mx xmox.nl
1262mox dns lookup txt _dmarc.xmox.nl.
1263mox dns lookup tlsa _25._tcp.xmox.nl
1265 usage: mox dns lookup [ptr | mx | cname | ips | a | aaaa | ns | txt | srv | tlsa] name
1267# mox dkim gened25519
1269Generate a new ed25519 key for use with DKIM.
1271Ed25519 keys are much smaller than RSA keys of comparable cryptographic
1272strength. This is convenient because of maximum DNS message sizes. At the time
1273of writing, not many mail servers appear to support ed25519 DKIM keys though,
1274so it is recommended to sign messages with both RSA and ed25519 keys.
1276 usage: mox dkim gened25519 >$selector._domainkey.$domain.ed25519.privatekey.pkcs8.pem
1280Generate a new 2048 bit RSA private key for use with DKIM.
1282The generated file is in PEM format, and has a comment it is generated for use
1285 usage: mox dkim genrsa >$selector._domainkey.$domain.rsa2048.privatekey.pkcs8.pem
1289Lookup and print the DKIM record for the selector at the domain.
1291 usage: mox dkim lookup selector domain
1295Print a DKIM DNS TXT record with the public key derived from the private key read from stdin.
1297The DNS should be configured as a TXT record at $selector._domainkey.$domain.
1299 usage: mox dkim txt <$selector._domainkey.$domain.key.pkcs8.pem
1303Verify the DKIM signatures in a message and print the results.
1305The message is parsed, and the DKIM-Signature headers are validated. Validation
1306of older messages may fail because the DNS records have been removed or changed
1307by now, or because the signature header may have specified an expiration time
1310 usage: mox dkim verify message
1314Sign a message, adding DKIM-Signature headers based on the domain in the From header.
1316The message is parsed, the domain looked up in the configuration files, and
1317DKIM-Signature headers generated. The message is printed with the DKIM-Signature
1320 usage: mox dkim sign message
1324Lookup dmarc policy for domain, a DNS TXT record at _dmarc.<domain>, validate and print it.
1326 usage: mox dmarc lookup domain
1328# mox dmarc parsereportmsg
1330Parse a DMARC report from an email message, and print its extracted details.
1332DMARC reports are periodically mailed, if requested in the DMARC DNS record of
1333a domain. Reports are sent by mail servers that received messages with our
1334domain in a From header. This may or may not be legatimate email. DMARC reports
1335contain summaries of evaluations of DMARC and DKIM/SPF, which can help
1336understand email deliverability problems.
1338 usage: mox dmarc parsereportmsg message ...
1342Parse an email message and evaluate it against the DMARC policy of the domain in the From-header.
1344mailfromaddress and helodomain are used for SPF validation. If both are empty,
1345SPF validation is skipped.
1347mailfromaddress should be the address used as MAIL FROM in the SMTP session.
1348For DSN messages, that address may be empty. The helo domain was specified at
1349the beginning of the SMTP transaction that delivered the message. These values
1350can be found in message headers.
1352 usage: mox dmarc verify remoteip mailfromaddress helodomain < message
1354# mox dmarc checkreportaddrs
1356For each reporting address in the domain's DMARC record, check if it has opted into receiving reports (if needed).
1358A DMARC record can request reports about DMARC evaluations to be sent to an
1359email/http address. If the organizational domains of that of the DMARC record
1360and that of the report destination address do not match, the destination
1361address must opt-in to receiving DMARC reports by creating a DMARC record at
1362<dmarcdomain>._report._dmarc.<reportdestdomain>.
1364 usage: mox dmarc checkreportaddrs domain
1368Test if IP is in the DNS blocklist of the zone, e.g. bl.spamcop.net.
1370If the IP is in the blocklist, an explanation is printed. This is typically a
1371URL with more information.
1373 usage: mox dnsbl check zone ip
1375# mox dnsbl checkhealth
1377Check the health of the DNS blocklist represented by zone, e.g. bl.spamcop.net.
1379The health of a DNS blocklist can be checked by querying for 127.0.0.1 and
1380127.0.0.2. The second must and the first must not be present.
1382 usage: mox dnsbl checkhealth zone
1386Lookup the MTASTS record and policy for the domain.
1388MTA-STS is a mechanism for a domain to specify if it requires TLS connections
1389for delivering email. If a domain has a valid MTA-STS DNS TXT record at
1390_mta-sts.<domain> it signals it implements MTA-STS. A policy can then be
1391fetched at https://mta-sts.<domain>/.well-known/mta-sts.txt. The policy
1392specifies the mode (enforce, testing, none), which MX servers support TLS and
1393should be used, and how long the policy can be cached.
1395 usage: mox mtasts lookup domain
1399Recreate and retrain the junk filter for the account or all accounts.
1401Useful after having made changes to the junk filter configuration, or if the
1402implementation has changed.
1404 usage: mox retrain [accountname]
1408Sendmail is a drop-in replacement for /usr/sbin/sendmail to deliver emails sent by unix processes like cron.
1410If invoked as "sendmail", it will act as sendmail for sending messages. Its
1411intention is to let processes like cron send emails. Messages are submitted to
1412an actual mail server over SMTP. The destination mail server and credentials are
1413configured in /etc/moxsubmit.conf, see mox config describe-sendmail. The From
1414message header is rewritten to the configured address. When the addressee
1415appears to be a local user, because without @, the message is sent to the
1416configured default address.
1418If submitting an email fails, it is added to a directory moxsubmit.failures in
1419the user's home directory.
1421Most flags are ignored to fake compatibility with other sendmail
1422implementations. A single recipient or the -t flag with a To-header is required.
1423With the -t flag, Cc and Bcc headers are not handled specially, so Bcc is not
1424removed and the addresses do not receive the email.
1426/etc/moxsubmit.conf should be group-readable and not readable by others and this
1427binary should be setgid that group:
1430 install -m 2755 -o root -g moxsubmit mox /usr/sbin/sendmail
1431 touch /etc/moxsubmit.conf
1432 chown root:moxsubmit /etc/moxsubmit.conf
1433 chmod 640 /etc/moxsubmit.conf
1434 # edit /etc/moxsubmit.conf
1437 usage: mox sendmail [-Fname] [ignoredflags] [-t] [<message]
1441Check the status of IP for the policy published in DNS for the domain.
1443IPs may be allowed to send for a domain, or disallowed, and several shades in
1444between. If not allowed, an explanation may be provided by the policy. If so,
1445the explanation is printed. The SPF mechanism that matched (if any) is also
1448 usage: mox spf check domain ip
1452Lookup the SPF record for the domain and print it.
1454 usage: mox spf lookup domain
1458Parse the record as SPF record. If valid, nothing is printed.
1460 usage: mox spf parse txtrecord
1464Lookup the TLSRPT record for the domain.
1466A TLSRPT record typically contains an email address where reports about TLS
1467connectivity should be sent. Mail servers attempting delivery to our domain
1468should attempt to use TLS. TLSRPT lets them report how many connection
1469successfully used TLS, and how what kind of errors occurred otherwise.
1471 usage: mox tlsrpt lookup domain
1473# mox tlsrpt parsereportmsg
1475Parse and print the TLSRPT in the message.
1477The report is printed in formatted JSON.
1479 usage: mox tlsrpt parsereportmsg message ...
1483Prints this mox version.
1489Lists available methods, prints request/response parameters for method, or calls a method with a request read from standard input.
1491 usage: mox webapi [method [baseurl-with-credentials]
1495List available examples, or print a specific example.
1497 usage: mox example [name]
1499# mox bumpuidvalidity
1501Change the IMAP UID validity of the mailbox, causing IMAP clients to refetch messages.
1503This can be useful after manually repairing metadata about the account/mailbox.
1505Opens account database file directly. Ensure mox does not have the account
1506open, or is not running.
1508 usage: mox bumpuidvalidity account [mailbox]
1512Reassign UIDs in one mailbox or all mailboxes in an account and bump UID validity, causing IMAP clients to refetch messages.
1514Opens account database file directly. Ensure mox does not have the account
1515open, or is not running.
1517 usage: mox reassignuids account [mailboxid]
1521Fix inconsistent UIDVALIDITY and UIDNEXT in messages/mailboxes/account.
1523The next UID to use for a message in a mailbox should always be higher than any
1524existing message UID in the mailbox. If it is not, the mailbox UIDNEXT is
1527Each mailbox has a UIDVALIDITY sequence number, which should always be lower
1528than the per-account next UIDVALIDITY to use. If it is not, the account next
1529UIDVALIDITY is updated.
1531Opens account database file directly. Ensure mox does not have the account
1532open, or is not running.
1534 usage: mox fixuidmeta account
1538Ensure message sizes in the database matching the sum of the message prefix length and on-disk file size.
1540Messages with an inconsistent size are also parsed again.
1542If an inconsistency is found, you should probably also run "mox
1543bumpuidvalidity" on the mailboxes or entire account to force IMAP clients to
1546 usage: mox fixmsgsize [account]
1550Parse all messages in the account or all accounts again.
1552Can be useful after upgrading mox with improved message parsing. Messages are
1553parsed in batches, so other access to the mailboxes/messages are not blocked
1554while reparsing all messages.
1556 usage: mox reparse [account]
1560Ensure messages in the database have a pre-parsed MIME form in the database.
1562 usage: mox ensureparsed account
1564 store new parsed message for all messages
1566# mox recalculatemailboxcounts
1568Recalculate message counts for all mailboxes in the account, and total message size for quota.
1570When a message is added to/removed from a mailbox, or when message flags change,
1571the total, unread, unseen and deleted messages are accounted, the total size of
1572the mailbox, and the total message size for the account. In case of a bug in
1573this accounting, the numbers could become incorrect. This command will find, fix
1576 usage: mox recalculatemailboxcounts account
1580Parse message, print JSON representation.
1582 usage: mox message parse message.eml
1584 check if message needs smtputf8
1586# mox reassignthreads
1588Reassign message threads.
1590For all accounts, or optionally only the specified account.
1592Threading for all messages in an account is first reset, and new base subject
1593and normalized message-id saved with the message. Then all messages are
1594evaluated and matched against their parents/ancestors.
1596Messages are matched based on the References header, with a fall-back to an
1597In-Reply-To header, and if neither is present/valid, based only on base
1600A References header typically points to multiple previous messages in a
1601hierarchy. From oldest ancestor to most recent parent. An In-Reply-To header
1602would have only a message-id of the parent message.
1604A message is only linked to a parent/ancestor if their base subject is the
1605same. This ensures unrelated replies, with a new subject, are placed in their
1608The base subject is lower cased, has whitespace collapsed to a single
1609space, and some components removed: leading "Re:", "Fwd:", "Fw:", or bracketed
1610tag (that mailing lists often add, e.g. "[listname]"), trailing "(fwd)", or
1611enclosing "[fwd: ...]".
1613Messages are linked to all their ancestors. If an intermediate parent/ancestor
1614message is deleted in the future, the message can still be linked to the earlier
1615ancestors. If the direct parent already wasn't available while matching, this is
1616stored as the message having a "missing link" to its stored ancestors.
1618 usage: mox reassignthreads [account]
1622// NOTE: DO NOT EDIT, this file is generated by gendoc.sh.