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.
698Mailbox flags, like "seen", "answered", will be imported. An optional
699dovecot-keywords file can specify additional flags, like Forwarded/Junk/NotJunk.
701 usage: mox import maildir accountname mailboxname maildir
705Import an mbox into an account.
707Using mbox is not recommended, maildir is a better defined format.
709The mbox/maildir archive is accessed and imported by the running mox process, so
710it must have access to the archive files. The default suggested systemd service
711file isolates mox from most of the file system, with only the "data/" directory
712accessible, so you may want to put the mbox/maildir archive files in a
713directory like "data/import/" to make it available to mox.
715By default, messages will train the junk filter based on their flags and, if
716"automatic junk flags" configuration is set, based on mailbox naming.
718If the destination mailbox is the Sent mailbox, the recipients of the messages
719are added to the message metadata, causing later incoming messages from these
720recipients to be accepted, unless other reputation signals prevent that.
722Users can also import mailboxes/messages through the account web page by
723uploading a zip or tgz file with mbox and/or maildirs.
725 usage: mox import mbox accountname mailboxname mbox
729Export one or all mailboxes from an account in maildir format.
731Export bypasses a running mox instance. It opens the account mailbox/message
732database file directly. This may block if a running mox instance also has the
733database open, e.g. for IMAP connections. To export from a running instance, use
734the accounts web page or webmail.
736 usage: mox export maildir [-single] dst-dir account-path [mailbox]
738 export single mailbox, without any children. disabled if mailbox isn't specified.
742Export messages from one or all mailboxes in an account in mbox format.
744Using mbox is not recommended. Maildir is a better format.
746Export bypasses a running mox instance. It opens the account mailbox/message
747database file directly. This may block if a running mox instance also has the
748database open, e.g. for IMAP connections. To export from a running instance, use
749the accounts web page or webmail.
751For mbox export, "mboxrd" is used where message lines starting with the magic
752"From " string are escaped by prepending a >. All ">*From " are escaped,
753otherwise reconstructing the original could lose a ">".
755 usage: mox export mbox [-single] dst-dir account-path [mailbox]
757 export single mailbox, without any children. disabled if mailbox isn't specified.
761Start a local SMTP/IMAP server that accepts all messages, useful when testing/developing software that sends email.
763Localserve starts mox with a configuration suitable for local email-related
764software development/testing. It listens for SMTP/Submission(s), IMAP(s) and
765HTTP(s), on the regular port numbers + 1000.
767Data is stored in the system user's configuration directory under
768"mox-localserve", e.g. $HOME/.config/mox-localserve/ on linux, but can be
769overridden with the -dir flag. If the directory does not yet exist, it is
770automatically initialized with configuration files, an account with email
771address mox@localhost and password moxmoxmox, and a newly generated self-signed
774Incoming messages are delivered as normal, falling back to accepting and
775delivering to the mox account for unknown addresses.
776Submitted messages are added to the queue, which delivers by ignoring the
777destination servers, always connecting to itself instead.
779Recipient addresses with the following localpart suffixes are handled specially:
781- "temperror": fail with a temporary error code
782- "permerror": fail with a permanent error code
783- [45][0-9][0-9]: fail with the specific error code
784- "timeout": no response (for an hour)
786If the localpart begins with "mailfrom" or "rcptto", the error is returned
787during those commands instead of during "data".
789 usage: mox localserve
791 configuration storage directory (default "$userconfigdir/mox-localserve")
793 write configuration files and exit
795 serve on this ip instead of default 127.0.0.1 and ::1. only used when writing configuration, at first launch.
799Prints help about matching commands.
801If multiple commands match, they are listed along with the first line of their help text.
802If a single command matches, its usage and full help text is printed.
804 usage: mox help [command ...]
808Creates a backup of the data directory.
810Backup creates consistent snapshots of the databases and message files and
811copies other files in the data directory. Empty directories are not copied.
812These files can then be stored elsewhere for long-term storage, or used to fall
813back to should an upgrade fail. Simply copying files in the data directory
814while mox is running can result in unusable database files.
816Message files never change (they are read-only, though can be removed) and are
817hard-linked so they don't consume additional space. If hardlinking fails, for
818example when the backup destination directory is on a different file system, a
819regular copy is made. Using a destination directory like "data/tmp/backup"
820increases the odds hardlinking succeeds: the default systemd service file
821specifically mounts the data directory, causing attempts to hardlink outside it
822to fail with an error about cross-device linking.
824All files in the data directory that aren't recognized (i.e. other than known
825database files, message files, an acme directory, the "tmp" directory, etc),
826are stored, but with a warning.
828A clean successful backup does not print any output by default. Use the
829-verbose flag for details, including timing.
831To restore a backup, first shut down mox, move away the old data directory and
832move an earlier backed up directory in its place, run "mox verifydata",
833possibly with the "-fix" option, and restart mox. After the restore, you may
834also want to run "mox bumpuidvalidity" for each account for which messages in a
835mailbox changed, to force IMAP clients to synchronize mailbox state.
837Before upgrading, to check if the upgrade will likely succeed, first make a
838backup, then use the new mox binary to run "mox verifydata" on the backup. This
839can change the backup files (e.g. upgrade database files, move away
840unrecognized message files), so you should make a new backup before actually
843 usage: mox backup dest-dir
849Verify the contents of a data directory, typically of a backup.
851Verifydata checks all database files to see if they are valid BoltDB/bstore
852databases. It checks that all messages in the database have a corresponding
853on-disk message file and there are no unrecognized files. If option -fix is
854specified, unrecognized message files are moved away. This may be needed after
855a restore, because messages enqueued or delivered in the future may get those
856message sequence numbers assigned and writing the message file would fail.
857Consistency of message/mailbox UID, UIDNEXT and UIDVALIDITY is verified as
860Because verifydata opens the database files, schema upgrades may automatically
861be applied. This can happen if you use a new mox release. It is useful to run
862"mox verifydata" with a new binary before attempting an upgrade, but only on a
863copy of the database files, as made with "mox backup". Before upgrading, make a
864new backup again since "mox verifydata" may have upgraded the database files,
865possibly making them potentially no longer readable by the previous version.
867 usage: mox verifydata data-dir
869 fix fixable problems, such as moving away message files not referenced by their database
871 skip the check for message size
875Parses and validates the configuration files.
877If valid, the command exits with status 0. If not valid, all errors encountered
880 usage: mox config test
884Check the DNS records with the configuration for the domain, and print any errors/warnings.
886 usage: mox config dnscheck domain
888# mox config dnsrecords
890Prints annotated DNS records as zone file that should be created for the domain.
892The zone file can be imported into existing DNS software. You should review the
893DNS records, especially if your domain previously/currently has email
896 usage: mox config dnsrecords domain
898# mox config describe-domains
900Prints an annotated empty configuration for use as domains.conf.
902The domains configuration file contains the domains and their configuration,
903and accounts and their configuration. This includes the configured email
904addresses. The mox admin web interface, and the mox command line interface, can
905make changes to this file. Mox automatically reloads this file when it changes.
907Like the static configuration, the example domains.conf printed by this command
908needs modifications to make it valid.
910 usage: mox config describe-domains >domains.conf
912# mox config describe-static
914Prints an annotated empty configuration for use as mox.conf.
916The static configuration file cannot be reloaded while mox is running. Mox has
917to be restarted for changes to the static configuration file to take effect.
919This configuration file needs modifications to make it valid. For example, it
920may contain unfinished list items.
922 usage: mox config describe-static >mox.conf
924# mox config account add
926Add an account with an email address and reload the configuration.
928Email can be delivered to this address/account. A password has to be configured
929explicitly, see the setaccountpassword command.
931 usage: mox config account add account address
933# mox config account rm
935Remove an account and reload the configuration.
937Email addresses for this account will also be removed, and incoming email for
938these addresses will be rejected.
940 usage: mox config account rm account
942# mox config address add
944Adds an address to an account and reloads the configuration.
946If address starts with a @ (i.e. a missing localpart), this is a catchall
947address for the domain.
949 usage: mox config address add address account
951# mox config address rm
953Remove an address and reload the configuration.
955Incoming email for this address will be rejected after removing an address.
957 usage: mox config address rm address
959# mox config domain add
961Adds a new domain to the configuration and reloads the configuration.
963The account is used for the postmaster mailboxes the domain, including as DMARC and
964TLS reporting. Localpart is the "username" at the domain for this account. If
965must be set if and only if account does not yet exist.
967 usage: mox config domain add domain account [localpart]
969# mox config domain rm
971Remove a domain from the configuration and reload the configuration.
973This is a dangerous operation. Incoming email delivery for this domain will be
976 usage: mox config domain rm domain
978# mox config alias list
980List aliases for domain.
982 usage: mox config alias list domain
984# mox config alias print
986Print settings and members of alias.
988 usage: mox config alias print alias
990# mox config alias add
992Add new alias with one or more addresses.
994 usage: mox config alias add alias@domain rcpt1@domain ...
996# mox config alias update
998Update alias configuration.
1000 usage: mox config alias update alias@domain [-postpublic false|true -listmembers false|true -allowmsgfrom false|true]
1001 -allowmsgfrom string
1002 whether alias address can be used in message from header
1004 whether list members can list members
1006 whether anyone or only list members can post
1008# mox config alias rm
1012 usage: mox config alias rm alias@domain
1014# mox config alias addaddr
1016Add addresses to alias.
1018 usage: mox config alias addaddr alias@domain rcpt1@domain ...
1020# mox config alias rmaddr
1022Remove addresses from alias.
1024 usage: mox config alias rmaddr alias@domain rcpt1@domain ...
1026# mox config describe-sendmail
1028Describe configuration for mox when invoked as sendmail.
1030 usage: mox config describe-sendmail >/etc/moxsubmit.conf
1032# mox config printservice
1034Prints a systemd unit service file for mox.
1036This is the same file as generated using quickstart. If the systemd service file
1037has changed with a newer version of mox, use this command to generate an up to
1040 usage: mox config printservice >mox.service
1042# mox config ensureacmehostprivatekeys
1044Ensure host private keys exist for TLS listeners with ACME.
1046In mox.conf, each listener can have TLS configured. Long-lived private key files
1047can be specified, which will be used when requesting ACME certificates.
1048Configuring these private keys makes it feasible to publish DANE TLSA records
1049for the corresponding public keys in DNS, protected with DNSSEC, allowing TLS
1050certificate verification without depending on a list of Certificate Authorities
1051(CAs). Previous versions of mox did not pre-generate private keys for use with
1052ACME certificates, but would generate private keys on-demand. By explicitly
1053configuring private keys, they will not change automatedly with new
1054certificates, and the DNS TLSA records stay valid.
1056This command looks for listeners in mox.conf with TLS with ACME configured. For
1057each missing host private key (of type rsa-2048 and ecdsa-p256) a key is written
1058to config/hostkeys/. If a certificate exists in the ACME "cache", its private
1059key is copied. Otherwise a new private key is generated. Snippets for manually
1060updating/editing mox.conf are printed.
1062After running this command, and updating mox.conf, run "mox config dnsrecords"
1063for a domain and create the TLSA DNS records it suggests to enable DANE.
1065 usage: mox config ensureacmehostprivatekeys
1069List available config examples, or print a specific example.
1071 usage: mox config example [name]
1075Check if a newer version of mox is available.
1077A single DNS TXT lookup to _updates.xmox.nl tells if a new version is
1078available. If so, a changelog is fetched from https://updates.xmox.nl, and the
1079individual entries verified with a builtin public key. The changelog is
1082 usage: mox checkupdate
1086Turn an ID from a Received header into a cid, for looking up in logs.
1088A cid is essentially a connection counter initialized when mox starts. Each log
1089line contains a cid. Received headers added by mox contain a unique ID that can
1090be decrypted to a cid by admin of a mox instance only.
1096Print the configuration for email clients for a domain.
1098Sending email is typically not done on the SMTP port 25, but on submission
1099ports 465 (with TLS) and 587 (without initial TLS, but usually added to the
1100connection with STARTTLS). For IMAP, the port with TLS is 993 and without is
1103Without TLS/STARTTLS, passwords are sent in clear text, which should only be
1104configured over otherwise secured connections, like a VPN.
1106 usage: mox clientconfig domain
1110Dial the address using TLS with certificate verification using DANE.
1112Data is copied between connection and stdin/stdout until either side closes the
1115 usage: mox dane dial host:port
1117 allowed usages for dane, comma-separated list (default "pkix-ta,pkix-ee,dane-ta,dane-ee")
1121Connect to MX server for domain using STARTTLS verified with DANE.
1123If no destination host is specified, regular delivery logic is used to find the
1124hosts to attempt delivery too. This involves following CNAMEs for the domain,
1125looking up MX records, and possibly falling back to the domain name itself as
1128If a destination host is specified, that is the only candidate host considered
1131With a list of destinations gathered, each is dialed until a successful SMTP
1132session verified with DANE has been initialized, including EHLO and STARTTLS
1135Once connected, data is copied between connection and stdin/stdout, until
1136either side closes the connection.
1138This command follows the same logic as delivery attempts made from the queue,
1139sharing most of its code.
1141 usage: mox dane dialmx domain [destination-host]
1142 -ehlohostname string
1143 hostname to send in smtp ehlo command (default "localhost")
1145# mox dane makerecord
1147Print TLSA record for given certificate/key and parameters.
1150- usage: pkix-ta (0), pkix-ee (1), dane-ta (2), dane-ee (3)
1151- selector: cert (0), spki (1)
1152- matchtype: full (0), sha2-256 (1), sha2-512 (2)
1154Common DANE TLSA record parameters are: dane-ee spki sha2-256, or 3 1 1,
1155followed by a sha2-256 hash of the DER-encoded "SPKI" (subject public key info)
1156from the certificate. An example DNS zone file entry:
1158 _25._tcp.example.com. TLSA 3 1 1 133b919c9d65d8b1488157315327334ead8d83372db57465ecabf53ee5748aee
1160The first usable information from the pem file is used to compose the TLSA
1161record. In case of selector "cert", a certificate is required. Otherwise the
1162"subject public key info" (spki) of the first certificate or public or private
1163key (pkcs#8, pkcs#1 or ec private key) is used.
1165 usage: mox dane makerecord usage selector matchtype [certificate.pem | publickey.pem | privatekey.pem]
1169Lookup DNS name of given type.
1171Lookup always prints whether the response was DNSSEC-protected.
1175mox dns lookup ptr 1.1.1.1
1176mox dns lookup mx xmox.nl
1177mox dns lookup txt _dmarc.xmox.nl.
1178mox dns lookup tlsa _25._tcp.xmox.nl
1180 usage: mox dns lookup [ptr | mx | cname | ips | a | aaaa | ns | txt | srv | tlsa] name
1182# mox dkim gened25519
1184Generate a new ed25519 key for use with DKIM.
1186Ed25519 keys are much smaller than RSA keys of comparable cryptographic
1187strength. This is convenient because of maximum DNS message sizes. At the time
1188of writing, not many mail servers appear to support ed25519 DKIM keys though,
1189so it is recommended to sign messages with both RSA and ed25519 keys.
1191 usage: mox dkim gened25519 >$selector._domainkey.$domain.ed25519.privatekey.pkcs8.pem
1195Generate a new 2048 bit RSA private key for use with DKIM.
1197The generated file is in PEM format, and has a comment it is generated for use
1200 usage: mox dkim genrsa >$selector._domainkey.$domain.rsa2048.privatekey.pkcs8.pem
1204Lookup and print the DKIM record for the selector at the domain.
1206 usage: mox dkim lookup selector domain
1210Print a DKIM DNS TXT record with the public key derived from the private key read from stdin.
1212The DNS should be configured as a TXT record at $selector._domainkey.$domain.
1214 usage: mox dkim txt <$selector._domainkey.$domain.key.pkcs8.pem
1218Verify the DKIM signatures in a message and print the results.
1220The message is parsed, and the DKIM-Signature headers are validated. Validation
1221of older messages may fail because the DNS records have been removed or changed
1222by now, or because the signature header may have specified an expiration time
1225 usage: mox dkim verify message
1229Sign a message, adding DKIM-Signature headers based on the domain in the From header.
1231The message is parsed, the domain looked up in the configuration files, and
1232DKIM-Signature headers generated. The message is printed with the DKIM-Signature
1235 usage: mox dkim sign message
1239Lookup dmarc policy for domain, a DNS TXT record at _dmarc.<domain>, validate and print it.
1241 usage: mox dmarc lookup domain
1243# mox dmarc parsereportmsg
1245Parse a DMARC report from an email message, and print its extracted details.
1247DMARC reports are periodically mailed, if requested in the DMARC DNS record of
1248a domain. Reports are sent by mail servers that received messages with our
1249domain in a From header. This may or may not be legatimate email. DMARC reports
1250contain summaries of evaluations of DMARC and DKIM/SPF, which can help
1251understand email deliverability problems.
1253 usage: mox dmarc parsereportmsg message ...
1257Parse an email message and evaluate it against the DMARC policy of the domain in the From-header.
1259mailfromaddress and helodomain are used for SPF validation. If both are empty,
1260SPF validation is skipped.
1262mailfromaddress should be the address used as MAIL FROM in the SMTP session.
1263For DSN messages, that address may be empty. The helo domain was specified at
1264the beginning of the SMTP transaction that delivered the message. These values
1265can be found in message headers.
1267 usage: mox dmarc verify remoteip mailfromaddress helodomain < message
1269# mox dmarc checkreportaddrs
1271For each reporting address in the domain's DMARC record, check if it has opted into receiving reports (if needed).
1273A DMARC record can request reports about DMARC evaluations to be sent to an
1274email/http address. If the organizational domains of that of the DMARC record
1275and that of the report destination address do not match, the destination
1276address must opt-in to receiving DMARC reports by creating a DMARC record at
1277<dmarcdomain>._report._dmarc.<reportdestdomain>.
1279 usage: mox dmarc checkreportaddrs domain
1283Test if IP is in the DNS blocklist of the zone, e.g. bl.spamcop.net.
1285If the IP is in the blocklist, an explanation is printed. This is typically a
1286URL with more information.
1288 usage: mox dnsbl check zone ip
1290# mox dnsbl checkhealth
1292Check the health of the DNS blocklist represented by zone, e.g. bl.spamcop.net.
1294The health of a DNS blocklist can be checked by querying for 127.0.0.1 and
1295127.0.0.2. The second must and the first must not be present.
1297 usage: mox dnsbl checkhealth zone
1301Lookup the MTASTS record and policy for the domain.
1303MTA-STS is a mechanism for a domain to specify if it requires TLS connections
1304for delivering email. If a domain has a valid MTA-STS DNS TXT record at
1305_mta-sts.<domain> it signals it implements MTA-STS. A policy can then be
1306fetched at https://mta-sts.<domain>/.well-known/mta-sts.txt. The policy
1307specifies the mode (enforce, testing, none), which MX servers support TLS and
1308should be used, and how long the policy can be cached.
1310 usage: mox mtasts lookup domain
1314Recreate and retrain the junk filter for the account.
1316Useful after having made changes to the junk filter configuration, or if the
1317implementation has changed.
1319 usage: mox retrain accountname
1323Sendmail is a drop-in replacement for /usr/sbin/sendmail to deliver emails sent by unix processes like cron.
1325If invoked as "sendmail", it will act as sendmail for sending messages. Its
1326intention is to let processes like cron send emails. Messages are submitted to
1327an actual mail server over SMTP. The destination mail server and credentials are
1328configured in /etc/moxsubmit.conf, see mox config describe-sendmail. The From
1329message header is rewritten to the configured address. When the addressee
1330appears to be a local user, because without @, the message is sent to the
1331configured default address.
1333If submitting an email fails, it is added to a directory moxsubmit.failures in
1334the user's home directory.
1336Most flags are ignored to fake compatibility with other sendmail
1337implementations. A single recipient or the -t flag with a To-header is required.
1338With the -t flag, Cc and Bcc headers are not handled specially, so Bcc is not
1339removed and the addresses do not receive the email.
1341/etc/moxsubmit.conf should be group-readable and not readable by others and this
1342binary should be setgid that group:
1345 install -m 2755 -o root -g moxsubmit mox /usr/sbin/sendmail
1346 touch /etc/moxsubmit.conf
1347 chown root:moxsubmit /etc/moxsubmit.conf
1348 chmod 640 /etc/moxsubmit.conf
1349 # edit /etc/moxsubmit.conf
1352 usage: mox sendmail [-Fname] [ignoredflags] [-t] [<message]
1356Check the status of IP for the policy published in DNS for the domain.
1358IPs may be allowed to send for a domain, or disallowed, and several shades in
1359between. If not allowed, an explanation may be provided by the policy. If so,
1360the explanation is printed. The SPF mechanism that matched (if any) is also
1363 usage: mox spf check domain ip
1367Lookup the SPF record for the domain and print it.
1369 usage: mox spf lookup domain
1373Parse the record as SPF record. If valid, nothing is printed.
1375 usage: mox spf parse txtrecord
1379Lookup the TLSRPT record for the domain.
1381A TLSRPT record typically contains an email address where reports about TLS
1382connectivity should be sent. Mail servers attempting delivery to our domain
1383should attempt to use TLS. TLSRPT lets them report how many connection
1384successfully used TLS, and how what kind of errors occurred otherwise.
1386 usage: mox tlsrpt lookup domain
1388# mox tlsrpt parsereportmsg
1390Parse and print the TLSRPT in the message.
1392The report is printed in formatted JSON.
1394 usage: mox tlsrpt parsereportmsg message ...
1398Prints this mox version.
1404Lists available methods, prints request/response parameters for method, or calls a method with a request read from standard input.
1406 usage: mox webapi [method [baseurl-with-credentials]
1410List available examples, or print a specific example.
1412 usage: mox example [name]
1414# mox bumpuidvalidity
1416Change the IMAP UID validity of the mailbox, causing IMAP clients to refetch messages.
1418This can be useful after manually repairing metadata about the account/mailbox.
1420Opens account database file directly. Ensure mox does not have the account
1421open, or is not running.
1423 usage: mox bumpuidvalidity account [mailbox]
1427Reassign UIDs in one mailbox or all mailboxes in an account and bump UID validity, causing IMAP clients to refetch messages.
1429Opens account database file directly. Ensure mox does not have the account
1430open, or is not running.
1432 usage: mox reassignuids account [mailboxid]
1436Fix inconsistent UIDVALIDITY and UIDNEXT in messages/mailboxes/account.
1438The next UID to use for a message in a mailbox should always be higher than any
1439existing message UID in the mailbox. If it is not, the mailbox UIDNEXT is
1442Each mailbox has a UIDVALIDITY sequence number, which should always be lower
1443than the per-account next UIDVALIDITY to use. If it is not, the account next
1444UIDVALIDITY is updated.
1446Opens account database file directly. Ensure mox does not have the account
1447open, or is not running.
1449 usage: mox fixuidmeta account
1453Ensure message sizes in the database matching the sum of the message prefix length and on-disk file size.
1455Messages with an inconsistent size are also parsed again.
1457If an inconsistency is found, you should probably also run "mox
1458bumpuidvalidity" on the mailboxes or entire account to force IMAP clients to
1461 usage: mox fixmsgsize [account]
1465Parse all messages in the account or all accounts again.
1467Can be useful after upgrading mox with improved message parsing. Messages are
1468parsed in batches, so other access to the mailboxes/messages are not blocked
1469while reparsing all messages.
1471 usage: mox reparse [account]
1475Ensure messages in the database have a pre-parsed MIME form in the database.
1477 usage: mox ensureparsed account
1479 store new parsed message for all messages
1481# mox recalculatemailboxcounts
1483Recalculate message counts for all mailboxes in the account, and total message size for quota.
1485When a message is added to/removed from a mailbox, or when message flags change,
1486the total, unread, unseen and deleted messages are accounted, the total size of
1487the mailbox, and the total message size for the account. In case of a bug in
1488this accounting, the numbers could become incorrect. This command will find, fix
1491 usage: mox recalculatemailboxcounts account
1495Parse message, print JSON representation.
1497 usage: mox message parse message.eml
1499 check if message needs smtputf8
1501# mox reassignthreads
1503Reassign message threads.
1505For all accounts, or optionally only the specified account.
1507Threading for all messages in an account is first reset, and new base subject
1508and normalized message-id saved with the message. Then all messages are
1509evaluated and matched against their parents/ancestors.
1511Messages are matched based on the References header, with a fall-back to an
1512In-Reply-To header, and if neither is present/valid, based only on base
1515A References header typically points to multiple previous messages in a
1516hierarchy. From oldest ancestor to most recent parent. An In-Reply-To header
1517would have only a message-id of the parent message.
1519A message is only linked to a parent/ancestor if their base subject is the
1520same. This ensures unrelated replies, with a new subject, are placed in their
1523The base subject is lower cased, has whitespace collapsed to a single
1524space, and some components removed: leading "Re:", "Fwd:", "Fw:", or bracketed
1525tag (that mailing lists often add, e.g. "[listname]"), trailing "(fwd)", or
1526enclosing "[fwd: ...]".
1528Messages are linked to all their ancestors. If an intermediate parent/ancestor
1529message is deleted in the future, the message can still be linked to the earlier
1530ancestors. If the direct parent already wasn't available while matching, this is
1531stored as the message having a "missing link" to its stored ancestors.
1533 usage: mox reassignthreads [account]
1537// NOTE: DO NOT EDIT, this file is generated by gendoc.sh.