How to Use Listmonk: The Beginner's Guide

CodexFuse Team · 2026-10-31T14:34:36.924Z · 12 min read

Learn how to use Listmonk: install with Docker, create your first list, set up double opt-in and SMTP, build templates, and send your first campaign.

If you want to learn how to use Listmonk, you are about to replace your email marketing subscription with a single binary on your own server. Listmonk is a free, open-source, self-hosted newsletter and mailing-list manager that handles millions of subscribers with no per-seat or per-email pricing — a genuine Mailchimp alternative you fully own. This Listmonk for beginners tutorial takes you from an empty server to your first sent campaign: installing with Docker, creating your first list, turning on double opt-in, connecting SMTP, building a template, and sending your first campaign. It deploys in containers, so pair this guide with our Docker beginner guide if containers are new to you.

What Is Listmonk?

Listmonk is a free and open-source, self-hosted newsletter and mailing-list manager packed into a single binary backed by a PostgreSQL database. It lets you run one-way mailing lists with millions of subscribers across single and double opt-in lists, segment subscribers with SQL expressions, build dynamic email templates with the Go templating language, and send high-throughput campaigns through multiple SMTP relays with throughput and sliding-window rate limiting. It is released under the AGPL-3.0 license, has more than 24,000 GitHub stars, and its current stable release is v6.2.0 (June 2026), with the v7.0.0-beta.1 beta released October 20, 2026. In plain terms: it does what Mailchimp does for sending newsletters, except your data lives on your server and there is no bill that grows with your list.

What You Need Before Installing Listmonk

Gather these four things before you start the Listmonk setup, and the rest of the guide flows smoothly.

• A VPS. Any modest VPS works — Listmonk has a nominal CPU and memory footprint. If you do not have one yet, read our guide on what is VPS hosting first.
• A domain with HTTPS. Your newsletter lives at a domain like newsletter.yourdomain.com, and subscription forms must be served over HTTPS. Our Caddy beginner guide shows the fastest reverse-proxy setup.
• An SMTP relay or provider. Listmonk composes and queues mail, but a separate mail server or transactional-email provider actually delivers it. Never send bulk mail from a fresh VPS IP without a plan — more on that in the SMTP lesson below.
• Docker. The official path is Docker Compose with a bundled PostgreSQL container — Listmonk does not support SQLite; PostgreSQL is required.

How to Install Listmonk with Docker

The official Listmonk Docker flow downloads a sample Compose file, runs the bundled Postgres container, and installs the database automatically. This Listmonk install needs no separate database setup — the Compose file wires Postgres for you. Here is the whole arc:

1. Download the official Compose file. curl -LO https://github.com/knadh/listmonk/raw/master/docker-compose.yml — this gives you the app container plus a Postgres container wired together.
2. Choose your version. The file ships with listmonk/listmonk:latest (v6.2.0 stable). If you want the v7 beta, edit the image line to listmonk/listmonk:beta.
3. Set your admin credentials up front. Export LISTMONK_ADMIN_USER and LISTMONK_ADMIN_PASSWORD before the first docker compose up — Listmonk then creates your super-admin automatically. Otherwise you create the account in the first-run wizard.
4. Start everything. Run docker compose up -d. The app container runs ./listmonk --install --idempotent --yes on first boot (installing the database schema only when the database is empty) and ./listmonk --upgrade --yes on later boots to apply migrations.
5. Open the dashboard. Visit http://localhost:9000 (or your domain once the reverse proxy is in place).
6. Create the admin account in the setup wizard if you did not pre-set the environment variables.
7. Confirm the install. The dashboard should load with empty Subscribers, Lists, and Campaigns sections — you are ready to configure.

Prefer a plain binary install instead of Docker? Download the release for your OS from the GitHub releases page, then run the same three commands the Compose file runs for you:

./listmonk --new-config     # generate config.toml, then edit the DB settings
./listmonk --install        # create the Postgres schema
./listmonk                  # run the app on http://localhost:9000

Create Your First List and Turn On Double Opt-In

Lists are the heart of the Listmonk setup: every campaign sends to one or more lists. Open Lists in the left menu and click + New to create your first one. The two decisions that matter:

• Public vs. private. Public lists let people subscribe themselves through your subscription form; private lists can only be filled by you (imports, API). Your main newsletter is almost always a public list.
• Double opt-in: always on for public lists. A new subscriber gets a confirmation email and must click the link before they count as confirmed. This single setting is the biggest deliverability decision you will make — confirmed addresses bounce less, spam-complain less, and keep your sender reputation clean. Single opt-in is only defensible for lists you fill yourself from customers you already email.

Give the list a clear name ("Weekly Tech Newsletter" beats "list1") and set the sender details — name and email address — because every campaign inherits them.

Connect SMTP: The Deliverability Lesson

Listmonk queues and hands off mail; it does not make you an email provider. The Listmonk SMTP settings live at Settings → SMTP: configure your relay's host, port, auth protocol, username, password, and TLS. Listmonk supports multiple SMTP servers with per-server rate limits, so you can split transactional and bulk traffic. Before you send a single campaign, do the three DNS jobs on your sending domain:

• SPF — authorizes your relay's servers to send for your domain.
• DKIM — cryptographically signs every message.
• DMARC — tells receivers what to do with mail that fails the first two, starting at p=none while you monitor.

Skip this and your beautifully templated newsletter lands in spam — or gets rejected outright. Most beginners either use a transactional-email provider as their relay (which guides them through the DNS records) or a dedicated SMTP host on their VPS with the records added manually at their DNS provider. Do the DNS work first; Listmonk's bounce handling under Settings → Bounces only protects your reputation after the mail leaves.

