> ## Content Index
> Fetch the complete content index at: https://blog.uptime.bet/llms.txt
> Use this file to discover other available public pages before exploring further.

# listmonk: Self-Host Your Own Newsletter and Mailing List Manager with Docker Compose
- URL: https://blog.uptime.bet/listmonk-self-hosted-newsletter-mailing-list-manager-docker/
- Published: 2026-11-19T08:00:00.000Z
- Updated: 2026-11-19T08:00:00.000Z
- Description: listmonk is an AGPL-licensed, self-hosted newsletter and mailing list manager that ships as a single Go binary next to PostgreSQL. Here's what it can do, what the v7 beta changes, and how to run the stable v6.2.0 with Docker Compose.
- Author: Alexandre Nebeling
- Tags: Trending, Email, Self-Hosted, Open Source, Docker, Homelab, Automation

Newsletters are having a moment again, and most people start them on a hosted platform. That works fine until the subscriber count grows and the monthly bill grows with it, or until you realize your audience list lives on someone else's server. If you already run a homelab or a small VPS, there is a well-established alternative: **listmonk**.

listmonk has been around since 2018, sits at roughly 24,000 GitHub stars, and is currently in the middle of its biggest release cycle so far: **v7.0.0-beta.2** landed on 10 November 2026 with a completely rebuilt admin UI, while **v6.2.0** remains the latest stable release. A good moment to take a proper look.

## What is listmonk?

