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 alias list domain
73 mox config alias print alias
74 mox config alias add alias@domain rcpt1@domain ...
75 mox config alias update alias@domain [-postpublic false|true -listmembers false|true -allowmsgfrom false|true]
76 mox config alias rm alias@domain
77 mox config alias addaddr alias@domain rcpt1@domain ...
78 mox config alias rmaddr alias@domain rcpt1@domain ...
79 mox config describe-sendmail >/etc/moxsubmit.conf
80 mox config printservice >mox.service
81 mox config ensureacmehostprivatekeys
82 mox config example [name]
85 mox clientconfig domain
86 mox dane dial host:port
87 mox dane dialmx domain [destination-host]
88 mox dane makerecord usage selector matchtype [certificate.pem | publickey.pem | privatekey.pem]
89 mox dns lookup [ptr | mx | cname | ips | a | aaaa | ns | txt | srv | tlsa] name
90 mox dkim gened25519 >$selector._domainkey.$domain.ed25519.privatekey.pkcs8.pem
91 mox dkim genrsa >$selector._domainkey.$domain.rsa2048.privatekey.pkcs8.pem
92 mox dkim lookup selector domain
93 mox dkim txt <$selector._domainkey.$domain.key.pkcs8.pem
94 mox dkim verify message
96 mox dmarc lookup domain
97 mox dmarc parsereportmsg message ...
98 mox dmarc verify remoteip mailfromaddress helodomain < message
99 mox dmarc checkreportaddrs domain
100 mox dnsbl check zone ip
101 mox dnsbl checkhealth zone
102 mox mtasts lookup domain
103 mox retrain accountname
104 mox sendmail [-Fname] [ignoredflags] [-t] [<message]
105 mox spf check domain ip
106 mox spf lookup domain
107 mox spf parse txtrecord
108 mox tlsrpt lookup domain
109 mox tlsrpt parsereportmsg message ...
111 mox webapi [method [baseurl-with-credentials]
113 mox bumpuidvalidity account [mailbox]
114 mox reassignuids account [mailboxid]
115 mox fixuidmeta account
116 mox fixmsgsize [account]
117 mox reparse [account]
118 mox ensureparsed account
119 mox recalculatemailboxcounts account
120 mox message parse message.eml
121 mox reassignthreads [account]
125Start mox, serving SMTP/IMAP/HTTPS.
127Incoming email is accepted over SMTP. Email can be retrieved by users using
128IMAP. HTTP listeners are started for the admin/account web interfaces, and for
129automated TLS configuration. Missing essential TLS certificates are immediately
130requested, other TLS certificates are requested on demand.
132Only implemented on unix systems, not Windows.
138Quickstart generates configuration files and prints instructions to quickly set up a mox instance.
140Quickstart writes configuration files, prints initial admin and account
141passwords, DNS records you should create. If you run it on Linux it writes a
142systemd service file and prints commands to enable and start mox as service.
144The user or uid is optional, defaults to "mox", and is the user or uid/gid mox
145will run as after initialization.
147Quickstart assumes mox will run on the machine you run quickstart on and uses
148its host name and public IPs. On many systems the hostname is not a fully
149qualified domain name, but only the first dns "label", e.g. "mail" in case of
150"mail.example.org". If so, quickstart does a reverse DNS lookup to find the
151hostname, and as fallback uses the label plus the domain of the email address
152you specified. Use flag -hostname to explicitly specify the hostname mox will
155Mox is by far easiest to operate if you let it listen on port 443 (HTTPS) and
15680 (HTTP). TLS will be fully automatic with ACME with Let's Encrypt.
158You can run mox along with an existing webserver, but because of MTA-STS and
159autoconfig, you'll need to forward HTTPS traffic for two domains to mox. Run
160"mox quickstart -existing-webserver ..." to generate configuration files and
161instructions for configuring mox along with an existing webserver.
163But please first consider configuring mox on port 443. It can itself serve
164domains with HTTP/HTTPS, including with automatic TLS with ACME, is easily
165configured through both configuration files and admin web interface, and can act
166as a reverse proxy (and static file server for that matter), so you can forward
167traffic to your existing backend applications. Look for "WebHandlers:" in the
168output of "mox config describe-domains" and see the output of
169"mox config example webhandlers".
171 usage: mox quickstart [-skipdial] [-existing-webserver] [-hostname host] user@domain [user | uid]
173 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.
175 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
177 skip check for outgoing smtp (port 25) connectivity
181Shut mox down, giving connections maximum 3 seconds to stop before closing them.
183While shutting down, new IMAP and SMTP connections will get a status response
184indicating temporary unavailability. Existing connections will get a 3 second
185period to finish their transaction and shut down. Under normal circumstances,
186only IMAP has long-living connections, with the IDLE command to get notified of
191# mox setaccountpassword
193Set new password an account.
195The password is read from stdin. Secrets derived from the password, but not the
196password itself, are stored in the account database. The stored secrets are for
197authentication with: scram-sha-256, scram-sha-1, cram-md5, plain text (bcrypt
200The parameter is an account name, as configured under Accounts in domains.conf
201and as present in the data/accounts/ directory, not a configured email address
204 usage: mox setaccountpassword account
206# mox setadminpassword
208Set a new admin password, for the web interface.
210The password is read from stdin. Its bcrypt hash is stored in a file named
211"adminpasswd" in the configuration directory.
213 usage: mox setadminpassword
217Print the log levels, or set a new default log level, or a level for the given package.
219By default, a single log level applies to all logging in mox. But for each
220"pkg", an overriding log level can be configured. Examples of packages:
221smtpserver, smtpclient, queue, imapserver, spf, dkim, dmarc, junk, message,
224Specify a pkg and an empty level to clear the configured level for a package.
226Valid labels: error, info, debug, trace, traceauth, tracedata.
228 usage: mox loglevels [level [pkg]]
230# mox queue holdrules list
232List hold rules for the delivery queue.
234Messages submitted to the queue that match a hold rule will be marked as on hold
235and not scheduled for delivery.
237 usage: mox queue holdrules list
239# mox queue holdrules add
241Add hold rule for the delivery queue.
243Add a hold rule to mark matching newly submitted messages as on hold. Set the
244matching rules with the flags. Don't specify any flags to match all submitted
247 usage: mox queue holdrules add [ruleflags]
249 account submitting the message
255# mox queue holdrules remove
257Remove hold rule for the delivery queue.
259Remove a hold rule by its id.
261 usage: mox queue holdrules remove ruleid
265List matching messages in the delivery queue.
267Prints the message with its ID, last and next delivery attempts, last error.
269 usage: mox queue list [filtersortflags]
271 account that queued the message
273 sort ascending instead of descending (default)
275 from address of message, use "@example.com" to match all messages for a domain
277 true or false, whether to match only messages that are (not) on hold
279 comma-separated list of message IDs
281 number of messages to return
283 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
285 field to sort by, "nextattempt" (default) or "queued"
287 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
289 recipient address of message, use "@example.com" to match all messages for a domain
291 transport to use for messages, empty string sets the default behaviour
295Mark matching messages on hold.
297Messages that are on hold are not delivered until marked as off hold again, or
298otherwise handled by the admin.
300 usage: mox queue hold [filterflags]
302 account that queued the message
304 from address of message, use "@example.com" to match all messages for a domain
306 true or false, whether to match only messages that are (not) on hold
308 comma-separated list of message IDs
310 number of messages to return
312 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
314 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
316 recipient address of message, use "@example.com" to match all messages for a domain
318 transport to use for messages, empty string sets the default behaviour
322Mark matching messages off hold.
324Once off hold, messages can be delivered according to their current next
325delivery attempt. See the "queue schedule" command.
327 usage: mox queue unhold [filterflags]
329 account that queued the message
331 from address of message, use "@example.com" to match all messages for a domain
333 true or false, whether to match only messages that are (not) on hold
335 comma-separated list of message IDs
337 number of messages to return
339 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
341 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
343 recipient address of message, use "@example.com" to match all messages for a domain
345 transport to use for messages, empty string sets the default behaviour
349Change next delivery attempt for matching messages.
351The next delivery attempt is adjusted by the duration parameter. If the -now
352flag is set, the new delivery attempt is set to the duration added to the
353current time, instead of added to the current scheduled time.
355Schedule immediate delivery with "mox queue schedule -now 0".
357 usage: mox queue schedule [filterflags] [-now] duration
359 account that queued the message
361 from address of message, use "@example.com" to match all messages for a domain
363 true or false, whether to match only messages that are (not) on hold
365 comma-separated list of message IDs
367 number of messages to return
369 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
371 schedule for duration relative to current time instead of relative to current next delivery attempt for messages
373 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
375 recipient address of message, use "@example.com" to match all messages for a domain
377 transport to use for messages, empty string sets the default behaviour
381Set transport for matching messages.
383By default, the routing rules determine how a message is delivered. The default
384and common case is direct delivery with SMTP. Messages can get a previously
385configured transport assigned to use for delivery, e.g. using submission to
386another mail server or with connections over a SOCKS proxy.
388 usage: mox queue transport [filterflags] transport
390 account that queued the message
392 from address of message, use "@example.com" to match all messages for a domain
394 true or false, whether to match only messages that are (not) on hold
396 comma-separated list of message IDs
398 number of messages to return
400 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
402 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
404 recipient address of message, use "@example.com" to match all messages for a domain
406 transport to use for messages, empty string sets the default behaviour
408# mox queue requiretls
410Set TLS requirements for delivery of matching messages.
412Value "yes" is handled as if the RequireTLS extension was specified during
415Value "no" is handled as if the message has a header "TLS-Required: No". This
416header is not added by the queue. If messages without this header are relayed
417through other mail servers they will apply their own default TLS policy.
419Value "default" is the default behaviour, currently for unverified opportunistic
422 usage: mox queue requiretls [filterflags] {yes | no | default}
424 account that queued the message
426 from address of message, use "@example.com" to match all messages for a domain
428 true or false, whether to match only messages that are (not) on hold
430 comma-separated list of message IDs
432 number of messages to return
434 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
436 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
438 recipient address of message, use "@example.com" to match all messages for a domain
440 transport to use for messages, empty string sets the default behaviour
444Fail delivery of matching messages, delivering DSNs.
446Failing a message is handled similar to how delivery is given up after all
447delivery attempts failed. The DSN (delivery status notification) message
448contains a line saying the message was canceled by the admin.
450 usage: mox queue fail [filterflags]
452 account that queued the message
454 from address of message, use "@example.com" to match all messages for a domain
456 true or false, whether to match only messages that are (not) on hold
458 comma-separated list of message IDs
460 number of messages to return
462 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
464 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
466 recipient address of message, use "@example.com" to match all messages for a domain
468 transport to use for messages, empty string sets the default behaviour
472Remove matching messages from the queue.
474Dangerous operation, this completely removes the message. If you want to store
475the message, use "queue dump" before removing.
477 usage: mox queue drop [filterflags]
479 account that queued the message
481 from address of message, use "@example.com" to match all messages for a domain
483 true or false, whether to match only messages that are (not) on hold
485 comma-separated list of message IDs
487 number of messages to return
489 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
491 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
493 recipient address of message, use "@example.com" to match all messages for a domain
495 transport to use for messages, empty string sets the default behaviour
499Dump a message from the queue.
501The message is printed to stdout and is in standard internet mail format.
503 usage: mox queue dump id
505# mox queue retired list
507List matching messages in the retired queue.
509Prints messages with their ID and results.
511 usage: mox queue retired list [filtersortflags]
513 account that queued the message
515 sort ascending instead of descending (default)
517 from address of message, use "@example.com" to match all messages for a domain
519 comma-separated list of retired message IDs
521 filter by time of last activity relative to now, value must start with "<" (before now) or ">" (after now)
523 number of messages to return
525 "success" or "failure" as result of delivery
527 field to sort by, "lastactivity" (default) or "queued"
529 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
531 recipient address of message, use "@example.com" to match all messages for a domain
533 transport to use for messages, empty string sets the default behaviour
535# mox queue retired print
537Print a message from the retired queue.
539Prints a JSON representation of the information from the retired queue.
541 usage: mox queue retired print id
543# mox queue suppress list
545Print addresses in suppression list.
547 usage: mox queue suppress list [-account account]
549 only show suppression list for this account
551# mox queue suppress add
553Add address to suppression list for account.
555 usage: mox queue suppress add account address
557# mox queue suppress remove
559Remove address from suppression list for account.
561 usage: mox queue suppress remove account address
563# mox queue suppress lookup
565Check if address is present in suppression list, for any or specific account.
567 usage: mox queue suppress lookup [-account account] address
569 only check address in specified account
571# mox queue webhook list
573List matching webhooks in the queue.
575Prints list of webhooks, their IDs and basic information.
577 usage: mox queue webhook list [filtersortflags]
579 account that queued the message/webhook
581 sort ascending instead of descending (default)
583 event this webhook is about: incoming, delivered, suppressed, delayed, failed, relayed, expanded, canceled, unrecognized
585 comma-separated list of webhook IDs
587 number of webhooks to return
589 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
591 field to sort by, "nextattempt" (default) or "queued"
593 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
595# mox queue webhook schedule
597Change next delivery attempt for matching webhooks.
599The next delivery attempt is adjusted by the duration parameter. If the -now
600flag is set, the new delivery attempt is set to the duration added to the
601current time, instead of added to the current scheduled time.
603Schedule immediate delivery with "mox queue schedule -now 0".
605 usage: mox queue webhook schedule [filterflags] duration
607 account that queued the message/webhook
609 event this webhook is about: incoming, delivered, suppressed, delayed, failed, relayed, expanded, canceled, unrecognized
611 comma-separated list of webhook IDs
613 number of webhooks to return
615 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
617 schedule for duration relative to current time instead of relative to current next delivery attempt for webhooks
619 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
621# mox queue webhook cancel
623Fail delivery of matching webhooks.
625 usage: mox queue webhook cancel [filterflags]
627 account that queued the message/webhook
629 event this webhook is about: incoming, delivered, suppressed, delayed, failed, relayed, expanded, canceled, unrecognized
631 comma-separated list of webhook IDs
633 number of webhooks to return
635 filter by time of next delivery attempt relative to now, value must start with "<" (before now) or ">" (after now)
637 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
639# mox queue webhook print
641Print details of a webhook from the queue.
643The webhook is printed to stdout as JSON.
645 usage: mox queue webhook print id
647# mox queue webhook retired list
649List matching webhooks in the retired queue.
651Prints list of retired webhooks, their IDs and basic information.
653 usage: mox queue webhook retired list [filtersortflags]
655 account that queued the message/webhook
657 sort ascending instead of descending (default)
659 event this webhook is about: incoming, delivered, suppressed, delayed, failed, relayed, expanded, canceled, unrecognized
661 comma-separated list of retired webhook IDs
663 filter by time of last activity relative to now, value must start with "<" (before now) or ">" (after now)
665 number of webhooks to return
667 field to sort by, "lastactivity" (default) or "queued"
669 filter by time of submission relative to now, value must start with "<" (before now) or ">" (after now)
671# mox queue webhook retired print
673Print details of a webhook from the retired queue.
675The retired webhook is printed to stdout as JSON.
677 usage: mox queue webhook retired print id
681Import a maildir into an account.
683The mbox/maildir archive is accessed and imported by the running mox process, so
684it must have access to the archive files. The default suggested systemd service
685file isolates mox from most of the file system, with only the "data/" directory
686accessible, so you may want to put the mbox/maildir archive files in a
687directory like "data/import/" to make it available to mox.
689By default, messages will train the junk filter based on their flags and, if
690"automatic junk flags" configuration is set, based on mailbox naming.
692If the destination mailbox is the Sent mailbox, the recipients of the messages
693are added to the message metadata, causing later incoming messages from these
694recipients to be accepted, unless other reputation signals prevent that.
696Users can also import mailboxes/messages through the account web page by
697uploading a zip or tgz file with mbox and/or maildirs.
699Messages are imported even if already present. Importing messages twice will
700result in duplicate messages.
702Mailbox flags, like "seen", "answered", will be imported. An optional
703dovecot-keywords file can specify additional flags, like Forwarded/Junk/NotJunk.
705 usage: mox import maildir accountname mailboxname maildir
709Import an mbox into an account.
711Using mbox is not recommended, maildir is a better defined format.
713The mbox/maildir archive is accessed and imported by the running mox process, so
714it must have access to the archive files. The default suggested systemd service
715file isolates mox from most of the file system, with only the "data/" directory
716accessible, so you may want to put the mbox/maildir archive files in a
717directory like "data/import/" to make it available to mox.
719By default, messages will train the junk filter based on their flags and, if
720"automatic junk flags" configuration is set, based on mailbox naming.
722If the destination mailbox is the Sent mailbox, the recipients of the messages
723are added to the message metadata, causing later incoming messages from these
724recipients to be accepted, unless other reputation signals prevent that.
726Users can also import mailboxes/messages through the account web page by
727uploading a zip or tgz file with mbox and/or maildirs.
729Messages are imported even if already present. Importing messages twice will
730result in duplicate messages.
732 usage: mox import mbox accountname mailboxname mbox
736Export one or all mailboxes from an account in maildir format.
738Export bypasses a running mox instance. It opens the account mailbox/message
739database file directly. This may block if a running mox instance also has the
740database open, e.g. for IMAP connections. To export from a running instance, use
741the accounts web page or webmail.
743 usage: mox export maildir [-single] dst-dir account-path [mailbox]
745 export single mailbox, without any children. disabled if mailbox isn't specified.
749Export messages from one or all mailboxes in an account in mbox format.
751Using mbox is not recommended. Maildir is a better format.
753Export bypasses a running mox instance. It opens the account mailbox/message
754database file directly. This may block if a running mox instance also has the
755database open, e.g. for IMAP connections. To export from a running instance, use
756the accounts web page or webmail.
758For mbox export, "mboxrd" is used where message lines starting with the magic
759"From " string are escaped by prepending a >. All ">*From " are escaped,
760otherwise reconstructing the original could lose a ">".
762 usage: mox export mbox [-single] dst-dir account-path [mailbox]
764 export single mailbox, without any children. disabled if mailbox isn't specified.
768Start a local SMTP/IMAP server that accepts all messages, useful when testing/developing software that sends email.
770Localserve starts mox with a configuration suitable for local email-related
771software development/testing. It listens for SMTP/Submission(s), IMAP(s) and
772HTTP(s), on the regular port numbers + 1000.
774Data is stored in the system user's configuration directory under
775"mox-localserve", e.g. $HOME/.config/mox-localserve/ on linux, but can be
776overridden with the -dir flag. If the directory does not yet exist, it is
777automatically initialized with configuration files, an account with email
778address mox@localhost and password moxmoxmox, and a newly generated self-signed
781Incoming messages are delivered as normal, falling back to accepting and
782delivering to the mox account for unknown addresses.
783Submitted messages are added to the queue, which delivers by ignoring the
784destination servers, always connecting to itself instead.
786Recipient addresses with the following localpart suffixes are handled specially:
788- "temperror": fail with a temporary error code
789- "permerror": fail with a permanent error code
790- [45][0-9][0-9]: fail with the specific error code
791- "timeout": no response (for an hour)
793If the localpart begins with "mailfrom" or "rcptto", the error is returned
794during those commands instead of during "data".
796 usage: mox localserve
798 configuration storage directory (default "$userconfigdir/mox-localserve")
800 write configuration files and exit
802 serve on this ip instead of default 127.0.0.1 and ::1. only used when writing configuration, at first launch.
806Prints help about matching commands.
808If multiple commands match, they are listed along with the first line of their help text.
809If a single command matches, its usage and full help text is printed.
811 usage: mox help [command ...]
815Creates a backup of the data directory.
817Backup creates consistent snapshots of the databases and message files and
818copies other files in the data directory. Empty directories are not copied.
819These files can then be stored elsewhere for long-term storage, or used to fall
820back to should an upgrade fail. Simply copying files in the data directory
821while mox is running can result in unusable database files.
823Message files never change (they are read-only, though can be removed) and are
824hard-linked so they don't consume additional space. If hardlinking fails, for
825example when the backup destination directory is on a different file system, a
826regular copy is made. Using a destination directory like "data/tmp/backup"
827increases the odds hardlinking succeeds: the default systemd service file
828specifically mounts the data directory, causing attempts to hardlink outside it
829to fail with an error about cross-device linking.
831All files in the data directory that aren't recognized (i.e. other than known
832database files, message files, an acme directory, the "tmp" directory, etc),
833are stored, but with a warning.
835Remove files in the destination directory before doing another backup. The
836backup command will not overwrite files, but print and return errors.
838Exit code 0 indicates the backup was successful. A clean successful backup does
839not print any output, but may print warnings. Use the -verbose flag for
840details, including timing.
842To restore a backup, first shut down mox, move away the old data directory and
843move an earlier backed up directory in its place, run "mox verifydata",
844possibly with the "-fix" option, and restart mox. After the restore, you may
845also want to run "mox bumpuidvalidity" for each account for which messages in a
846mailbox changed, to force IMAP clients to synchronize mailbox state.
848Before upgrading, to check if the upgrade will likely succeed, first make a
849backup, then use the new mox binary to run "mox verifydata" on the backup. This
850can change the backup files (e.g. upgrade database files, move away
851unrecognized message files), so you should make a new backup before actually
854 usage: mox backup dest-dir
860Verify the contents of a data directory, typically of a backup.
862Verifydata checks all database files to see if they are valid BoltDB/bstore
863databases. It checks that all messages in the database have a corresponding
864on-disk message file and there are no unrecognized files. If option -fix is
865specified, unrecognized message files are moved away. This may be needed after
866a restore, because messages enqueued or delivered in the future may get those
867message sequence numbers assigned and writing the message file would fail.
868Consistency of message/mailbox UID, UIDNEXT and UIDVALIDITY is verified as
871Because verifydata opens the database files, schema upgrades may automatically
872be applied. This can happen if you use a new mox release. It is useful to run
873"mox verifydata" with a new binary before attempting an upgrade, but only on a
874copy of the database files, as made with "mox backup". Before upgrading, make a
875new backup again since "mox verifydata" may have upgraded the database files,
876possibly making them potentially no longer readable by the previous version.
878 usage: mox verifydata data-dir
880 fix fixable problems, such as moving away message files not referenced by their database
882 skip the check for message size
886Print licenses of mox source code and dependencies.
892Parses and validates the configuration files.
894If valid, the command exits with status 0. If not valid, all errors encountered
897 usage: mox config test
901Check the DNS records with the configuration for the domain, and print any errors/warnings.
903 usage: mox config dnscheck domain
905# mox config dnsrecords
907Prints annotated DNS records as zone file that should be created for the domain.
909The zone file can be imported into existing DNS software. You should review the
910DNS records, especially if your domain previously/currently has email
913 usage: mox config dnsrecords domain
915# mox config describe-domains
917Prints an annotated empty configuration for use as domains.conf.
919The domains configuration file contains the domains and their configuration,
920and accounts and their configuration. This includes the configured email
921addresses. The mox admin web interface, and the mox command line interface, can
922make changes to this file. Mox automatically reloads this file when it changes.
924Like the static configuration, the example domains.conf printed by this command
925needs modifications to make it valid.
927 usage: mox config describe-domains >domains.conf
929# mox config describe-static
931Prints an annotated empty configuration for use as mox.conf.
933The static configuration file cannot be reloaded while mox is running. Mox has
934to be restarted for changes to the static configuration file to take effect.
936This configuration file needs modifications to make it valid. For example, it
937may contain unfinished list items.
939 usage: mox config describe-static >mox.conf
941# mox config account add
943Add an account with an email address and reload the configuration.
945Email can be delivered to this address/account. A password has to be configured
946explicitly, see the setaccountpassword command.
948 usage: mox config account add account address
950# mox config account rm
952Remove an account and reload the configuration.
954Email addresses for this account will also be removed, and incoming email for
955these addresses will be rejected.
957All data for the account will be removed.
959 usage: mox config account rm account
961# mox config address add
963Adds an address to an account and reloads the configuration.
965If address starts with a @ (i.e. a missing localpart), this is a catchall
966address for the domain.
968 usage: mox config address add address account
970# mox config address rm
972Remove an address and reload the configuration.
974Incoming email for this address will be rejected after removing an address.
976 usage: mox config address rm address
978# mox config domain add
980Adds a new domain to the configuration and reloads the configuration.
982The account is used for the postmaster mailboxes the domain, including as DMARC and
983TLS reporting. Localpart is the "username" at the domain for this account. If
984must be set if and only if account does not yet exist.
986 usage: mox config domain add domain account [localpart]
988# mox config domain rm
990Remove a domain from the configuration and reload the configuration.
992This is a dangerous operation. Incoming email delivery for this domain will be
995 usage: mox config domain rm domain
997# mox config alias list
999List aliases for domain.
1001 usage: mox config alias list domain
1003# mox config alias print
1005Print settings and members of alias.
1007 usage: mox config alias print alias
1009# mox config alias add
1011Add new alias with one or more addresses and public posting enabled.
1013 usage: mox config alias add alias@domain rcpt1@domain ...
1015# mox config alias update
1017Update alias configuration.
1019 usage: mox config alias update alias@domain [-postpublic false|true -listmembers false|true -allowmsgfrom false|true]
1020 -allowmsgfrom string
1021 whether alias address can be used in message from header
1023 whether list members can list members
1025 whether anyone or only list members can post
1027# mox config alias rm
1031 usage: mox config alias rm alias@domain
1033# mox config alias addaddr
1035Add addresses to alias.
1037 usage: mox config alias addaddr alias@domain rcpt1@domain ...
1039# mox config alias rmaddr
1041Remove addresses from alias.
1043 usage: mox config alias rmaddr alias@domain rcpt1@domain ...
1045# mox config describe-sendmail
1047Describe configuration for mox when invoked as sendmail.
1049 usage: mox config describe-sendmail >/etc/moxsubmit.conf
1051# mox config printservice
1053Prints a systemd unit service file for mox.
1055This is the same file as generated using quickstart. If the systemd service file
1056has changed with a newer version of mox, use this command to generate an up to
1059 usage: mox config printservice >mox.service
1061# mox config ensureacmehostprivatekeys
1063Ensure host private keys exist for TLS listeners with ACME.
1065In mox.conf, each listener can have TLS configured. Long-lived private key files
1066can be specified, which will be used when requesting ACME certificates.
1067Configuring these private keys makes it feasible to publish DANE TLSA records
1068for the corresponding public keys in DNS, protected with DNSSEC, allowing TLS
1069certificate verification without depending on a list of Certificate Authorities
1070(CAs). Previous versions of mox did not pre-generate private keys for use with
1071ACME certificates, but would generate private keys on-demand. By explicitly
1072configuring private keys, they will not change automatedly with new
1073certificates, and the DNS TLSA records stay valid.
1075This command looks for listeners in mox.conf with TLS with ACME configured. For
1076each missing host private key (of type rsa-2048 and ecdsa-p256) a key is written
1077to config/hostkeys/. If a certificate exists in the ACME "cache", its private
1078key is copied. Otherwise a new private key is generated. Snippets for manually
1079updating/editing mox.conf are printed.
1081After running this command, and updating mox.conf, run "mox config dnsrecords"
1082for a domain and create the TLSA DNS records it suggests to enable DANE.
1084 usage: mox config ensureacmehostprivatekeys
1088List available config examples, or print a specific example.
1090 usage: mox config example [name]
1094Check if a newer version of mox is available.
1096A single DNS TXT lookup to _updates.xmox.nl tells if a new version is
1097available. If so, a changelog is fetched from https://updates.xmox.nl, and the
1098individual entries verified with a builtin public key. The changelog is
1101 usage: mox checkupdate
1105Turn an ID from a Received header into a cid, for looking up in logs.
1107A cid is essentially a connection counter initialized when mox starts. Each log
1108line contains a cid. Received headers added by mox contain a unique ID that can
1109be decrypted to a cid by admin of a mox instance only.
1115Print the configuration for email clients for a domain.
1117Sending email is typically not done on the SMTP port 25, but on submission
1118ports 465 (with TLS) and 587 (without initial TLS, but usually added to the
1119connection with STARTTLS). For IMAP, the port with TLS is 993 and without is
1122Without TLS/STARTTLS, passwords are sent in clear text, which should only be
1123configured over otherwise secured connections, like a VPN.
1125 usage: mox clientconfig domain
1129Dial the address using TLS with certificate verification using DANE.
1131Data is copied between connection and stdin/stdout until either side closes the
1134 usage: mox dane dial host:port
1136 allowed usages for dane, comma-separated list (default "pkix-ta,pkix-ee,dane-ta,dane-ee")
1140Connect to MX server for domain using STARTTLS verified with DANE.
1142If no destination host is specified, regular delivery logic is used to find the
1143hosts to attempt delivery too. This involves following CNAMEs for the domain,
1144looking up MX records, and possibly falling back to the domain name itself as
1147If a destination host is specified, that is the only candidate host considered
1150With a list of destinations gathered, each is dialed until a successful SMTP
1151session verified with DANE has been initialized, including EHLO and STARTTLS
1154Once connected, data is copied between connection and stdin/stdout, until
1155either side closes the connection.
1157This command follows the same logic as delivery attempts made from the queue,
1158sharing most of its code.
1160 usage: mox dane dialmx domain [destination-host]
1161 -ehlohostname string
1162 hostname to send in smtp ehlo command (default "localhost")
1164# mox dane makerecord
1166Print TLSA record for given certificate/key and parameters.
1169- usage: pkix-ta (0), pkix-ee (1), dane-ta (2), dane-ee (3)
1170- selector: cert (0), spki (1)
1171- matchtype: full (0), sha2-256 (1), sha2-512 (2)
1173Common DANE TLSA record parameters are: dane-ee spki sha2-256, or 3 1 1,
1174followed by a sha2-256 hash of the DER-encoded "SPKI" (subject public key info)
1175from the certificate. An example DNS zone file entry:
1177 _25._tcp.example.com. TLSA 3 1 1 133b919c9d65d8b1488157315327334ead8d83372db57465ecabf53ee5748aee
1179The first usable information from the pem file is used to compose the TLSA
1180record. In case of selector "cert", a certificate is required. Otherwise the
1181"subject public key info" (spki) of the first certificate or public or private
1182key (pkcs#8, pkcs#1 or ec private key) is used.
1184 usage: mox dane makerecord usage selector matchtype [certificate.pem | publickey.pem | privatekey.pem]
1188Lookup DNS name of given type.
1190Lookup always prints whether the response was DNSSEC-protected.
1194mox dns lookup ptr 1.1.1.1
1195mox dns lookup mx xmox.nl
1196mox dns lookup txt _dmarc.xmox.nl.
1197mox dns lookup tlsa _25._tcp.xmox.nl
1199 usage: mox dns lookup [ptr | mx | cname | ips | a | aaaa | ns | txt | srv | tlsa] name
1201# mox dkim gened25519
1203Generate a new ed25519 key for use with DKIM.
1205Ed25519 keys are much smaller than RSA keys of comparable cryptographic
1206strength. This is convenient because of maximum DNS message sizes. At the time
1207of writing, not many mail servers appear to support ed25519 DKIM keys though,
1208so it is recommended to sign messages with both RSA and ed25519 keys.
1210 usage: mox dkim gened25519 >$selector._domainkey.$domain.ed25519.privatekey.pkcs8.pem
1214Generate a new 2048 bit RSA private key for use with DKIM.
1216The generated file is in PEM format, and has a comment it is generated for use
1219 usage: mox dkim genrsa >$selector._domainkey.$domain.rsa2048.privatekey.pkcs8.pem
1223Lookup and print the DKIM record for the selector at the domain.
1225 usage: mox dkim lookup selector domain
1229Print a DKIM DNS TXT record with the public key derived from the private key read from stdin.
1231The DNS should be configured as a TXT record at $selector._domainkey.$domain.
1233 usage: mox dkim txt <$selector._domainkey.$domain.key.pkcs8.pem
1237Verify the DKIM signatures in a message and print the results.
1239The message is parsed, and the DKIM-Signature headers are validated. Validation
1240of older messages may fail because the DNS records have been removed or changed
1241by now, or because the signature header may have specified an expiration time
1244 usage: mox dkim verify message
1248Sign a message, adding DKIM-Signature headers based on the domain in the From header.
1250The message is parsed, the domain looked up in the configuration files, and
1251DKIM-Signature headers generated. The message is printed with the DKIM-Signature
1254 usage: mox dkim sign message
1258Lookup dmarc policy for domain, a DNS TXT record at _dmarc.<domain>, validate and print it.
1260 usage: mox dmarc lookup domain
1262# mox dmarc parsereportmsg
1264Parse a DMARC report from an email message, and print its extracted details.
1266DMARC reports are periodically mailed, if requested in the DMARC DNS record of
1267a domain. Reports are sent by mail servers that received messages with our
1268domain in a From header. This may or may not be legatimate email. DMARC reports
1269contain summaries of evaluations of DMARC and DKIM/SPF, which can help
1270understand email deliverability problems.
1272 usage: mox dmarc parsereportmsg message ...
1276Parse an email message and evaluate it against the DMARC policy of the domain in the From-header.
1278mailfromaddress and helodomain are used for SPF validation. If both are empty,
1279SPF validation is skipped.
1281mailfromaddress should be the address used as MAIL FROM in the SMTP session.
1282For DSN messages, that address may be empty. The helo domain was specified at
1283the beginning of the SMTP transaction that delivered the message. These values
1284can be found in message headers.
1286 usage: mox dmarc verify remoteip mailfromaddress helodomain < message
1288# mox dmarc checkreportaddrs
1290For each reporting address in the domain's DMARC record, check if it has opted into receiving reports (if needed).
1292A DMARC record can request reports about DMARC evaluations to be sent to an
1293email/http address. If the organizational domains of that of the DMARC record
1294and that of the report destination address do not match, the destination
1295address must opt-in to receiving DMARC reports by creating a DMARC record at
1296<dmarcdomain>._report._dmarc.<reportdestdomain>.
1298 usage: mox dmarc checkreportaddrs domain
1302Test if IP is in the DNS blocklist of the zone, e.g. bl.spamcop.net.
1304If the IP is in the blocklist, an explanation is printed. This is typically a
1305URL with more information.
1307 usage: mox dnsbl check zone ip
1309# mox dnsbl checkhealth
1311Check the health of the DNS blocklist represented by zone, e.g. bl.spamcop.net.
1313The health of a DNS blocklist can be checked by querying for 127.0.0.1 and
1314127.0.0.2. The second must and the first must not be present.
1316 usage: mox dnsbl checkhealth zone
1320Lookup the MTASTS record and policy for the domain.
1322MTA-STS is a mechanism for a domain to specify if it requires TLS connections
1323for delivering email. If a domain has a valid MTA-STS DNS TXT record at
1324_mta-sts.<domain> it signals it implements MTA-STS. A policy can then be
1325fetched at https://mta-sts.<domain>/.well-known/mta-sts.txt. The policy
1326specifies the mode (enforce, testing, none), which MX servers support TLS and
1327should be used, and how long the policy can be cached.
1329 usage: mox mtasts lookup domain
1333Recreate and retrain the junk filter for the account.
1335Useful after having made changes to the junk filter configuration, or if the
1336implementation has changed.
1338 usage: mox retrain accountname
1342Sendmail is a drop-in replacement for /usr/sbin/sendmail to deliver emails sent by unix processes like cron.
1344If invoked as "sendmail", it will act as sendmail for sending messages. Its
1345intention is to let processes like cron send emails. Messages are submitted to
1346an actual mail server over SMTP. The destination mail server and credentials are
1347configured in /etc/moxsubmit.conf, see mox config describe-sendmail. The From
1348message header is rewritten to the configured address. When the addressee
1349appears to be a local user, because without @, the message is sent to the
1350configured default address.
1352If submitting an email fails, it is added to a directory moxsubmit.failures in
1353the user's home directory.
1355Most flags are ignored to fake compatibility with other sendmail
1356implementations. A single recipient or the -t flag with a To-header is required.
1357With the -t flag, Cc and Bcc headers are not handled specially, so Bcc is not
1358removed and the addresses do not receive the email.
1360/etc/moxsubmit.conf should be group-readable and not readable by others and this
1361binary should be setgid that group:
1364 install -m 2755 -o root -g moxsubmit mox /usr/sbin/sendmail
1365 touch /etc/moxsubmit.conf
1366 chown root:moxsubmit /etc/moxsubmit.conf
1367 chmod 640 /etc/moxsubmit.conf
1368 # edit /etc/moxsubmit.conf
1371 usage: mox sendmail [-Fname] [ignoredflags] [-t] [<message]
1375Check the status of IP for the policy published in DNS for the domain.
1377IPs may be allowed to send for a domain, or disallowed, and several shades in
1378between. If not allowed, an explanation may be provided by the policy. If so,
1379the explanation is printed. The SPF mechanism that matched (if any) is also
1382 usage: mox spf check domain ip
1386Lookup the SPF record for the domain and print it.
1388 usage: mox spf lookup domain
1392Parse the record as SPF record. If valid, nothing is printed.
1394 usage: mox spf parse txtrecord
1398Lookup the TLSRPT record for the domain.
1400A TLSRPT record typically contains an email address where reports about TLS
1401connectivity should be sent. Mail servers attempting delivery to our domain
1402should attempt to use TLS. TLSRPT lets them report how many connection
1403successfully used TLS, and how what kind of errors occurred otherwise.
1405 usage: mox tlsrpt lookup domain
1407# mox tlsrpt parsereportmsg
1409Parse and print the TLSRPT in the message.
1411The report is printed in formatted JSON.
1413 usage: mox tlsrpt parsereportmsg message ...
1417Prints this mox version.
1423Lists available methods, prints request/response parameters for method, or calls a method with a request read from standard input.
1425 usage: mox webapi [method [baseurl-with-credentials]
1429List available examples, or print a specific example.
1431 usage: mox example [name]
1433# mox bumpuidvalidity
1435Change the IMAP UID validity of the mailbox, causing IMAP clients to refetch messages.
1437This can be useful after manually repairing metadata about the account/mailbox.
1439Opens account database file directly. Ensure mox does not have the account
1440open, or is not running.
1442 usage: mox bumpuidvalidity account [mailbox]
1446Reassign UIDs in one mailbox or all mailboxes in an account and bump UID validity, causing IMAP clients to refetch messages.
1448Opens account database file directly. Ensure mox does not have the account
1449open, or is not running.
1451 usage: mox reassignuids account [mailboxid]
1455Fix inconsistent UIDVALIDITY and UIDNEXT in messages/mailboxes/account.
1457The next UID to use for a message in a mailbox should always be higher than any
1458existing message UID in the mailbox. If it is not, the mailbox UIDNEXT is
1461Each mailbox has a UIDVALIDITY sequence number, which should always be lower
1462than the per-account next UIDVALIDITY to use. If it is not, the account next
1463UIDVALIDITY is updated.
1465Opens account database file directly. Ensure mox does not have the account
1466open, or is not running.
1468 usage: mox fixuidmeta account
1472Ensure message sizes in the database matching the sum of the message prefix length and on-disk file size.
1474Messages with an inconsistent size are also parsed again.
1476If an inconsistency is found, you should probably also run "mox
1477bumpuidvalidity" on the mailboxes or entire account to force IMAP clients to
1480 usage: mox fixmsgsize [account]
1484Parse all messages in the account or all accounts again.
1486Can be useful after upgrading mox with improved message parsing. Messages are
1487parsed in batches, so other access to the mailboxes/messages are not blocked
1488while reparsing all messages.
1490 usage: mox reparse [account]
1494Ensure messages in the database have a pre-parsed MIME form in the database.
1496 usage: mox ensureparsed account
1498 store new parsed message for all messages
1500# mox recalculatemailboxcounts
1502Recalculate message counts for all mailboxes in the account, and total message size for quota.
1504When a message is added to/removed from a mailbox, or when message flags change,
1505the total, unread, unseen and deleted messages are accounted, the total size of
1506the mailbox, and the total message size for the account. In case of a bug in
1507this accounting, the numbers could become incorrect. This command will find, fix
1510 usage: mox recalculatemailboxcounts account
1514Parse message, print JSON representation.
1516 usage: mox message parse message.eml
1518 check if message needs smtputf8
1520# mox reassignthreads
1522Reassign message threads.
1524For all accounts, or optionally only the specified account.
1526Threading for all messages in an account is first reset, and new base subject
1527and normalized message-id saved with the message. Then all messages are
1528evaluated and matched against their parents/ancestors.
1530Messages are matched based on the References header, with a fall-back to an
1531In-Reply-To header, and if neither is present/valid, based only on base
1534A References header typically points to multiple previous messages in a
1535hierarchy. From oldest ancestor to most recent parent. An In-Reply-To header
1536would have only a message-id of the parent message.
1538A message is only linked to a parent/ancestor if their base subject is the
1539same. This ensures unrelated replies, with a new subject, are placed in their
1542The base subject is lower cased, has whitespace collapsed to a single
1543space, and some components removed: leading "Re:", "Fwd:", "Fw:", or bracketed
1544tag (that mailing lists often add, e.g. "[listname]"), trailing "(fwd)", or
1545enclosing "[fwd: ...]".
1547Messages are linked to all their ancestors. If an intermediate parent/ancestor
1548message is deleted in the future, the message can still be linked to the earlier
1549ancestors. If the direct parent already wasn't available while matching, this is
1550stored as the message having a "missing link" to its stored ancestors.
1552 usage: mox reassignthreads [account]
1556// NOTE: DO NOT EDIT, this file is generated by gendoc.sh.