Add Subscribers: Forms, CSV Import, and the API

With a public list in place, Listmonk gives you three ways to grow it. First, subscription forms: each public list gets an embeddable HTML form you can drop on your website — subscribers fill it in, confirm via double opt-in, and land in the list with zero manual work. Second, CSV import: if you are migrating from Mailchimp or MailerLite, export your list there and import it into Listmonk from the Subscribers page — but only import people who actually opted in, and expect bounces on stale addresses. Third, the REST API: Listmonk has a full API with Basic Auth, so you can add subscribers, create lists, and even launch campaigns from your own apps:

curl -X POST "http://localhost:9000/api/subscribers" \
  -u "listmonk:your-password" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"Reader","status":"enabled","lists":[1]}'

Power users can segment with raw SQL expressions — for example, querying subscriber attributes to build a segment of everyone who marked a "news" preference — without exporting anything to a spreadsheet.

This Listmonk tutorial now walks the full arc: install, first list, double opt-in, SMTP, template, and first campaign.

Build Your First Listmonk Template

Listmonk templates are where the Go-templating rule shows up: templates are written with the Go templating language, which gives you expressions, logic, and 100+ functions in subject lines and content — but it also means literal {{ }} and {% %} in pasted CSS or JavaScript will be parsed as template code. Go to Templates → New template and pick your authoring mode:

• Visual drag-and-drop builder — the beginner-safe path; compose with blocks and never touch template syntax.
• WYSIWYG editor — rich-text editing for simple branded layouts.
• Markdown — write in Markdown and let Listmonk convert it.
• Raw HTML — full control; this is where you must escape or avoid stray template delimiters.
• Plain text — for transactional mail where formatting is a liability.

Use the built-in preview before saving, and test with real subscriber data — template expressions behave differently with empty fields than with filled ones.

Send Your First Campaign

Listmonk campaigns are how every newsletter send works. Click Campaigns → Create New and fill in the name, subject, from address, the lists it goes to, and the template. Then compose your content in the editor, and — this is the step beginners skip — send a test message first. Note the Listmonk rule: the test message goes to an existing subscriber, so add your own address to the list (and confirm the double opt-in) before testing. When the test looks right in your inbox and the links track, start the campaign and watch the built-in analytics: opens, clicks, top links, bounces, and unsubscribes per campaign.

Listmonk vs Mailchimp: When Self-Hosting Wins

This is the comparison every beginner runs before committing. The math is simple: SaaS newsletters charge per contact, and your list only grows.

The honest version: Listmonk wins on cost and control, but it hands you the deliverability homework — SPF, DKIM, DMARC, bounce handling, and list hygiene — that a SaaS platform quietly does for you. If you would rather never think about DNS, stay on SaaS. If you want your list to be an asset you own, Listmonk is the tool.

7 Beginner Mistakes to Avoid

Sources

• listmonk.app (official site, fetched 2026-10-31): single-binary self-hosted newsletter manager, Docker install flow, v7.0.0-beta.1 released 20 Oct 2026, Postgres required, Go templating language, multi-SMTP queues, SQL subscriber segmentation.
• GitHub knadh/listmonk releases API (fetched 2026-10-31): v6.2.0 stable released 2026-06-26; v7.0.0-beta.1 released 2026-10-20; ~24,095 stars; AGPL-3.0 license.
• Official docker-compose.yml (knadh/listmonk master, fetched 2026-10-31): listmonk/listmonk:latest image, bundled Postgres, --install --idempotent --yes first-boot flow, LISTMONK_ADMIN_USER/_PASSWORD env, port 9000.
• book.servus.at "Newsletter via Listmonk" (fetched 2026-10-31): SMTP settings (host, port, auth protocol, username, password, TLS), public vs. private lists, double opt-in recommendation, campaign creation flow, bounce handling.
• thetechedvocate.org "How to Create Your Own Newsletter with Listmonk" (fetched via SERP 2026-10-31): install → database → configure → template → subscribers → campaign → test → analytics arc.
• prompts.brightcoding.dev "Stop Paying Mailchimp! Self-Host Newsletters with listmonk" (fetched 2026-10-31): built by Kailash Nadh, backed by Zerodha; Mailchimp ~$299/month for 10,000 contacts, ConvertKit ~$290/month (June 2026).
• dev.to "How I Saved $348/Year with a Self-Hosted Newsletter" (fetched via SERP 2026-10-31): MailerLite-to-self-hosted migration savings story; REST API usage with Basic Auth.

Frequently Asked Questions

Is Listmonk really free?

Yes — Listmonk is free and open source under the AGPL-3.0 license, with unlimited subscribers and unlimited sends. Your only costs are the VPS it runs on and whatever SMTP relay you use for delivery.

Does Listmonk work with SQLite?

No. Listmonk requires PostgreSQL as its database. The official Docker Compose file bundles a Postgres container, so most beginners never install the database separately.

What is double opt-in in Listmonk, and should I use it?

Double opt-in sends every new subscriber a confirmation email they must click before they are confirmed. Yes — always enable it on public lists. It keeps bounces and spam complaints down and protects your sender reputation.

How do Listmonk templates work?

Templates use the Go templating language, giving you expressions, logic, and 100+ functions in subjects and content. You can author with the visual drag-and-drop builder, a WYSIWYG editor, Markdown, raw HTML, or plain text — and preview before saving.

Can Listmonk replace Mailchimp?

For sending newsletters and managing lists, yes — with unlimited contacts at no platform cost. The trade-off is that you take over deliverability work (SPF, DKIM, DMARC, bounce handling) that Mailchimp handles for you. Self-hosters cite real savings, like $348/year saved migrating from MailerLite.