[listmonk](https://github.com/knadh/listmonk?ref=blog.uptime.bet) is a self-hosted newsletter and mailing list manager. The whole application is a **single binary** written in Go (the current admin frontend is Vue), and the only dependency is a **PostgreSQL** database. It is developed by Kailash Nadh and published under the **GNU AGPL v3**, an OSI-approved copyleft license.

It covers two jobs that are usually split across different tools:

- **Campaigns**: classic newsletters and one-way mailing lists, sent to single or double opt-in lists.
- **Transactional messages**: a simple HTTP API (`POST /api/tx`) that sends a predefined template to one or more subscribers, for example sign-up confirmations from your own app.

The project's own website mentions a production instance sending a campaign to more than 7 million recipients using a fraction of one CPU core and a peak of 57 MB of RAM. Your homelab newsletter with 300 readers will not stress it.

![The listmonk campaign editor with the visual drag-and-drop e-mail builder and a style panel](https://blog.uptime.bet/content/images/2026/11/listmonk-visual-builder.webp)

Composing a campaign with the drag-and-drop visual e-mail builder in listmonk. [Source: knadh/listmonk on GitHub](https://github.com/knadh/listmonk?ref=blog.uptime.bet) (AGPL-3.0)

## Key features

- **Lists and subscribers**: single and double opt-in lists, CSV imports, blocklisting, and segmentation with **SQL expressions** against subscriber fields and arbitrary JSON attributes (for example `subscribers.attribs->>'city' = 'Berlin'`).
- **Flexible editors**: write e-mails with a drag-and-drop visual builder, a WYSIWYG editor, Markdown, raw HTML or plain text.
- **Templating**: Go templates plus 100+ Sprig functions in subjects and bodies, e.g. `{{ .Subscriber.Name }}`.
- **Performance controls**: multi-threaded queues, multiple SMTP servers, and throughput and sliding-window rate limits.
- **Analytics**: campaign views, clicks, bounces and top links.
- **Bounce processing**: a POP3 bounce mailbox or webhooks, including built-in endpoints for Amazon SES, SendGrid and Postmark.
- **Messengers**: besides SMTP, listmonk can POST campaign messages as JSON to a webhook, so you can bridge to SMS, push notifications or chat.
- **Access control**: users with granular roles and permissions, scoped API tokens, and **OIDC single sign-on**.
- **Media and privacy**: a built-in media library (local or S3-compatible storage), and subscribers can export or delete their own data.

## What's coming in v7

The v7 betas replace the old Vue admin with a new, lightweight interface. According to the release notes, the admin bundle shrinks by almost 80%, and the UI gets native dark mode, a better mobile view, bookmarkable filters, standalone pages for lists and subscribers, new list and campaign overview pages with analytics, multiple "From" addresses and automatic OIDC role mapping. The TinyMCE rich-text editor is replaced by the much smaller Squire editor.

There are **breaking changes**, though: `app.from_email` becomes an array, the bounce settings structure changes, Amazon SES webhooks now need allowed SNS topic ARNs, Azure webhooks need a shared secret, and the transactional API needs the `subscribers:get` permission to target existing subscribers. If you want to try it, the Docker tag is `listmonk/listmonk:beta`. For anything that sends real mail, I would stay on v6.2.0 for now.

## Why self-host your newsletter?

- **You own the list.** Subscribers, consent and history sit in your own PostgreSQL database.
- **Cost scales with your mail provider, not your subscriber count.** listmonk itself is free; you pay only for the SMTP relay you choose.
- **One tool for newsletters and app mail.** The transactional API saves you a second service for notification mails from your own projects.

## Installing listmonk with Docker Compose

The project ships an official `docker-compose.yml`. Below is a slightly hardened version of it: pinned to **v6.2.0**, database credentials moved into a `.env` file, and Postgres not published on the host at all (the official file binds it to `127.0.0.1:5432`).

### 1\. Create a folder and an `.env` file

```bash
mkdir -p ~/listmonk && cd ~/listmonk
cat > .env <<'ENV'
POSTGRES_PASSWORD=change-me-to-a-long-random-string
LISTMONK_ADMIN_USER=admin
LISTMONK_ADMIN_PASSWORD=change-me-too
ENV
chmod 600 .env

```

`LISTMONK_ADMIN_USER` and `LISTMONK_ADMIN_PASSWORD` are optional: if they are set on the very first start, listmonk creates the Super Admin automatically. Otherwise you create the account in the browser on first visit.

### 2\. Create `docker-compose.yml`

```yaml
services:
  app:
    image: listmonk/listmonk:v6.2.0
    container_name: listmonk_app
    restart: unless-stopped
    ports:
      - "9000:9000"
    hostname: listmonk.example.com
    depends_on:
      db:
        condition: service_healthy
    command: [sh, -c, "./listmonk --install --idempotent --yes --config '' && ./listmonk --upgrade --yes --config '' && ./listmonk --config ''"]
    environment:
      LISTMONK_app__address: 0.0.0.0:9000
      LISTMONK_db__user: listmonk
      LISTMONK_db__password: ${POSTGRES_PASSWORD}
      LISTMONK_db__database: listmonk
      LISTMONK_db__host: db
      LISTMONK_db__port: 5432
      LISTMONK_db__ssl_mode: disable
      LISTMONK_db__max_open: 25
      LISTMONK_db__max_idle: 25
      LISTMONK_db__max_lifetime: 300s
      TZ: Etc/UTC
      LISTMONK_ADMIN_USER: ${LISTMONK_ADMIN_USER:-}
      LISTMONK_ADMIN_PASSWORD: ${LISTMONK_ADMIN_PASSWORD:-}
    volumes:
      - ./uploads:/listmonk/uploads:rw

  db:
    image: postgres:17-alpine
    container_name: listmonk_db
    restart: unless-stopped
    environment:
      POSTGRES_USER: listmonk
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: listmonk
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U listmonk"]
      interval: 10s
      timeout: 5s
      retries: 6
    volumes:
      - listmonk-data:/var/lib/postgresql/data

volumes:
  listmonk-data:

```

The `command` line comes straight from the official file: `--install --idempotent` sets up the database schema only on the first start, and `--upgrade` runs migrations automatically whenever you pull a newer image. `--config ''` tells listmonk to take its configuration purely from the `LISTMONK_*` environment variables (dots in config keys become double underscores, so `db.host` becomes `LISTMONK_db__host`).

### 3\. Start it

```bash
docker compose up -d
docker compose logs -f app

```

Then open `http://<your-server>:9000/admin` and log in.

## First configuration steps

1. **Root URL**: in *Settings → General*, set the public URL of the installation (no trailing slash), e.g. `https://newsletter.example.com`. Subscription links, tracking links and unsubscribe links are built from it.
2. **SMTP**: add your mail relay in *Settings → SMTP*. If you run your own mail server, see our [Stalwart guide](https://blog.uptime.bet/stalwart-self-hosted-mail-server-docker/), but for bulk mail a dedicated relay with good reputation is usually the safer choice. Make sure SPF, DKIM and DMARC are set up for your sending domain.
3. **Media uploads**: the compose file mounts `./uploads`. To use it, set the upload path to `/listmonk/uploads` in *Settings → Media*.
4. **Bounces**: enable bounce processing in *Settings → Bounces*. If you use a POP3 mailbox, the docs explicitly warn to use a dedicated one, because listmonk deletes processed mails from it.
5. **Single sign-on**: if you already run an OIDC provider such as [Pocket ID](https://blog.uptime.bet/pocket-id-self-hosted-passkey-sso-oidc-docker/), configure it in *Settings → Security → OIDC*.

![The listmonk rich-text editor showing a greeting with the template expression for the subscriber name and an embedded image](https://blog.uptime.bet/content/images/2026/11/listmonk-templating.webp)

The rich-text editor with a Go template expression for the subscriber's name. [Source: listmonk.app (knadh/listmonk)](https://listmonk.app/?ref=blog.uptime.bet) (AGPL-3.0)

## Reverse proxy tips

Put listmonk behind your usual reverse proxy with TLS. The configuration docs list which routes are private and which must be public, which is handy for auth proxies and firewalls:

- **Keep private**: `/admin/*` (admin UI), `/api/*` (admin APIs) and `/webhooks/bounce`.
- **Must be public**: `/subscription/*` (subscription pages), `/link/*` (tracked links), `/campaign/*` (tracking pixel), `/public/*` (static files) and `/webhooks/service/*` (provider bounce webhooks).

If you put an authentication layer in front of the admin, exclude the public paths, otherwise your readers can no longer unsubscribe or open tracked links.

## Upgrading and backups

Back up PostgreSQL before every upgrade, as the release notes keep reminding. A simple dump:

```bash
docker compose exec -T db pg_dump -U listmonk listmonk | gzip > listmonk-$(date +%F).sql.gz

```

To upgrade, bump the image tag and run the documented sequence:

```bash
docker compose down
docker compose pull && docker compose run --rm app ./listmonk --upgrade
docker compose up -d app db

```

Pinning the version is worth it: v6.1.0 and v6.2.0 both fixed permission-validation issues in multi-user setups, and v6.2.0 also fixed a path traversal ("ZIP Slip") issue in the CSV import. You want to notice such releases, and a monitor like [changedetection.io](https://blog.uptime.bet/changedetection-io-self-hosted-website-change-monitoring-docker/) or a GitHub release feed in your RSS reader helps.

## Honest limitations

- **Deliverability is your problem.** listmonk sends mail, it does not fix your reputation. Expect to spend time on SPF/DKIM/DMARC, a reputable SMTP relay and bounce handling.
- **No built-in automation journeys.** It is a newsletter and list manager, not a marketing automation suite with drip sequences and visual workflows.
- **Large databases get slow in places.** The performance docs note that with millions of subscribers and tracking records, aggregation-heavy admin pages can take tens of seconds to load. They recommend enabling *Cache slow database queries* in *Settings → Performance* and running `VACUUM ANALYZE` regularly.
- **Powerful features need trust.** The docs warn that the `subscribers:sql_query` permission and template functions can be abused, so only give them to trusted users.
- **v7 is still beta** and comes with breaking changes. Plan the migration rather than following `latest` blindly.

## How does it compare?

|              | listmonk                                    | Ghost newsletters                   | Hosted services (e.g. Mailchimp) |
| ------------ | ------------------------------------------- | ----------------------------------- | -------------------------------- |
| Hosting      | Self-hosted, single binary + PostgreSQL     | Self-hosted or Ghost(Pro)           | SaaS only                        |
| License      | AGPL-3.0                                    | MIT                                 | Proprietary                      |
| Bulk sending | Any SMTP server(s), plus messenger webhooks | Self-hosted installs: Mailgun only  | Provider's own infrastructure    |
| Focus        | Lists, campaigns, transactional API         | Publishing with built-in newsletter | Marketing suite                  |

If you mainly publish a blog and want posts delivered by e-mail, Ghost's built-in newsletter is the simpler path. If you want an independent mailing list with full control over the SMTP side, segmentation and an API for transactional mail, listmonk is the more flexible tool.

## Conclusion

listmonk does one thing and does it well: it manages lists and sends a lot of e-mail with almost no resources. The Docker setup takes five minutes, the real work is on the mail side. With v7 bringing a much lighter, more modern admin UI, it is a good time to start on the stable v6.2.0 and keep an eye on the beta. If you want notifications rather than newsletters, take a look at [Apprise API](https://blog.uptime.bet/apprise-api-self-hosted-notification-gateway-docker/) instead, and for archiving your own inbox, [Mail-Archiver](https://blog.uptime.bet/mail-archiver-self-hosted-email-archive-docker/). More e-mail tools are collected under the [Email tag](https://blog.uptime.bet/tag/email/).

## Sources

- [knadh/listmonk on GitHub](https://github.com/knadh/listmonk?ref=blog.uptime.bet) (README, license, official docker-compose.yml)
- [listmonk releases: v6.2.0, v7.0.0-beta.1, v7.0.0-beta.2](https://github.com/knadh/listmonk/releases?ref=blog.uptime.bet)
- [listmonk.app](https://listmonk.app/?ref=blog.uptime.bet) (features, performance figures, screenshots)
- [Installation docs](https://listmonk.app/docs/installation/?ref=blog.uptime.bet) and [Configuration docs](https://listmonk.app/docs/configuration/?ref=blog.uptime.bet)
- [Performance docs](https://listmonk.app/docs/maintenance/performance/?ref=blog.uptime.bet)
- [Bounce processing](https://listmonk.app/docs/bounces/?ref=blog.uptime.bet), [Messengers](https://listmonk.app/docs/messengers/?ref=blog.uptime.bet), [Transactional API](https://listmonk.app/docs/apis/transactional/?ref=blog.uptime.bet), [Roles and permissions](https://listmonk.app/docs/roles-and-permissions/?ref=blog.uptime.bet), [Templating](https://listmonk.app/docs/templating/?ref=blog.uptime.bet), [Querying and segmentation](https://listmonk.app/docs/querying-and-segmentation/?ref=blog.uptime.bet)
- [listmonk on Docker Hub](https://hub.docker.com/r/listmonk/listmonk?ref=blog.uptime.bet)
- [Ghost docs: Newsletters](https://ghost.org/docs/newsletters/?ref=blog.uptime.bet)