listmonk: Self-Hosted Newsletter and Mailing List Manager as a Single Binary

What listmonk Is and Who It Targets

listmonk is a standalone, self-hosted newsletter and mailing list manager. The README describes it as fast, feature-rich, and packed into a single binary that uses PostgreSQL as its data store. It provides a web dashboard at port 9000 for creating and managing subscriber lists, designing and sending campaigns, and tracking transactional messages.

The target users are developers, small organizations, and independent publishers who send newsletters or operate mailing lists and want to run their own infrastructure rather than using a software-as-a-service tool. The README states explicitly that listmonk is free and open-source software with no advertising, monetizing, or venture capital. The project received a grant from the NLnet foundation and was built within Zerodha, a financial services company.

The backend is written in Go and the frontend is Vue with Buefy for the UI, as documented in the README. The Go module path is `github.com/knadh/listmonk`. The go.mod file specifies `go 1.26.1` as the minimum Go toolchain version.

Installing listmonk with Docker

The fastest installation path is Docker Compose. The docker-compose.yml in the repository root sets up both the listmonk application and a PostgreSQL database container. The README provides the following commands:

curl -LO https://github.com/knadh/listmonk/raw/master/docker-compose.yml
docker compose up -d

After startup, visit `http://localhost:9000` to access the dashboard. The compose file exposes port 9000 externally. The application container runs the install and upgrade steps automatically on first start through the command:

./listmonk --install --idempotent --yes --config '' && ./listmonk --upgrade --yes --config ''

The `--install --idempotent` flag ensures database setup runs only once on an empty database. The `--upgrade` flag runs any pending database migrations automatically when a new image is pulled. The `--config ''` argument tells listmonk to read configuration entirely from environment variables rather than from a config file, which the compose file supplies as `LISTMONK_app__address`, `LISTMONK_db__*`, and similar variables.

All `LISTMONK_*` environment variables also support a `_FILE` suffix pattern for loading secrets from files, supporting Docker secrets and Podman secret mounts.

Installing listmonk as a Binary

For environments without Docker, listmonk distributes standalone binaries from the GitHub releases page. The setup sequence from the README is:

./listmonk --new-config

This generates a `config.toml` file. Edit it to provide the PostgreSQL connection details and the application address. Then initialize the database:

./listmonk --install

Finally, start the application:

./listmonk

For upgrades, run `./listmonk --upgrade` before restarting. The README notes that upgrades are idempotent: running the upgrade command multiple times has no side effects. The repository includes `listmonk.service` and `[email protected]` systemd unit files for running listmonk as a Linux system service. The Dockerfile uses an Alpine base image, installs ca-certificates, tzdata, shadow, and su-exec, and copies the listmonk binary and the sample config file directly.

Configuration and the TOML Format

listmonk reads configuration from `config.toml` when started with a file path, or from environment variables when the config path is set to empty. The repository includes `config.toml.sample` as a reference. Environment variables follow the `LISTMONK_section__key` pattern, where double underscores separate the TOML section from the key name.

The go.mod file shows several configuration-related libraries from the same author: koanf is used for configuration loading and supports TOML files, environment variables, command-line flags, and raw byte providers. The `knadh/smtppool/v2` library handles the SMTP connection pool for sending email. The `knadh/paginator` library provides query pagination. These are all first-party libraries maintained alongside listmonk.

The `queries/` directory in the repository holds SQL query files that knadh/goyesql loads at runtime. This is an unusual design: SQL queries are stored in `.sql` files rather than inline strings, which keeps query logic separate from Go code and makes them easier to inspect. The `schema.sql` file in the repository root defines the PostgreSQL schema.

Feature Set: Subscribers, Campaigns, and Transactional Email

listmonk manages subscriber lists, sends bulk campaigns, handles opt-in and opt-out flows, and supports transactional messages. The feature set is documented at listmonk.app, which the README references for the full documentation and a live demo at demo.listmonk.app.

The go.mod file reveals several capabilities through its dependencies. The `coreos/go-oidc/v3` package indicates OIDC single sign-on support. The `altcha-org/altcha-lib-go` package suggests bot protection for subscription forms. The `pquerna/otp` package indicates two-factor authentication support for the admin dashboard. The `emersion/go-message` package handles MIME message construction. The `knadh/go-pop3` package suggests POP3-based bounce handling.

The i18n directory and the `project.inlang.json` configuration file indicate that the frontend interface supports multiple languages. The `permissions.json` file in the repository root defines the role-based permission model for the admin dashboard.

Limitations and the AGPL-3.0 License Implications

listmonk manages campaigns and dispatches email through an external SMTP provider. It does not include its own mail transfer agent. Teams adopting listmonk need to configure a transactional email provider (such as Amazon SES, Postfix, or a commercial SMTP relay) separately. listmonk handles list hygiene, campaign scheduling, and tracking; email deliverability is the responsibility of the SMTP layer.

listmonk is not a SaaS product. There is no hosted version, no support contract, and no managed infrastructure. Teams that need someone else to run the service must either build that capability themselves or use a managed self-hosting service.

The license is AGPL-3.0. This has a practical consequence for commercial SaaS products: if a company deploys a modified version of listmonk to users over a network, the source code of those modifications must be made available. Internal deployments and unmodified deployments are unaffected by this requirement. Teams building a competing newsletter product on top of listmonk should verify the license implications with legal counsel.

Comparison with Mailchimp and Other Alternatives

listmonk occupies a different tier from Mailchimp, which is a cloud SaaS platform with managed deliverability, audience segmentation tools, and per-subscriber pricing. listmonk offers none of the managed infrastructure, but also has none of the per-subscriber costs after the initial server setup.

Within the self-hosted newsletter category, Mautic is a common alternative. Mautic is a PHP-based marketing automation platform with a broader feature set including CRM, landing pages, and behavioral tracking. listmonk focuses specifically on newsletters and mailing lists: it does not include CRM features or behavioral marketing automation. The single-binary distribution and the Go runtime make listmonk considerably simpler to deploy and operate than Mautic, which requires a PHP stack, a web server, and a database.

v6.2.0 is the current stable release, dated 2026-06-26. Nightly releases are available from the repository and are tagged with the build date. The last push to the repository was on 2026-09-25. The project is actively maintained.

Editorial conclusion

listmonk is the right choice for teams and individuals who want full control over their mailing list data and do not want to pay per-subscriber fees to a managed service. The single-binary distribution and Docker Compose setup make deployment straightforward on any Linux server. It is not the right choice for users who need hosted infrastructure, a managed SMTP relay, or enterprise SLAs: listmonk provides the application but not the email delivery layer. Before adopting it, verify that PostgreSQL is available in your infrastructure and that you have a reliable transactional email provider to connect it to, since listmonk handles list management and campaign dispatch but not email deliverability. The AGPL-3.0 license requires that modifications to listmonk that are deployed over a network be released as open source.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes