Docs Get key
All guides
Bulk email

Self-host listmonk for bulk email

Install listmonk with Docker or a binary, connect SMTP, segment subscribers, and run campaigns through its API with explicit status transitions.

Reviewed

listmonk is a self-hosted newsletter and mailing-list application. It owns subscribers, lists, templates, campaign state, and statistics; it does not deliver mail itself. Choose it when you want a small Go service and PostgreSQL, SQL-based audience queries, and a campaign API your application can drive. This guide installs listmonk, connects a transport, and runs a controlled campaign without treating an API response as proof of delivery.

The trade-off is operational: you run the database, upgrades, backups, and bounce feedback. If you only need to send an occasional edition, a hosted sender is less machinery. For the surrounding architecture, read the bulk email guide and the listmonk vs Keila comparison.

Prerequisites

  • Docker with the Compose plugin, or a server for the listmonk binary.
  • PostgreSQL 12 or newer. The binary installation documentation states this minimum.
  • SMTP credentials from a provider or your own mail transfer agent, plus an authenticated sending domain.
  • A test mailbox you control. Do not use an imported prospect list for the first send.

listmonk’s installation documentation is authoritative for the current release. The project is licensed under the AGPLv3.

Install and start listmonk

The documented container path downloads the project Compose file, which you should review before starting:

curl -LO https://github.com/knadh/listmonk/raw/master/docker-compose.yml
# Replace the sample database credentials, SMTP values, and admin settings.
docker compose up -d

Then open http://localhost:9000 and create the Super Admin user. For a binary installation:

./listmonk --new-config   # writes config.toml; edit database and SMTP values
./listmonk --install      # creates tables in the configured PostgreSQL database
./listmonk

--install initializes the schema; it does not start a mail server. Pin a versioned image or binary release for production rather than tracking latest, and keep the database plus uploaded media in your backup plan.

Connect a transport and feedback path

SMTP is the default messenger. Configure it in the admin settings or config.toml, then send one message to your controlled mailbox and inspect the headers. Custom HTTP messengers are an extension point, but they do not remove the need for SPF, DKIM, DMARC, and a working bounce path.

listmonk’s concepts documentation separates a subscriber record from list membership: one address can belong to several lists with different subscription states. Use double opt-in for public signup forms and keep the confirmation evidence. Imported addresses need a lawful basis, not just a successful CSV parse.

Bounce processing can read a POP mailbox or supported provider feedback. Configure one before a real campaign. An unprocessed bounce list quietly damages sender reputation and keeps invalid addresses in the next audience query.

Build the audience before the campaign

Subscribers carry arbitrary JSON attributes, and listmonk can evaluate partial PostgreSQL SQL expressions over them. That is the feature to choose it for, and also the risk: a query typo can select the wrong people. Run the segment query against a small test list, inspect the count, and compare it with an export before scheduling a campaign.

Treat each list as an eligibility boundary, not a tag. Confirm that unsubscribed and unconfirmed addresses are excluded by the campaign’s list selection rather than by a later manual cleanup.

Run a campaign through the API

Create an API user with the permissions your integration needs, then create a draft campaign. The request below follows the documented campaign API; replace the URL, credentials, list ID, and content:

curl -u "api_user:token" 'http://localhost:9000/api/campaigns' \
  -X POST -H 'Content-Type: application/json;charset=utf-8' \
  --data-raw '{
    "name": "Controlled test campaign",
    "subject": "A controlled listmonk test",
    "lists": [1],
    "from_email": "News <news@your-sending-domain.example>",
    "content_type": "richtext",
    "type": "regular",
    "body": "This is a controlled test message."
  }'

Use the test endpoint with an explicit subscriber address before changing campaign status. The documentation says to repeat the campaign fields and add subscribers:

curl -u "api_user:token" -X POST \
  'http://localhost:9000/api/campaigns/1/test' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "name": "Controlled test campaign",
    "subject": "A controlled listmonk test",
    "lists": [1],
    "from_email": "News <news@your-sending-domain.example>",
    "content_type": "richtext",
    "type": "regular",
    "body": "This is a controlled test message.",
    "subscribers": ["test-listmonk@mailkite.dev"]
  }'

Starting a send is a status transition, not a free-form field update. The API documents these rules: only a draft can become scheduled, only a draft or paused campaign can start running, and only a running campaign can pause or cancel. A scheduled campaign is also the only state that can return to draft.

curl -u "api_user:token" -X PUT \
  'http://localhost:9000/api/campaigns/1/status' \
  -H 'Content-Type: application/json' \
  --data-raw '{"status":"running"}'

Record the campaign ID and status before the request. If the connection times out, query the campaign rather than repeating the transition blindly.

Operate campaigns and recover

Watch to_send, sent, and campaign analytics. A running campaign can be paused or canceled, but cancellation cannot recall messages already accepted by the SMTP transport. Delivered, bounced, and complained are later states that come from the transport and feedback path, not from the campaign row alone.

Back up PostgreSQL and uploaded assets together. Upgrade on a restored copy first, and check the release notes for schema changes. A container that starts with an empty database is not a recovery.

Where MailKite fits

MailKite, which we build, provides hosted batches and broadcasts, so you do not operate PostgreSQL or the campaign worker. Its terms prohibit unsolicited bulk or commercial mail, sending without consent, and sending after opt-out. A batch endpoint is not permission to import a prospect list.

If you want to keep audience state but stop running delivery infrastructure, compare programmatic newsletters and the MailKite sending documentation. Moving a listmonk campaign to another transport requires rechecking consent, suppressions, templates, and campaign state; it is not an in-place failover.

Next steps

Sources reviewed 2026-11-07: listmonk installation, concepts, campaign API, and the license.