Skip to content

Mailman 3 mailing-list server install on Ubuntu

A working Mailman 3 deployment on Ubuntu — Core engine, Postorius admin UI, HyperKitty archives, Postfix integration, and the operational checks that keep lists deliverable.

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 (mailman package) — 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

  1. 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
  2. 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;
    SQL

    Store the password in your secrets manager — Core and Web config files will both reference it.

  3. 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 start running as the mailman user. The first start initializes the schema.

  4. 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_domains

    Reload Postfix and confirm a postmap -q lists.example.com /opt/mailman3/var/data/postfix_domains returns OK.

  5. Install and configure the web stack. Create /opt/mailman3/web/settings.py from the mailman-web template, 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
  6. 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.com

    Nginx server block proxies / to Gunicorn, serves /static/ from the collected static directory, and adds X-Forwarded-Proto https so Django generates absolute URLs correctly.

  7. 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 -f

    Subscribe 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 mailman system 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/postgresql and run VACUUM on 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 under dmarc_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_threshold per list; the default is aggressive for low-volume lists.

Common pitfalls

  • Installing the Ubuntu mailman3-full package 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_maps line is forgotten and Postfix rejects every list message with User unknown in local recipient table before Mailman even sees the message.
  • The transport_maps and local_recipient_maps files 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_URL or a Core daemon that’s down. Check curl -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_enabled support, 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.