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
61 mox config dnscheck domain
62 mox config dnsrecords domain
63 mox config describe-domains >domains.conf
64 mox config describe-static >mox.conf
65 mox config account add account address
66 mox config account rm account
67 mox config address add address account
68 mox config address rm address
69 mox config domain add domain account [localpart]
70 mox config domain rm domain
71 mox config alias list domain
72 mox config alias print alias
73 mox config alias add alias@domain rcpt1@domain ...
74 mox config alias update alias@domain [-postpublic false|true -listmembers false|true -allowmsgfrom false|true]
75 mox config alias rm alias@domain
76 mox config alias addaddr alias@domain rcpt1@domain ...
77 mox config alias rmaddr alias@domain rcpt1@domain ...
78 mox config describe-sendmail >/etc/moxsubmit.conf
79 mox config printservice >mox.service
80 mox config ensureacmehostprivatekeys
81 mox config example [name]
84 mox clientconfig domain
85 mox dane dial host:port
86 mox dane dialmx domain [destination-host]
87 mox dane makerecord usage selector matchtype [certificate.pem | publickey.pem | privatekey.pem]
88 mox dns lookup [ptr | mx | cname | ips | a | aaaa | ns | txt | srv | tlsa] name
89 mox dkim gened25519 >$selector._domainkey.$domain.ed25519.privatekey.pkcs8.pem
90 mox dkim genrsa >$selector._domainkey.$domain.rsa2048.privatekey.pkcs8.pem
91 mox dkim lookup selector domain
92 mox dkim txt <$selector._domainkey.$domain.key.pkcs8.pem
93 mox dkim verify message
95 mox dmarc lookup domain
96 mox dmarc parsereportmsg message ...
97 mox dmarc verify remoteip mailfromaddress helodomain < message
98 mox dmarc checkreportaddrs domain
99 mox dnsbl check zone ip
100 mox dnsbl checkhealth zone
101 mox mtasts lookup domain
102 mox retrain accountname
103 mox sendmail [-Fname] [ignoredflags] [-t] [<message]
104 mox spf check domain ip
105 mox spf lookup domain
106 mox spf parse txtrecord
107 mox tlsrpt lookup domain
108 mox tlsrpt parsereportmsg message ...
110 mox webapi [method [baseurl-with-credentials]
112 mox bumpuidvalidity account [mailbox]
113 mox reassignuids account [mailboxid]
114 mox fixuidmeta account
115 mox fixmsgsize [account]
116 mox reparse [account]
117 mox ensureparsed account
118 mox recalculatemailboxcounts account
119 mox message parse message.eml
120 mox reassignthreads [account]
124Start mox, serving SMTP/IMAP/HTTPS.
126Incoming email is accepted over SMTP. Email can be retrieved by users using
127IMAP. HTTP listeners are started for the admin/account web interfaces, and for
128automated TLS configuration. Missing essential TLS certificates are immediately
129requested, other TLS certificates are requested on demand.
131Only implemented on unix systems, not Windows.
137Quickstart generates configuration files and prints instructions to quickly set up a mox instance.
139Quickstart writes configuration files, prints initial admin and account
140passwords, DNS records you should create. If you run it on Linux it writes a
141systemd service file and prints commands to enable and start mox as service.
143The user or uid is optional, defaults to "mox", and is the user or uid/gid mox
144will run as after initialization.
146Quickstart assumes mox will run on the machine you run quickstart on and uses
147its host name and public IPs. On many systems the hostname is not a fully
148qualified domain name, but only the first dns "label", e.g. "mail" in case of
149"mail.example.org". If so, quickstart does a reverse DNS lookup to find the
150hostname, and as fallback uses the label plus the domain of the email address
151you specified. Use flag -hostname to explicitly specify the hostname mox will
154Mox is by far easiest to operate if you let it listen on port 443 (HTTPS) and
15580 (HTTP). TLS will be fully automatic with ACME with Let's Encrypt.
157You can run mox along with an existing webserver, but because of MTA-STS and
158autoconfig, you'll need to forward HTTPS traffic for two domains to mox. Run
159"mox quickstart -existing-webserver ..." to generate configuration files and
160instructions for configuring mox along with an existing webserver.
162But please first consider configuring mox on port 443. It can itself serve
163domains with HTTP/HTTPS, including with automatic TLS with ACME, is easily
164configured through both configuration files and admin web interface, and can act
165as a reverse proxy (and static file server for that matter), so you can forward
166traffic to your existing backend applications. Look for "WebHandlers:" in the
167output of "mox config describe-domains" and see the output of
168"mox config example webhandlers".
170 usage: mox quickstart [-skipdial] [-existing-webserver] [-hostname host] user@domain [user | uid]
172 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.
174 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
176 skip check for outgoing smtp (port 25) connectivity
180Shut mox down, giving connections maximum 3 seconds to stop before closing them.
182While shutting down, new IMAP and SMTP connections will get a status response
183indicating temporary unavailability. Existing connections will get a 3 second
184period to finish their transaction and shut down. Under normal circumstances,
185only IMAP has long-living connections, with the IDLE command to get notified of
190# mox setaccountpassword
192Set new password an account.
194The password is read from stdin. Secrets derived from the password, but not the
195password itself, are stored in the account database. The stored secrets are for
196authentication with: scram-sha-256, scram-sha-1, cram-md5, plain text (bcrypt
199The parameter is an account name, as configured under Accounts in domains.conf
200and as present in the data/accounts/ directory, not a configured email address
203 usage: mox setaccountpassword account
205# mox setadminpassword
207Set a new admin password, for the web interface.
209The password is read from stdin. Its bcrypt hash is stored in a file named
210"adminpasswd" in the configuration directory.
212 usage: mox setadminpassword
216Print the log levels, or set a new default log level, or a level for the given package.
218By default, a single log level applies to all logging in mox. But for each
219"pkg", an overriding log level can be configured. Examples of packages:
220smtpserver, smtpclient, queue, imapserver, spf, dkim, dmarc, junk, message,
223Specify a pkg and an empty level to clear the configured level for a package.
225Valid labels: error, info, debug, trace, traceauth, tracedata.
227 usage: mox loglevels [level [pkg]]
229# mox queue holdrules list
231List hold rules for the delivery queue.
233Messages submitted to the queue that match a hold rule will be marked as on hold
234and not scheduled for delivery.
236 usage: mox queue holdrules list
238# mox queue holdrules add
240Add hold rule for the delivery queue.
242Add a hold rule to mark matching newly submitted messages as on hold. Set the
243matching rules with the flags. Don't specify any flags to match all submitted
246 usage: mox queue holdrules add [ruleflags]
248 account submitting the message
254# mox queue holdrules remove
256Remove hold rule for the delivery queue.
258Remove a hold rule by its id.
260 usage: mox queue holdrules remove ruleid
264List matching messages in the delivery queue.
266Prints the message with its ID, last and next delivery attempts, last error.
268 usage: mox queue list [filtersortflags]
270 account that queued the message
272 sort ascending instead of descending (default)
274 from address of message, use "@example.com" to match all messages for a domain
276 true or false, whether to match only messages that are (not) on hold
278 comma-separated list of message IDs
280 number of messages to return
282 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
284 field to sort by, "nextattempt" (default) or "queued"
286 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
288 recipient address of message, use "@example.com" to match all messages for a domain
290 transport to use for messages, empty string sets the default behaviour
294Mark matching messages on hold.
296Messages that are on hold are not delivered until marked as off hold again, or
297otherwise handled by the admin.
299 usage: mox queue hold [filterflags]
301 account that queued the message
303 from address of message, use "@example.com" to match all messages for a domain
305 true or false, whether to match only messages that are (not) on hold
307 comma-separated list of message IDs
309 number of messages to return
311 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
313 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
315 recipient address of message, use "@example.com" to match all messages for a domain
317 transport to use for messages, empty string sets the default behaviour
321Mark matching messages off hold.
323Once off hold, messages can be delivered according to their current next
324delivery attempt. See the "queue schedule" command.
326 usage: mox queue unhold [filterflags]
328 account that queued the message
330 from address of message, use "@example.com" to match all messages for a domain
332 true or false, whether to match only messages that are (not) on hold
334 comma-separated list of message IDs
336 number of messages to return
338 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
340 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
342 recipient address of message, use "@example.com" to match all messages for a domain
344 transport to use for messages, empty string sets the default behaviour
348Change next delivery attempt for matching messages.
350The next delivery attempt is adjusted by the duration parameter. If the -now
351flag is set, the new delivery attempt is set to the duration added to the
352current time, instead of added to the current scheduled time.
354Schedule immediate delivery with "mox queue schedule -now 0".
356 usage: mox queue schedule [filterflags] [-now] duration
358 account that queued the message
360 from address of message, use "@example.com" to match all messages for a domain
362 true or false, whether to match only messages that are (not) on hold
364 comma-separated list of message IDs
366 number of messages to return
368 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
370 schedule for duration relative to current time instead of relative to current next delivery attempt for messages
372 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
374 recipient address of message, use "@example.com" to match all messages for a domain
376 transport to use for messages, empty string sets the default behaviour
380Set transport for matching messages.
382By default, the routing rules determine how a message is delivered. The default
383and common case is direct delivery with SMTP. Messages can get a previously
384configured transport assigned to use for delivery, e.g. using submission to
385another mail server or with connections over a SOCKS proxy.
387 usage: mox queue transport [filterflags] transport
389 account that queued the message
391 from address of message, use "@example.com" to match all messages for a domain
393 true or false, whether to match only messages that are (not) on hold
395 comma-separated list of message IDs
397 number of messages to return
399 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
401 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
403 recipient address of message, use "@example.com" to match all messages for a domain
405 transport to use for messages, empty string sets the default behaviour
407# mox queue requiretls
409Set TLS requirements for delivery of matching messages.
411Value "yes" is handled as if the RequireTLS extension was specified during
414Value "no" is handled as if the message has a header "TLS-Required: No". This
415header is not added by the queue. If messages without this header are relayed
416through other mail servers they will apply their own default TLS policy.
418Value "default" is the default behaviour, currently for unverified opportunistic
421 usage: mox queue requiretls [filterflags] {yes | no | default}
423 account that queued the message
425 from address of message, use "@example.com" to match all messages for a domain
427 true or false, whether to match only messages that are (not) on hold
429 comma-separated list of message IDs
431 number of messages to return
433 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
435 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
437 recipient address of message, use "@example.com" to match all messages for a domain
439 transport to use for messages, empty string sets the default behaviour
443Fail delivery of matching messages, delivering DSNs.
445Failing a message is handled similar to how delivery is given up after all
446delivery attempts failed. The DSN (delivery status notification) message
447contains a line saying the message was canceled by the admin.
449 usage: mox queue fail [filterflags]
451 account that queued the message
453 from address of message, use "@example.com" to match all messages for a domain
455 true or false, whether to match only messages that are (not) on hold
457 comma-separated list of message IDs
459 number of messages to return
461 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
463 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
465 recipient address of message, use "@example.com" to match all messages for a domain
467 transport to use for messages, empty string sets the default behaviour
471Remove matching messages from the queue.
473Dangerous operation, this completely removes the message. If you want to store
474the message, use "queue dump" before removing.
476 usage: mox queue drop [filterflags]
478 account that queued the message
480 from address of message, use "@example.com" to match all messages for a domain
482 true or false, whether to match only messages that are (not) on hold
484 comma-separated list of message IDs
486 number of messages to return
488 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
490 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
492 recipient address of message, use "@example.com" to match all messages for a domain
494 transport to use for messages, empty string sets the default behaviour
498Dump a message from the queue.
500The message is printed to stdout and is in standard internet mail format.
502 usage: mox queue dump id
504# mox queue retired list
506List matching messages in the retired queue.
508Prints messages with their ID and results.
510 usage: mox queue retired list [filtersortflags]
512 account that queued the message
514 sort ascending instead of descending (default)
516 from address of message, use "@example.com" to match all messages for a domain
518 comma-separated list of retired message IDs
520 filter by time of last activity relative to now, value must start with "<" (before now) or ">" (after now)
522 number of messages to return
524 "success" or "failure" as result of delivery
526 field to sort by, "lastactivity" (default) or "queued"
528 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
530 recipient address of message, use "@example.com" to match all messages for a domain
532 transport to use for messages, empty string sets the default behaviour
534# mox queue retired print
536Print a message from the retired queue.
538Prints a JSON representation of the information from the retired queue.
540 usage: mox queue retired print id
542# mox queue suppress list
544Print addresses in suppression list.
546 usage: mox queue suppress list [-account account]
548 only show suppression list for this account
550# mox queue suppress add
552Add address to suppression list for account.
554 usage: mox queue suppress add account address
556# mox queue suppress remove
558Remove address from suppression list for account.
560 usage: mox queue suppress remove account address
562# mox queue suppress lookup
564Check if address is present in suppression list, for any or specific account.
566 usage: mox queue suppress lookup [-account account] address
568 only check address in specified account
570# mox queue webhook list
572List matching webhooks in the queue.
574Prints list of webhooks, their IDs and basic information.
576 usage: mox queue webhook list [filtersortflags]
578 account that queued the message/webhook
580 sort ascending instead of descending (default)
582 event this webhook is about: incoming, delivered, suppressed, delayed, failed, relayed, expanded, canceled, unrecognized
584 comma-separated list of webhook IDs
586 number of webhooks to return
588 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
590 field to sort by, "nextattempt" (default) or "queued"
592 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
594# mox queue webhook schedule
596Change next delivery attempt for matching webhooks.
598The next delivery attempt is adjusted by the duration parameter. If the -now
599flag is set, the new delivery attempt is set to the duration added to the
600current time, instead of added to the current scheduled time.
602Schedule immediate delivery with "mox queue schedule -now 0".
604 usage: mox queue webhook schedule [filterflags] duration
606 account that queued the message/webhook
608 event this webhook is about: incoming, delivered, suppressed, delayed, failed, relayed, expanded, canceled, unrecognized
610 comma-separated list of webhook IDs
612 number of webhooks to return
614 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
616 schedule for duration relative to current time instead of relative to current next delivery attempt for webhooks
618 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
620# mox queue webhook cancel
622Fail delivery of matching webhooks.
624 usage: mox queue webhook cancel [filterflags]
626 account that queued the message/webhook
628 event this webhook is about: incoming, delivered, suppressed, delayed, failed, relayed, expanded, canceled, unrecognized
630 comma-separated list of webhook IDs
632 number of webhooks to return
634 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
636 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
638# mox queue webhook print
640Print details of a webhook from the queue.
642The webhook is printed to stdout as JSON.
644 usage: mox queue webhook print id
646# mox queue webhook retired list
648List matching webhooks in the retired queue.
650Prints list of retired webhooks, their IDs and basic information.
652 usage: mox queue webhook retired list [filtersortflags]
654 account that queued the message/webhook
656 sort ascending instead of descending (default)
658 event this webhook is about: incoming, delivered, suppressed, delayed, failed, relayed, expanded, canceled, unrecognized
660 comma-separated list of retired webhook IDs
662 filter by time of last activity relative to now, value must start with "<" (before now) or ">" (after now)
664 number of webhooks to return
666 field to sort by, "lastactivity" (default) or "queued"
668 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
670# mox queue webhook retired print
672Print details of a webhook from the retired queue.
674The retired webhook is printed to stdout as JSON.
676 usage: mox queue webhook retired print id
680Import a maildir into an account.
682The mbox/maildir archive is accessed and imported by the running mox process, so
683it must have access to the archive files. The default suggested systemd service
684file isolates mox from most of the file system, with only the "data/" directory
685accessible, so you may want to put the mbox/maildir archive files in a
686directory like "data/import/" to make it available to mox.
688By default, messages will train the junk filter based on their flags and, if
689"automatic junk flags" configuration is set, based on mailbox naming.
691If the destination mailbox is the Sent mailbox, the recipients of the messages
692are added to the message metadata, causing later incoming messages from these
693recipients to be accepted, unless other reputation signals prevent that.
695Users can also import mailboxes/messages through the account web page by
696uploading a zip or tgz file with mbox and/or maildirs.
698Messages are imported even if already present. Importing messages twice will
699result in duplicate messages.
701Mailbox flags, like "seen", "answered", will be imported. An optional
702dovecot-keywords file can specify additional flags, like Forwarded/Junk/NotJunk.
704 usage: mox import maildir accountname mailboxname maildir
708Import an mbox into an account.
710Using mbox is not recommended, maildir is a better defined format.
712The mbox/maildir archive is accessed and imported by the running mox process, so
713it must have access to the archive files. The default suggested systemd service
714file isolates mox from most of the file system, with only the "data/" directory
715accessible, so you may want to put the mbox/maildir archive files in a
716directory like "data/import/" to make it available to mox.
718By default, messages will train the junk filter based on their flags and, if
719"automatic junk flags" configuration is set, based on mailbox naming.
721If the destination mailbox is the Sent mailbox, the recipients of the messages
722are added to the message metadata, causing later incoming messages from these
723recipients to be accepted, unless other reputation signals prevent that.
725Users can also import mailboxes/messages through the account web page by
726uploading a zip or tgz file with mbox and/or maildirs.
728Messages are imported even if already present. Importing messages twice will
729result in duplicate messages.
731 usage: mox import mbox accountname mailboxname mbox
735Export one or all mailboxes from an account in maildir format.
737Export bypasses a running mox instance. It opens the account mailbox/message
738database file directly. This may block if a running mox instance also has the
739database open, e.g. for IMAP connections. To export from a running instance, use
740the accounts web page or webmail.
742 usage: mox export maildir [-single] dst-dir account-path [mailbox]
744 export single mailbox, without any children. disabled if mailbox isn't specified.
748Export messages from one or all mailboxes in an account in mbox format.
750Using mbox is not recommended. Maildir is a better format.
752Export bypasses a running mox instance. It opens the account mailbox/message
753database file directly. This may block if a running mox instance also has the
754database open, e.g. for IMAP connections. To export from a running instance, use
755the accounts web page or webmail.
757For mbox export, "mboxrd" is used where message lines starting with the magic
758"From " string are escaped by prepending a >. All ">*From " are escaped,
759otherwise reconstructing the original could lose a ">".
761 usage: mox export mbox [-single] dst-dir account-path [mailbox]
763 export single mailbox, without any children. disabled if mailbox isn't specified.
767Start a local SMTP/IMAP server that accepts all messages, useful when testing/developing software that sends email.
769Localserve starts mox with a configuration suitable for local email-related
770software development/testing. It listens for SMTP/Submission(s), IMAP(s) and
771HTTP(s), on the regular port numbers + 1000.
773Data is stored in the system user's configuration directory under
774"mox-localserve", e.g. $HOME/.config/mox-localserve/ on linux, but can be
775overridden with the -dir flag. If the directory does not yet exist, it is
776automatically initialized with configuration files, an account with email
777address mox@localhost and password moxmoxmox, and a newly generated self-signed
780Incoming messages are delivered as normal, falling back to accepting and
781delivering to the mox account for unknown addresses.
782Submitted messages are added to the queue, which delivers by ignoring the
783destination servers, always connecting to itself instead.
785Recipient addresses with the following localpart suffixes are handled specially:
787- "temperror": fail with a temporary error code
788- "permerror": fail with a permanent error code
789- [45][0-9][0-9]: fail with the specific error code
790- "timeout": no response (for an hour)
792If the localpart begins with "mailfrom" or "rcptto", the error is returned
793during those commands instead of during "data".
795 usage: mox localserve
797 configuration storage directory (default "$userconfigdir/mox-localserve")
799 write configuration files and exit
801 serve on this ip instead of default 127.0.0.1 and ::1. only used when writing configuration, at first launch.
805Prints help about matching commands.
807If multiple commands match, they are listed along with the first line of their help text.
808If a single command matches, its usage and full help text is printed.
810 usage: mox help [command ...]
814Creates a backup of the data directory.
816Backup creates consistent snapshots of the databases and message files and
817copies other files in the data directory. Empty directories are not copied.
818These files can then be stored elsewhere for long-term storage, or used to fall
819back to should an upgrade fail. Simply copying files in the data directory
820while mox is running can result in unusable database files.
822Message files never change (they are read-only, though can be removed) and are
823hard-linked so they don't consume additional space. If hardlinking fails, for
824example when the backup destination directory is on a different file system, a
825regular copy is made. Using a destination directory like "data/tmp/backup"
826increases the odds hardlinking succeeds: the default systemd service file
827specifically mounts the data directory, causing attempts to hardlink outside it
828to fail with an error about cross-device linking.
830All files in the data directory that aren't recognized (i.e. other than known
831database files, message files, an acme directory, the "tmp" directory, etc),
832are stored, but with a warning.
834Remove files in the destination directory before doing another backup. The
835backup command will not overwrite files, but print and return errors.
837Exit code 0 indicates the backup was successful. A clean successful backup does
838not print any output, but may print warnings. Use the -verbose flag for
839details, including timing.
841To restore a backup, first shut down mox, move away the old data directory and
842move an earlier backed up directory in its place, run "mox verifydata",
843possibly with the "-fix" option, and restart mox. After the restore, you may
844also want to run "mox bumpuidvalidity" for each account for which messages in a
845mailbox changed, to force IMAP clients to synchronize mailbox state.
847Before upgrading, to check if the upgrade will likely succeed, first make a
848backup, then use the new mox binary to run "mox verifydata" on the backup. This
849can change the backup files (e.g. upgrade database files, move away
850unrecognized message files), so you should make a new backup before actually
853 usage: mox backup dest-dir
859Verify the contents of a data directory, typically of a backup.
861Verifydata checks all database files to see if they are valid BoltDB/bstore
862databases. It checks that all messages in the database have a corresponding
863on-disk message file and there are no unrecognized files. If option -fix is
864specified, unrecognized message files are moved away. This may be needed after
865a restore, because messages enqueued or delivered in the future may get those
866message sequence numbers assigned and writing the message file would fail.
867Consistency of message/mailbox UID, UIDNEXT and UIDVALIDITY is verified as
870Because verifydata opens the database files, schema upgrades may automatically
871be applied. This can happen if you use a new mox release. It is useful to run
872"mox verifydata" with a new binary before attempting an upgrade, but only on a
873copy of the database files, as made with "mox backup". Before upgrading, make a
874new backup again since "mox verifydata" may have upgraded the database files,
875possibly making them potentially no longer readable by the previous version.
877 usage: mox verifydata data-dir
879 fix fixable problems, such as moving away message files not referenced by their database
881 skip the check for message size
885Parses and validates the configuration files.
887If valid, the command exits with status 0. If not valid, all errors encountered
890 usage: mox config test
894Check the DNS records with the configuration for the domain, and print any errors/warnings.
896 usage: mox config dnscheck domain
898# mox config dnsrecords
900Prints annotated DNS records as zone file that should be created for the domain.
902The zone file can be imported into existing DNS software. You should review the
903DNS records, especially if your domain previously/currently has email
906 usage: mox config dnsrecords domain
908# mox config describe-domains
910Prints an annotated empty configuration for use as domains.conf.
912The domains configuration file contains the domains and their configuration,
913and accounts and their configuration. This includes the configured email
914addresses. The mox admin web interface, and the mox command line interface, can
915make changes to this file. Mox automatically reloads this file when it changes.
917Like the static configuration, the example domains.conf printed by this command
918needs modifications to make it valid.
920 usage: mox config describe-domains >domains.conf
922# mox config describe-static
924Prints an annotated empty configuration for use as mox.conf.
926The static configuration file cannot be reloaded while mox is running. Mox has
927to be restarted for changes to the static configuration file to take effect.
929This configuration file needs modifications to make it valid. For example, it
930may contain unfinished list items.
932 usage: mox config describe-static >mox.conf
934# mox config account add
936Add an account with an email address and reload the configuration.
938Email can be delivered to this address/account. A password has to be configured
939explicitly, see the setaccountpassword command.
941 usage: mox config account add account address
943# mox config account rm
945Remove an account and reload the configuration.
947Email addresses for this account will also be removed, and incoming email for
948these addresses will be rejected.
950All data for the account will be removed.
952 usage: mox config account rm account
954# mox config address add
956Adds an address to an account and reloads the configuration.
958If address starts with a @ (i.e. a missing localpart), this is a catchall
959address for the domain.
961 usage: mox config address add address account
963# mox config address rm
965Remove an address and reload the configuration.
967Incoming email for this address will be rejected after removing an address.
969 usage: mox config address rm address
971# mox config domain add
973Adds a new domain to the configuration and reloads the configuration.
975The account is used for the postmaster mailboxes the domain, including as DMARC and
976TLS reporting. Localpart is the "username" at the domain for this account. If
977must be set if and only if account does not yet exist.
979 usage: mox config domain add domain account [localpart]
981# mox config domain rm
983Remove a domain from the configuration and reload the configuration.
985This is a dangerous operation. Incoming email delivery for this domain will be
988 usage: mox config domain rm domain
990# mox config alias list
992List aliases for domain.
994 usage: mox config alias list domain
996# mox config alias print
998Print settings and members of alias.
1000 usage: mox config alias print alias
1002# mox config alias add
1004Add new alias with one or more addresses.
1006 usage: mox config alias add alias@domain rcpt1@domain ...
1008# mox config alias update
1010Update alias configuration.
1012 usage: mox config alias update alias@domain [-postpublic false|true -listmembers false|true -allowmsgfrom false|true]
1013 -allowmsgfrom string
1014 whether alias address can be used in message from header
1016 whether list members can list members
1018 whether anyone or only list members can post
1020# mox config alias rm
1024 usage: mox config alias rm alias@domain
1026# mox config alias addaddr
1028Add addresses to alias.
1030 usage: mox config alias addaddr alias@domain rcpt1@domain ...
1032# mox config alias rmaddr
1034Remove addresses from alias.
1036 usage: mox config alias rmaddr alias@domain rcpt1@domain ...
1038# mox config describe-sendmail
1040Describe configuration for mox when invoked as sendmail.
1042 usage: mox config describe-sendmail >/etc/moxsubmit.conf
1044# mox config printservice
1046Prints a systemd unit service file for mox.
1048This is the same file as generated using quickstart. If the systemd service file
1049has changed with a newer version of mox, use this command to generate an up to
1052 usage: mox config printservice >mox.service
1054# mox config ensureacmehostprivatekeys
1056Ensure host private keys exist for TLS listeners with ACME.
1058In mox.conf, each listener can have TLS configured. Long-lived private key files
1059can be specified, which will be used when requesting ACME certificates.
1060Configuring these private keys makes it feasible to publish DANE TLSA records
1061for the corresponding public keys in DNS, protected with DNSSEC, allowing TLS
1062certificate verification without depending on a list of Certificate Authorities
1063(CAs). Previous versions of mox did not pre-generate private keys for use with
1064ACME certificates, but would generate private keys on-demand. By explicitly
1065configuring private keys, they will not change automatedly with new
1066certificates, and the DNS TLSA records stay valid.
1068This command looks for listeners in mox.conf with TLS with ACME configured. For
1069each missing host private key (of type rsa-2048 and ecdsa-p256) a key is written
1070to config/hostkeys/. If a certificate exists in the ACME "cache", its private
1071key is copied. Otherwise a new private key is generated. Snippets for manually
1072updating/editing mox.conf are printed.
1074After running this command, and updating mox.conf, run "mox config dnsrecords"
1075for a domain and create the TLSA DNS records it suggests to enable DANE.
1077 usage: mox config ensureacmehostprivatekeys
1081List available config examples, or print a specific example.
1083 usage: mox config example [name]
1087Check if a newer version of mox is available.
1089A single DNS TXT lookup to _updates.xmox.nl tells if a new version is
1090available. If so, a changelog is fetched from https://updates.xmox.nl, and the
1091individual entries verified with a builtin public key. The changelog is
1094 usage: mox checkupdate
1098Turn an ID from a Received header into a cid, for looking up in logs.
1100A cid is essentially a connection counter initialized when mox starts. Each log
1101line contains a cid. Received headers added by mox contain a unique ID that can
1102be decrypted to a cid by admin of a mox instance only.
1108Print the configuration for email clients for a domain.
1110Sending email is typically not done on the SMTP port 25, but on submission
1111ports 465 (with TLS) and 587 (without initial TLS, but usually added to the
1112connection with STARTTLS). For IMAP, the port with TLS is 993 and without is
1115Without TLS/STARTTLS, passwords are sent in clear text, which should only be
1116configured over otherwise secured connections, like a VPN.
1118 usage: mox clientconfig domain
1122Dial the address using TLS with certificate verification using DANE.
1124Data is copied between connection and stdin/stdout until either side closes the
1127 usage: mox dane dial host:port
1129 allowed usages for dane, comma-separated list (default "pkix-ta,pkix-ee,dane-ta,dane-ee")
1133Connect to MX server for domain using STARTTLS verified with DANE.
1135If no destination host is specified, regular delivery logic is used to find the
1136hosts to attempt delivery too. This involves following CNAMEs for the domain,
1137looking up MX records, and possibly falling back to the domain name itself as
1140If a destination host is specified, that is the only candidate host considered
1143With a list of destinations gathered, each is dialed until a successful SMTP
1144session verified with DANE has been initialized, including EHLO and STARTTLS
1147Once connected, data is copied between connection and stdin/stdout, until
1148either side closes the connection.
1150This command follows the same logic as delivery attempts made from the queue,
1151sharing most of its code.
1153 usage: mox dane dialmx domain [destination-host]
1154 -ehlohostname string
1155 hostname to send in smtp ehlo command (default "localhost")
1157# mox dane makerecord
1159Print TLSA record for given certificate/key and parameters.
1162- usage: pkix-ta (0), pkix-ee (1), dane-ta (2), dane-ee (3)
1163- selector: cert (0), spki (1)
1164- matchtype: full (0), sha2-256 (1), sha2-512 (2)
1166Common DANE TLSA record parameters are: dane-ee spki sha2-256, or 3 1 1,
1167followed by a sha2-256 hash of the DER-encoded "SPKI" (subject public key info)
1168from the certificate. An example DNS zone file entry:
1170 _25._tcp.example.com. TLSA 3 1 1 133b919c9d65d8b1488157315327334ead8d83372db57465ecabf53ee5748aee
1172The first usable information from the pem file is used to compose the TLSA
1173record. In case of selector "cert", a certificate is required. Otherwise the
1174"subject public key info" (spki) of the first certificate or public or private
1175key (pkcs#8, pkcs#1 or ec private key) is used.
1177 usage: mox dane makerecord usage selector matchtype [certificate.pem | publickey.pem | privatekey.pem]
1181Lookup DNS name of given type.
1183Lookup always prints whether the response was DNSSEC-protected.
1187mox dns lookup ptr 1.1.1.1
1188mox dns lookup mx xmox.nl
1189mox dns lookup txt _dmarc.xmox.nl.
1190mox dns lookup tlsa _25._tcp.xmox.nl
1192 usage: mox dns lookup [ptr | mx | cname | ips | a | aaaa | ns | txt | srv | tlsa] name
1194# mox dkim gened25519
1196Generate a new ed25519 key for use with DKIM.
1198Ed25519 keys are much smaller than RSA keys of comparable cryptographic
1199strength. This is convenient because of maximum DNS message sizes. At the time
1200of writing, not many mail servers appear to support ed25519 DKIM keys though,
1201so it is recommended to sign messages with both RSA and ed25519 keys.
1203 usage: mox dkim gened25519 >$selector._domainkey.$domain.ed25519.privatekey.pkcs8.pem
1207Generate a new 2048 bit RSA private key for use with DKIM.
1209The generated file is in PEM format, and has a comment it is generated for use
1212 usage: mox dkim genrsa >$selector._domainkey.$domain.rsa2048.privatekey.pkcs8.pem
1216Lookup and print the DKIM record for the selector at the domain.
1218 usage: mox dkim lookup selector domain
1222Print a DKIM DNS TXT record with the public key derived from the private key read from stdin.
1224The DNS should be configured as a TXT record at $selector._domainkey.$domain.
1226 usage: mox dkim txt <$selector._domainkey.$domain.key.pkcs8.pem
1230Verify the DKIM signatures in a message and print the results.
1232The message is parsed, and the DKIM-Signature headers are validated. Validation
1233of older messages may fail because the DNS records have been removed or changed
1234by now, or because the signature header may have specified an expiration time
1237 usage: mox dkim verify message
1241Sign a message, adding DKIM-Signature headers based on the domain in the From header.
1243The message is parsed, the domain looked up in the configuration files, and
1244DKIM-Signature headers generated. The message is printed with the DKIM-Signature
1247 usage: mox dkim sign message
1251Lookup dmarc policy for domain, a DNS TXT record at _dmarc.<domain>, validate and print it.
1253 usage: mox dmarc lookup domain
1255# mox dmarc parsereportmsg
1257Parse a DMARC report from an email message, and print its extracted details.
1259DMARC reports are periodically mailed, if requested in the DMARC DNS record of
1260a domain. Reports are sent by mail servers that received messages with our
1261domain in a From header. This may or may not be legatimate email. DMARC reports
1262contain summaries of evaluations of DMARC and DKIM/SPF, which can help
1263understand email deliverability problems.
1265 usage: mox dmarc parsereportmsg message ...
1269Parse an email message and evaluate it against the DMARC policy of the domain in the From-header.
1271mailfromaddress and helodomain are used for SPF validation. If both are empty,
1272SPF validation is skipped.
1274mailfromaddress should be the address used as MAIL FROM in the SMTP session.
1275For DSN messages, that address may be empty. The helo domain was specified at
1276the beginning of the SMTP transaction that delivered the message. These values
1277can be found in message headers.
1279 usage: mox dmarc verify remoteip mailfromaddress helodomain < message
1281# mox dmarc checkreportaddrs
1283For each reporting address in the domain's DMARC record, check if it has opted into receiving reports (if needed).
1285A DMARC record can request reports about DMARC evaluations to be sent to an
1286email/http address. If the organizational domains of that of the DMARC record
1287and that of the report destination address do not match, the destination
1288address must opt-in to receiving DMARC reports by creating a DMARC record at
1289<dmarcdomain>._report._dmarc.<reportdestdomain>.
1291 usage: mox dmarc checkreportaddrs domain
1295Test if IP is in the DNS blocklist of the zone, e.g. bl.spamcop.net.
1297If the IP is in the blocklist, an explanation is printed. This is typically a
1298URL with more information.
1300 usage: mox dnsbl check zone ip
1302# mox dnsbl checkhealth
1304Check the health of the DNS blocklist represented by zone, e.g. bl.spamcop.net.
1306The health of a DNS blocklist can be checked by querying for 127.0.0.1 and
1307127.0.0.2. The second must and the first must not be present.
1309 usage: mox dnsbl checkhealth zone
1313Lookup the MTASTS record and policy for the domain.
1315MTA-STS is a mechanism for a domain to specify if it requires TLS connections
1316for delivering email. If a domain has a valid MTA-STS DNS TXT record at
1317_mta-sts.<domain> it signals it implements MTA-STS. A policy can then be
1318fetched at https://mta-sts.<domain>/.well-known/mta-sts.txt. The policy
1319specifies the mode (enforce, testing, none), which MX servers support TLS and
1320should be used, and how long the policy can be cached.
1322 usage: mox mtasts lookup domain
1326Recreate and retrain the junk filter for the account.
1328Useful after having made changes to the junk filter configuration, or if the
1329implementation has changed.
1331 usage: mox retrain accountname
1335Sendmail is a drop-in replacement for /usr/sbin/sendmail to deliver emails sent by unix processes like cron.
1337If invoked as "sendmail", it will act as sendmail for sending messages. Its
1338intention is to let processes like cron send emails. Messages are submitted to
1339an actual mail server over SMTP. The destination mail server and credentials are
1340configured in /etc/moxsubmit.conf, see mox config describe-sendmail. The From
1341message header is rewritten to the configured address. When the addressee
1342appears to be a local user, because without @, the message is sent to the
1343configured default address.
1345If submitting an email fails, it is added to a directory moxsubmit.failures in
1346the user's home directory.
1348Most flags are ignored to fake compatibility with other sendmail
1349implementations. A single recipient or the -t flag with a To-header is required.
1350With the -t flag, Cc and Bcc headers are not handled specially, so Bcc is not
1351removed and the addresses do not receive the email.
1353/etc/moxsubmit.conf should be group-readable and not readable by others and this
1354binary should be setgid that group:
1357 install -m 2755 -o root -g moxsubmit mox /usr/sbin/sendmail
1358 touch /etc/moxsubmit.conf
1359 chown root:moxsubmit /etc/moxsubmit.conf
1360 chmod 640 /etc/moxsubmit.conf
1361 # edit /etc/moxsubmit.conf
1364 usage: mox sendmail [-Fname] [ignoredflags] [-t] [<message]
1368Check the status of IP for the policy published in DNS for the domain.
1370IPs may be allowed to send for a domain, or disallowed, and several shades in
1371between. If not allowed, an explanation may be provided by the policy. If so,
1372the explanation is printed. The SPF mechanism that matched (if any) is also
1375 usage: mox spf check domain ip
1379Lookup the SPF record for the domain and print it.
1381 usage: mox spf lookup domain
1385Parse the record as SPF record. If valid, nothing is printed.
1387 usage: mox spf parse txtrecord
1391Lookup the TLSRPT record for the domain.
1393A TLSRPT record typically contains an email address where reports about TLS
1394connectivity should be sent. Mail servers attempting delivery to our domain
1395should attempt to use TLS. TLSRPT lets them report how many connection
1396successfully used TLS, and how what kind of errors occurred otherwise.
1398 usage: mox tlsrpt lookup domain
1400# mox tlsrpt parsereportmsg
1402Parse and print the TLSRPT in the message.
1404The report is printed in formatted JSON.
1406 usage: mox tlsrpt parsereportmsg message ...
1410Prints this mox version.
1416Lists available methods, prints request/response parameters for method, or calls a method with a request read from standard input.
1418 usage: mox webapi [method [baseurl-with-credentials]
1422List available examples, or print a specific example.
1424 usage: mox example [name]
1426# mox bumpuidvalidity
1428Change the IMAP UID validity of the mailbox, causing IMAP clients to refetch messages.
1430This can be useful after manually repairing metadata about the account/mailbox.
1432Opens account database file directly. Ensure mox does not have the account
1433open, or is not running.
1435 usage: mox bumpuidvalidity account [mailbox]
1439Reassign UIDs in one mailbox or all mailboxes in an account and bump UID validity, causing IMAP clients to refetch messages.
1441Opens account database file directly. Ensure mox does not have the account
1442open, or is not running.
1444 usage: mox reassignuids account [mailboxid]
1448Fix inconsistent UIDVALIDITY and UIDNEXT in messages/mailboxes/account.
1450The next UID to use for a message in a mailbox should always be higher than any
1451existing message UID in the mailbox. If it is not, the mailbox UIDNEXT is
1454Each mailbox has a UIDVALIDITY sequence number, which should always be lower
1455than the per-account next UIDVALIDITY to use. If it is not, the account next
1456UIDVALIDITY is updated.
1458Opens account database file directly. Ensure mox does not have the account
1459open, or is not running.
1461 usage: mox fixuidmeta account
1465Ensure message sizes in the database matching the sum of the message prefix length and on-disk file size.
1467Messages with an inconsistent size are also parsed again.
1469If an inconsistency is found, you should probably also run "mox
1470bumpuidvalidity" on the mailboxes or entire account to force IMAP clients to
1473 usage: mox fixmsgsize [account]
1477Parse all messages in the account or all accounts again.
1479Can be useful after upgrading mox with improved message parsing. Messages are
1480parsed in batches, so other access to the mailboxes/messages are not blocked
1481while reparsing all messages.
1483 usage: mox reparse [account]
1487Ensure messages in the database have a pre-parsed MIME form in the database.
1489 usage: mox ensureparsed account
1491 store new parsed message for all messages
1493# mox recalculatemailboxcounts
1495Recalculate message counts for all mailboxes in the account, and total message size for quota.
1497When a message is added to/removed from a mailbox, or when message flags change,
1498the total, unread, unseen and deleted messages are accounted, the total size of
1499the mailbox, and the total message size for the account. In case of a bug in
1500this accounting, the numbers could become incorrect. This command will find, fix
1503 usage: mox recalculatemailboxcounts account
1507Parse message, print JSON representation.
1509 usage: mox message parse message.eml
1511 check if message needs smtputf8
1513# mox reassignthreads
1515Reassign message threads.
1517For all accounts, or optionally only the specified account.
1519Threading for all messages in an account is first reset, and new base subject
1520and normalized message-id saved with the message. Then all messages are
1521evaluated and matched against their parents/ancestors.
1523Messages are matched based on the References header, with a fall-back to an
1524In-Reply-To header, and if neither is present/valid, based only on base
1527A References header typically points to multiple previous messages in a
1528hierarchy. From oldest ancestor to most recent parent. An In-Reply-To header
1529would have only a message-id of the parent message.
1531A message is only linked to a parent/ancestor if their base subject is the
1532same. This ensures unrelated replies, with a new subject, are placed in their
1535The base subject is lower cased, has whitespace collapsed to a single
1536space, and some components removed: leading "Re:", "Fwd:", "Fw:", or bracketed
1537tag (that mailing lists often add, e.g. "[listname]"), trailing "(fwd)", or
1538enclosing "[fwd: ...]".
1540Messages are linked to all their ancestors. If an intermediate parent/ancestor
1541message is deleted in the future, the message can still be linked to the earlier
1542ancestors. If the direct parent already wasn't available while matching, this is
1543stored as the message having a "missing link" to its stored ancestors.
1545 usage: mox reassignthreads [account]
1549// NOTE: DO NOT EDIT, this file is generated by gendoc.sh.