Configuring Mailman Core

If you are here, it means that you have successfully installed complete Mailman 3 or some of its components. To verify that you have Mailman Core installed try:

$ mailman info
GNU Mailman 3.1.0 (Between The Wheels)
Python 3.5.3 (default, Jan 19 2017, 14:11:04)
[GCC 6.3.0 20170118]
config file: /etc/mailman.cfg
db url: sqlite:////var/lib/mailman/data/mailman.db
devmode: DISABLED
REST root url: http://localhost:8001/3.1/
REST credentials: restadmin:restpass

There are a few important parameters in the above command that can help you debug problems if they occur. Most important of which is the configuration file that is being used, pointed to by config_file that you see above.

Mailman 3 uses a total of two main configuration files, the first one is for Mailman Core and the other is Django’s used to deploy the web front end.

mailman.cfg is the main configuration file for Mailman Core. Core will look for this file at several different places in order like:

  • Filesystem Path pointed to by MAILMAN_CONFIG_FILE environment variable.

  • mailman.cfg in the current working directory.

  • var/etc/mailman.cfg relative to the current working directory.

  • $HOME/.mailman.cfg

  • /etc/mailman.cfg

  • ../../etc/mailman.cfg relative to the working directory of argv[0] i.e. the working directory of the mailman command script.

Alternatively, you can specify the absolute path of the configuration file using the -C flag in the command line.

Configuring Filesystem Paths

Mailman by default puts all the configuration, logs and lock files in the current working directory under a var directory. Each var directory belongs to either a running or previously run Mailman Core instance.

While it is often confusing to several people, the reason it is default is because it helps a lot with debugging and testing. In production you want a static location for your configuration, locks and logs.

All the different paths that Mailman creates are, by default, configured relative to var_dir. For example, paths.fhs which is based on Filesystem Hierarchy Standard . To use it add the following to your configuration:

layout: fhs

This is equivalent to the following configuration:

bin_dir: /sbin
var_dir: /var/lib/mailman
queue_dir: /var/spool/mailman
log_dir: /var/log/mailman
lock_dir: /var/lock/mailman
etc_dir: /etc
ext_dir: /etc/mailman.d
pid_file: /var/run/mailman/

Most of the path names are self explanatory, like all the runnable scripts are put under /sbin and all the logs are placed under /var/log/mailman.

If you want a custom directory layout you can define a new layout and use that instead. For example:

var_dir: /home/user/.mailman

layout: custom

If you are installing Mailman from source (or using Pip), it is recommended to use paths.local. To use it, add the following to your mailman.cfg:

layout: local

It is equivalent to the following configuration:

var_dir: /var/tmp/mailman
bin_dir: $argv
log_dir: $var_dir/logs
lock_dir: $var_dir/locks
data_dir: $var_dir/data
cache_dir: $var_dir/cache
etc_dir: $var_dir/etc
messages_dir: $var_dir/messages
archive_dir: $var_dir/archives
template_dir: $var_dir/templates
pid_file: $var_dir/
lock_file: $lock_dir/master.lck

Configuring MTA

The first step to get Core to work is to enable it to talk to the Mail Transport Agent or MTA. It supports various different MTAs.


Core automatically generated transport maps(postfix_lmtp and postfix_lmtp) to be used by Postfix at var/data/. To configure Postfix, add the following configuration to

# Support the default VERP delimiter.
recipient_delimiter = +
unknown_local_recipient_reject_code = 550
owner_request_special = no
transport_maps =
local_recipient_maps =
relay_domains =

Mailman’s var directory can vary according your source of installation. Please refer to the documentation provided with your source or ask Mailman Developers at

Note that in the above, if your current contains settings for these items, including the default setting for local_recipient_maps, you should add the Mailman setting to the existing setting rather than replacing it. For example:

local_recipient_maps = proxy:unix:passwd.byname $alias_maps

To configure Core to use Postfix, add the following configuration to your mailman.cfg configuration, be sure to replace with your email domain:

incoming: mailman.mta.postfix.LMTP
outgoing: mailman.mta.deliver.deliver
lmtp_port: 8024
smtp_port: 25

To setup Exim4, add the following files to your configuration as file names mentioned above:

# /etc/exim4/conf.d/main/25_mm3_macros
# The colon-separated list of domains served by Mailman.


# MM3_HOME must be set to Mailman's var directory, wherever it is
# according to your installation. If you are following these instructions
# on Debian, it might be MM3_HOME=/opt/mailman/mm/var, for example.

# The configuration below is boilerplate:
# you should not need to change it.

# The path to the list receipt (used as the required file when
# matching list addresses)

# /etc/exim4/conf.d/router/455_mm3_router
driver = accept
domains = +mm_domains
require_files = MM3_LISTCHK
local_part_suffix = \
-bounces   : -bounces+* : \
-confirm   : -confirm+* : \
-join      : -leave     : \
-owner     : -request   : \
-subscribe : -unsubscribe
transport = mailman3_transport

# /etc/exim4/conf.d/transport/55_mm3_transport
driver = smtp
protocol = lmtp
hosts = localhost
port = MM3_LMTP_PORT
rcpt_include_affixes = true

You should note that Exim4 configuration above doesn’t support multiple domains like Postfix does. Please change the variables in the configuration above before installing it.

To configure Mailman to use Exim4 add the following to your mailman.cfg

incoming: mailman.mta.exim4.LMTP
outgoing: mailman.mta.deliver.deliver
lmtp_port: 8024
smtp_port: 25
Other MTAs

Mailman also supports Sendmail and qmail. Please check the Mailman Core documentation for sendmail setup and qmail setup to configure them.

Configuring REST API

Core presents a HTTP Rest API which clients can use to interact with it. Note that this is an administrative API and must not be exposed to the public internet. It has a very basic HTTP Basic Authentication which can be configured using the configuration below:

hostname: localhost
port: 8001
use_https: no
admin_user: restadmin
admin_pass: restpass
api_version: 3.1

If you need to bind to a different host or port, you can change the configuration above according to you needs.

There are several different other ways to configure Core and you can find more details about it in the Core’s documentation.

Configure Templates

You can configure templates for headers, footers and automated emails generated by Mailman. By default, the only templates available are in English, but you can add them other languages too. You can add templates to the var directory of Mailman, which will be picked up by Core.

  • sitewide templates can be put in $var/templates/site/LC/,

  • domain specific templates in var/templates/domains/DOMAIN/LC/

  • list specific templates invar/templates/lists/LIST-ID/LC/

List overrides domain overrides site overrides defaults.

Configuring Databases

Core supports Sqlite, PostgreSQL and MySQL and each of them are tested. By default, without any configuration, Core uses Sqlite database. For a production use, a more efficient database like PostgreSQL or MySQL is highly recommended. Please have a look at the setting up your database in Core’s documentation for the same.

Configuring Cron Jobs

Depending on your configuration, Core has some periodic tasks that need to be run using job schedulers like cron. Right now, the two tasks required to be run routinely for Core are periodic sending of digests for mailing lists that have digest_send_periodic set to true and periodic sending of notices of pending requests to list moderators. These can be customized to send at any periodic time, the following format sends out digests at midnight:

@daily /path/to/mailman digests --periodic

This format will send moderator notices at 08:00:

0 8 * * * /path/to/mailman notify

If your installation has lists which make use of the NNTP Gateway to gate messages from Usenet to one or more lists, you also need to periodically run the mailman gatenews command to gate messages from Usenet to the list(s). This format will run the command every 5 minutes:

*/5 * * * * /path/to/mailman gatenews


Be careful about mailman.cfg locations.

If your mailman.cfg is not found in a standard location, mailman will silently write a new emtpy mailman.cfg in ~/var/etc and terminate successfully. If your notify and digests jobs are failing silently, try adding the -C option to specify the config file to use.