A client needs a mailing-list server for community discussion, announcement broadcasts, or internal staff lists, and Mailman 3 is the obvious open-source answer. The catch is that Mailman 3 is not one daemon — it is the Core engine plus a Django app for the admin UI (Postorius) plus a second Django app for the searchable archive (HyperKitty). This article is the install procedure we run for the engagements that need a self-hosted list manager, with the Postfix wiring and the deliverability checks that the upstream docs hand-wave.
How to verify
Audit the host before installing — Mailman 3 needs a real database, a working MTA, and Python 3.9+.
lsb_release -d
python3 --version
systemctl is-active postfix
psql --version 2>/dev/null || mariadb --version
dig +short MX example.com
hostname -f
The FQDN must match the MX record and the PTR — Mailman injects a List-Id based on the host, and broken DNS will cascade into every list message being marked spam.
What’s happening
Mailman 3 is three moving parts plus the MTA:
- Mailman Core (
mailmanpackage) — the actual list engine. Runs as a daemon, exposes a REST API on localhost:8001, talks to Postfix via LMTP on port 8024. - Postorius — Django app that is the admin UI and the per-user subscription/preferences front-end.
- HyperKitty — Django app that ingests every list message and stores it in a searchable archive.
- Postfix — the MTA that accepts mail addressed to the list and hands it off to Mailman Core via LMTP.
The database can be SQLite (development only), PostgreSQL (recommended), or MariaDB. Core and the two Django apps each have their own schema; Postorius and HyperKitty typically share a Django database, separate from Core’s.
The mail flow: a user emails discuss@lists.example.com. Postfix accepts (transport map points the recipient domain at LMTP). Mailman Core receives the message, checks subscription, runs moderation, expands the recipient list, and queues the broadcast back through Postfix for outbound delivery. HyperKitty’s archiver hooks in via the Core REST API and stores a copy for the archive.
The procedure
-
Install Mailman Core and dependencies. On Ubuntu 22.04 / 24.04 the upstream Debian package is several versions behind — use pip in a venv for production:
sudo apt update sudo apt install -y python3-venv python3-dev libpq-dev gcc postgresql nginx sudo useradd --system --home-dir /opt/mailman3 --create-home --shell /bin/bash mailman sudo -u mailman python3 -m venv /opt/mailman3/venv sudo -u mailman /opt/mailman3/venv/bin/pip install \ mailman mailman-web postorius hyperkitty psycopg2-binary gunicorn -
Create the databases. Two databases — one for Core, one shared by Postorius and HyperKitty:
sudo -u postgres psql <<SQL CREATE USER mailman WITH PASSWORD '$(openssl rand -hex 16)'; CREATE DATABASE mailman_core OWNER mailman; CREATE DATABASE mailman_web OWNER mailman; SQLStore the password in your secrets manager — Core and Web config files will both reference it.
-
Configure Mailman Core. Edit
/opt/mailman3/var/etc/mailman.cfg:[mailman] site_owner: postmaster@example.com default_language: en [database] class: mailman.database.postgresql.PostgreSQLDatabase url: postgresql://mailman:$PASSWORD@localhost/mailman_core [mta] incoming: mailman.mta.postfix.LMTP outgoing: mailman.mta.deliver.deliver lmtp_host: 127.0.0.1 lmtp_port: 8024 smtp_host: 127.0.0.1 smtp_port: 25 configuration: /opt/mailman3/var/etc/postfix-mailman.cfg [webservice] hostname: 127.0.0.1 port: 8001 admin_user: restadmin admin_pass: $(openssl rand -hex 24)Then start Core under systemd — a unit file pointing at
/opt/mailman3/venv/bin/mailman startrunning as themailmanuser. The first start initializes the schema. -
Wire Postfix to Mailman Core via LMTP. Mailman writes the Postfix maps automatically when lists are created; you tell Postfix where to find them. In
/etc/postfix/main.cf:transport_maps = hash:/etc/postfix/transport, hash:/opt/mailman3/var/data/postfix_lmtp local_recipient_maps = proxy:unix:passwd.byname, $alias_maps, hash:/opt/mailman3/var/data/postfix_lmtp relay_domains = $mydestination, hash:/opt/mailman3/var/data/postfix_domainsReload Postfix and confirm a
postmap -q lists.example.com /opt/mailman3/var/data/postfix_domainsreturns OK. -
Install and configure the web stack. Create
/opt/mailman3/web/settings.pyfrom themailman-webtemplate, set the database, secret key, and allowed hosts:DATABASES = { 'default': { 'ENGINE': 'django.db.backends.postgresql', 'NAME': 'mailman_web', 'USER': 'mailman', 'PASSWORD': os.environ['MM_DB_PASSWORD'], 'HOST': 'localhost', } } ALLOWED_HOSTS = ['lists.example.com'] MAILMAN_REST_API_URL = 'http://127.0.0.1:8001' MAILMAN_REST_API_USER = 'restadmin' MAILMAN_REST_API_PASS = os.environ['MM_REST_PASSWORD']Run migrations and create the admin user:
sudo -u mailman /opt/mailman3/venv/bin/python /opt/mailman3/web/manage.py migrate sudo -u mailman /opt/mailman3/venv/bin/python /opt/mailman3/web/manage.py createsuperuser sudo -u mailman /opt/mailman3/venv/bin/python /opt/mailman3/web/manage.py collectstatic --noinput -
Front the Django app with Nginx and TLS. A systemd unit runs Gunicorn bound to
127.0.0.1:8000; Nginx terminates TLS on 443 and proxies. Certificate from Let’s Encrypt:sudo certbot certonly --nginx -d lists.example.comNginx server block proxies
/to Gunicorn, serves/static/from the collected static directory, and addsX-Forwarded-Proto httpsso Django generates absolute URLs correctly. -
Create the first list and send a smoke probe. From the CLI:
sudo -u mailman /opt/mailman3/venv/bin/mailman create discuss@lists.example.com echo "first post" | mail -s "list smoke" discuss@lists.example.com sudo journalctl -u postfix -u mailman -fSubscribe yourself via Postorius, send a test, and confirm the message lands in HyperKitty’s archive.
Operational notes
- Run Mailman Core and the Django apps as the same
mailmansystem user so file permissions on the var directory stay consistent across upgrades. - The Django web app keeps a session-based cache of REST API responses; restarting Core invalidates everything — bounce the Gunicorn unit too if you change Core’s auth credentials.
- HyperKitty’s archive grows roughly 1 KB per message stored, plus index overhead — on busy lists, the database hits double-digit GB within a year. Plan a separate volume for
/var/lib/postgresqland runVACUUMon a cron. - Mailman writes outbound mail with the list’s own
From:(DMARC-mitigation mode) when the original sender’s domain enforces DMARC reject — this is configurable per list underdmarc_mitigate_action. Without it, every Gmail/Outlook subscriber loses messages from DMARC-strict domains. - Bounce processing in Mailman 3 is automatic — repeated bounces unsubscribe the address. Tune
bounce_score_thresholdper list; the default is aggressive for low-volume lists.
Common pitfalls
- Installing the Ubuntu
mailman3-fullpackage on 22.04 pulls a Debian-packaged version with conflicting config paths from the upstream pip install — pick one strategy and stick with it; mixing causes the daemon to lose track of its var directory. - The Postfix
local_recipient_mapsline is forgotten and Postfix rejects every list message withUser unknown in local recipient tablebefore Mailman even sees the message. - The
transport_mapsandlocal_recipient_mapsfiles are auto-regenerated by Mailman; editing them by hand has no effect — manage list-domains in Mailman, not Postfix. - Postorius admin UI hangs at “loading” because the Django app can’t reach Core’s REST API — usually a missing
MAILMAN_REST_API_URLor a Core daemon that’s down. Checkcurl -u restadmin:pass http://127.0.0.1:8001/3.0/system/versions. - The DKIM signature applied by the host MTA does not cover the modifications Mailman makes to the message (subject prefix, list footers) — Mailman 3 has built-in
arc_enabledsupport, but the simpler fix is ARC sealing at the outbound edge before Postfix re-signs.
Stack Harbor stands up Mailman 3 as a single contracted deployment in the engagements we run that need self-hosted lists — Core under systemd, Postfix wiring auto-generated and verified, Django apps behind authenticated Nginx with monthly Django security patches in the upgrade window, and archive volume on a separate disk with a retention policy. If you have a Mailman 2 install that nobody dares upgrade or a Mailman 3 that drifted away from its upstream releases, that re-baselining work is part of our Managed Operations practice.