Quickstart Guide

Overview

This quickstart guide will walk you through setting up listmonk and sending your first email campaign in just a few steps. By the end, you’ll have:

A running listmonk instance
A configured mailing list
Subscribers added to your list
Your first campaign created and sent

This guide assumes you’re using Docker for installation. For other installation methods, see the Installation Guide.

Prerequisites

Before you begin, ensure you have:

Docker and Docker Compose installed
An SMTP server or email provider (Gmail, AWS SES, Sendgrid, etc.)
Basic command line knowledge

Step-by-Step Guide

Install and Launch Listmonk

Download and start listmonk with Docker Compose:

# Download the compose file
curl -LO https://github.com/knadh/listmonk/raw/master/docker-compose.yml

# Start the services
docker compose up -d

Visit http://localhost:9000 in your browser. You’ll be prompted to create your admin account.

To set credentials during installation, use:

LISTMONK_ADMIN_USER=admin LISTMONK_ADMIN_PASSWORD=yourpassword docker compose up -d

Configure SMTP Settings

After logging in, navigate to Settings → SMTP to configure your email provider.

Gmail
AWS SES
Sendgrid

{
  "host": "smtp.gmail.com",
  "port": 587,
  "auth_protocol": "login",
  "username": "[email protected]",
  "password": "your-app-password",
  "hello_hostname": "",
  "max_conns": 10,
  "max_msg_retries": 2,
  "idle_timeout": "15s",
  "wait_timeout": "5s",
  "tls_enabled": true,
  "tls_skip_verify": false
}

Use an App Password instead of your regular Gmail password.

{
  "host": "email-smtp.us-east-1.amazonaws.com",
  "port": 587,
  "auth_protocol": "login",
  "username": "YOUR_SMTP_USERNAME",
  "password": "YOUR_SMTP_PASSWORD",
  "hello_hostname": "",
  "max_conns": 10,
  "max_msg_retries": 2,
  "idle_timeout": "15s",
  "wait_timeout": "5s",
  "tls_enabled": true,
  "tls_skip_verify": false
}

{
  "host": "smtp.sendgrid.net",
  "port": 587,
  "auth_protocol": "login",
  "username": "apikey",
  "password": "YOUR_SENDGRID_API_KEY",
  "hello_hostname": "",
  "max_conns": 10,
  "max_msg_retries": 2,
  "idle_timeout": "15s",
  "wait_timeout": "5s",
  "tls_enabled": true,
  "tls_skip_verify": false
}

Click Test connection to verify your SMTP settings work correctly.

Create Your First Mailing List

Navigate to Lists in the sidebar and click New.Fill in the details:

Name: Newsletter Subscribers
Type: Public (allows public subscription)
Opt-in: Single (subscribers are added immediately) or Double (requires email confirmation)
Description: Optional internal description

Click Save to create your list.

Start with a Private list and Single opt-in for testing to avoid sending confirmation emails.

Add Subscribers

Go to Subscribers → New to manually add a subscriber.

Manual Entry
Bulk Import

Fill in the form:

Email: [email protected]
Name: Your Name
Status: Enabled
Lists: Select “Newsletter Subscribers”
Subscription Status: Confirmed

Click Save.

You can also import multiple subscribers from a CSV file:

Go to Subscribers → Import
Upload a CSV file with columns: email, name, status
Select the list to import into
Choose import mode (Subscribe or Blocklist)
Click Upload

Example CSV:

email,name,status
[email protected],John Doe,enabled
[email protected],Jane Smith,enabled

For your first test, use your own email address so you can verify campaign delivery.

Create an Email Template

Navigate to Campaigns → Templates → New.You can use the default template or create a custom one:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
</head>
<body>
    <h1>{{ "{{" }} .Campaign.Name {{ "}}" }}</h1>
    <div>
        {{ "{{" }} .Campaign.Body {{ "}}" }}
    </div>
    <hr>
    <p>
        <a href="{{ "{{" }} .UnsubscribeURL {{ "}}" }}">Unsubscribe</a>
    </p>
</body>
</html>

Save the template as your default campaign template.

Create and Send Your First Campaign

Navigate to Campaigns → New Campaign.Configure your campaign:

Name: Welcome Newsletter (internal name)
Subject: Welcome to Our Newsletter!
From: [email protected]
Lists: Select “Newsletter Subscribers”
Template: Choose your template
Content: Write your email content using the rich text editor

Example content:

Hi there!

Thank you for subscribing to our newsletter. We're excited to have you join our community.

You'll receive updates about our latest news, tips, and exclusive offers.

Best regards,
The Team

Test Your Campaign:

Click Test and enter your email address
Check that you receive the test email
Verify formatting and links work correctly

Send Your Campaign:

Click Start campaign when you’re ready
The campaign status will change to “Running”
Monitor progress in the campaign dashboard

Verify Delivery

After sending your campaign:

Check the Campaign page for delivery statistics
Look for:
- Sent: Number of emails sent
- Views: Number of opens (if tracking enabled)
- Clicks: Number of link clicks
- Bounces: Failed deliveries
Check your inbox for the email
Verify all links work, especially the unsubscribe link

What’s Next?

Now that you’ve sent your first campaign, explore more features:

Subscriber Management

Learn advanced subscriber management and segmentation

Campaign Features

Explore scheduling, analytics, and advanced campaign options

Templates

Create beautiful email templates with variables and functions

API Integration

Integrate listmonk with your applications using the API

Troubleshooting

SMTP Connection Failed

Problem: Test connection fails or emails won’t sendSolutions:

Verify your SMTP credentials are correct
Check that you’re using the correct host and port
For Gmail, ensure you’re using an App Password, not your regular password
Check if your provider requires specific security settings (TLS/SSL)
Verify your firewall allows outbound connections on the SMTP port

Campaign Stuck in 'Running' Status

Problem: Campaign doesn’t complete or shows no progressSolutions:

Check SMTP settings are configured correctly
Look at the logs: docker compose logs -f listmonk
Verify you have subscribers in the selected lists
Check the campaign’s “Send later” date if scheduled
Ensure concurrency and message_rate settings allow sending

Subscribers Not Receiving Emails

Problem: Campaign sent but subscribers didn’t receive emailsSolutions:

Check subscriber status is “Enabled”
Verify subscription status is “Confirmed”
Check spam/junk folders
Look for bounces in the Bounces section
Verify your SMTP provider’s sending limits aren’t exceeded
Check campaign analytics for delivery errors

Unsubscribe Link Not Working

Problem: Unsubscribe link returns an errorSolutions:

Ensure root_url is configured correctly in Settings → General
Verify your template includes {{ "{{" }} .UnsubscribeURL {{ "}}" }}
Check that the listmonk web server is accessible at the configured URL

Best Practices

Start Small

Begin with a small test list of your own email addresses to verify everything works before sending to your full subscriber base.

Monitor Bounces

Regularly check and clean your bounce list to maintain a healthy sender reputation.

Respect Unsubscribes

Always include an unsubscribe link and honor opt-outs immediately.

Test Everything

Use the test campaign feature to verify content, links, and formatting before sending to your entire list.

Get Started

Core Features

Configuration

Advanced

Development

Overview

Prerequisites

Step-by-Step Guide

Verify Delivery

What’s Next?

Subscriber Management

Campaign Features

Templates

API Integration

Troubleshooting

Best Practices

Start Small

Monitor Bounces

Respect Unsubscribes

Test Everything

Need Help?

Documentation

GitHub Issues

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Advanced

Development

​Overview

​Prerequisites

​Step-by-Step Guide

​Verify Delivery

​What’s Next?

Subscriber Management

Campaign Features

Templates

API Integration

​Troubleshooting

​Best Practices

Start Small

Monitor Bounces

Respect Unsubscribes

Test Everything

​Need Help?

Documentation

GitHub Issues

Build docs developers (and LLMs) love

Overview

Prerequisites

Step-by-Step Guide

Verify Delivery

What’s Next?

Troubleshooting

Best Practices

Need Help?