Core Concepts

listmonk is built around four core concepts that work together to power your email campaigns. Understanding these concepts is essential for effective use of the platform.

Overview

Subscribers

People who receive your campaigns

Lists

Groups of subscribers organized by topic

Campaigns

Email messages sent to lists

Templates

Reusable email layouts and designs

Subscribers

Subscribers are individuals who receive your campaigns. Each subscriber has a unique email address and associated metadata.

Subscriber Attributes

Basic Information

Every subscriber has:

UUID: Unique identifier (auto-generated)
Email: Unique email address (required)
Name: Subscriber’s name (required)
Status: Current status (enabled, disabled, or blocklisted)
Created At: Timestamp when subscriber was added
Updated At: Timestamp of last modification

{
  "id": 1,
  "uuid": "5e91c497-b4b5-48d6-9548-e6b4f8e9d4c5",
  "email": "user@example.com",
  "name": "John Doe",
  "status": "enabled",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Custom Attributes

Subscribers can have custom attributes stored as JSON:

{
  "email": "user@example.com",
  "name": "John Doe",
  "attribs": {
    "city": "New York",
    "country": "USA",
    "signup_source": "homepage",
    "plan": "premium",
    "interests": ["technology", "business"],
    "age": 35
  }
}

Use Cases for Custom Attributes:

Geographic targeting
Product/plan segmentation
Personalization in campaigns
Behavior tracking
Custom fields for your use case

Access in Templates:

Hello from {{ .Subscriber.Attribs.city }}!
Your {{ .Subscriber.Attribs.plan }} plan includes...

Subscriber Statuses

Subscribers have three possible statuses defined in schema.sql:4:

Enabled
Disabled
Blocklisted

Status: enabled

Default status for active subscribers
Can receive all campaigns
Can manage their subscriptions
Can unsubscribe from lists

This is the normal, active state for subscribers.

Status: disabled

Temporarily inactive
Cannot receive campaigns
Subscription relationships preserved
Can be re-enabled later

When to use:

Temporary suspension
Cooling-off period
Testing/debugging
Voluntary pause by subscriber

Status: blocklisted

Permanently blocked from receiving emails
Cannot receive any campaigns
Usually result of hard bounces or complaints
Strongest form of opt-out

Blocklisted subscribers should never receive emails. This status is typically set automatically by bounce handling.

Common reasons:

Hard bounces (invalid email)
Spam complaints
Multiple soft bounces
Legal/compliance requirements

Status Transitions:

Subscription Management

Subscribers can be subscribed to multiple lists, each with its own subscription status.

Subscription Statuses

Defined in schema.sql:5, each subscriber-list relationship has one of three statuses:

Unconfirmed
Confirmed
Unsubscribed

Status: unconfirmed

Subscriber has been added but not confirmed
Used with double opt-in lists
Subscriber receives confirmation email
Cannot receive regular campaigns until confirmed
Can receive opt-in confirmation campaigns

Workflow:

Subscriber signs up or is imported
Status set to unconfirmed
Confirmation email sent (if send_optin_confirmation enabled)
Subscriber clicks confirmation link
Status changes to confirmed

Double opt-in is recommended for compliance with GDPR and best practices.

Status: confirmed

Subscriber has confirmed their subscription
Can receive campaigns sent to this list
Active subscription state
Subscriber can unsubscribe at any time

How subscribers get confirmed:

Click confirmation link (double opt-in)
Immediate confirmation (single opt-in)
Admin manually confirms
API sets status to confirmed

Status: unsubscribed

Subscriber has opted out of this list
Cannot receive campaigns for this list
Subscription relationship preserved (for records)
Can re-subscribe later

Important:

Unsubscribing from one list doesn’t affect other lists
Subscriber can still receive campaigns from other subscribed lists
Different from subscriber status “blocklisted” (which blocks all emails)

Always honor unsubscribe requests immediately to comply with anti-spam laws.

Subscription Status Flow:

Lists

Lists are groups of subscribers organized by topic, interest, or purpose. Subscribers can belong to multiple lists simultaneously.

List Types

Defined in schema.sql:1, lists can be one of three types:

Public
Private
Temporary

Type: public

Visible on the public subscription page
Subscribers can self-subscribe
Appears in public subscription forms
Used for newsletters, announcements, etc.

Example Use Cases:

General newsletter
Product updates
Blog post notifications
Community announcements

{
  "name": "Weekly Newsletter",
  "type": "public",
  "optin": "double",
  "description": "Our weekly newsletter with the latest updates",
  "tags": ["newsletter", "weekly"]
}

Type: private

Hidden from public subscription page
Only admins can add subscribers
Not visible in public forms
Used for internal or exclusive lists

Example Use Cases:

VIP customers
Internal team communications
Beta testers
Exclusive offers
Partner communications

{
  "name": "VIP Customers",
  "type": "private",
  "optin": "single",
  "description": "Exclusive list for VIP customers",
  "tags": ["vip", "premium"]
}

Type: temporary

Created for one-time campaigns
Automatically deleted after campaign completion
Used for ad-hoc segments
Not visible on public pages

Example Use Cases:

One-time promotional campaigns
Event-specific communications
Temporary segments for testing
Campaign-specific targeting

Temporary lists and all their subscribers are automatically deleted after associated campaigns finish. Use with caution.

{
  "name": "Black Friday 2024 Segment",
  "type": "temporary",
  "optin": "single",
  "description": "Temporary list for Black Friday campaign",
  "tags": ["temporary", "promo"]
}

Opt-in Types

Defined in schema.sql:2, lists support two opt-in methods:

Single Opt-in
Double Opt-in

Type: single

Subscribers are immediately confirmed
No confirmation email required
Faster subscription process
Higher conversion rate
Lower compliance confidence

When to use:

Internal lists
Trusted sources
Low-risk communications
When speed matters more than verification

Workflow:

Type: double

Subscribers must confirm via email
Sends confirmation email automatically
Verifies email address is valid
Better compliance (GDPR recommended)
Lower bounce rate

When to use:

Public-facing lists
Compliance-critical scenarios
When list quality matters
GDPR compliance required

Workflow:

Double opt-in is the gold standard for email marketing compliance and list quality.

List Status

Defined in schema.sql:3, lists can have two statuses:

Active
Archived

Status: active

List is operational and visible (based on type)
Can be used in campaigns
Accepts new subscribers
Normal operational state

Status: archived

List is hidden from active use
Cannot be used in new campaigns
Existing subscriptions preserved
Used for historical lists

When to archive:

Discontinued newsletter
Completed event series
Seasonal campaigns (off-season)
Historical reference

Archiving preserves data while removing the list from active use. You can unarchive lists later if needed.

List Attributes

Lists have several attributes for organization and configuration:

{
  "id": 1,
  "uuid": "3e9c6a7f-8b2d-4e1a-9f3c-7d8e5a2b4c1f",
  "name": "Product Updates",
  "type": "public",
  "optin": "double",
  "status": "active",
  "tags": ["product", "updates", "monthly"],
  "description": "Monthly updates about new features and improvements",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Attributes:

UUID: Unique identifier for external references
Name: Display name (required)
Type: public, private, or temporary
Opt-in: single or double
Status: active or archived
Tags: Array of strings for categorization
Description: Optional internal notes

Campaigns

Campaigns are email messages sent to one or more lists. They are the primary way to communicate with your subscribers.

Campaign Lifecycle

Defined in schema.sql:6, campaigns progress through several statuses:

Draft

Status: draft

Campaign is being created or edited
Not visible to subscribers
Can be freely modified
Not sending any messages

Actions available:

Edit content
Change recipients
Configure settings
Send test emails
Schedule or start

Scheduled

Status: scheduled

Campaign is scheduled for future sending
Will automatically start at configured time
Can still be edited or cancelled
Shows scheduled time

Transitions to:

running - At scheduled time
draft - If unscheduled
cancelled - If cancelled before start

Running

Status: running

Campaign is actively sending
Messages being delivered to subscribers
Progress tracked in real-time
Cannot be edited (content locked)

Monitoring:

Sent count (current / total)
Error count
Real-time progress
Estimated completion time

Actions available:

Pause
Cancel
View analytics

Paused

Status: paused

Campaign temporarily stopped
Can be resumed later
Progress saved
No messages sent while paused

Use cases:

Emergency stop
Address issues
Rate limiting
Manual control

Actions available:

Resume (returns to running)
Cancel

Cancelled

Status: cancelled

Campaign permanently stopped
Cannot be resumed
Partial send recorded
Final state (terminal)

When cancelled:

Records show messages sent before cancellation
Remaining subscribers not contacted
Analytics available for sent portion

Finished

Status: finished

Campaign completed successfully
All messages sent
Final analytics available
Final state (terminal)

Available data:

Total sent
Views (opens)
Clicks
Bounces
Completion time

Status Flow Diagram:

Campaign Types

Defined in schema.sql:7, campaigns have two types:

Regular
Opt-in

Type: regular

Standard marketing/newsletter campaigns
Sent to confirmed subscribers
Respects subscription preferences
Most common campaign type

Target subscribers with:

Status: enabled
Subscription status: confirmed
On selected lists

{
  "name": "Monthly Newsletter - March 2024",
  "type": "regular",
  "subject": "What's New This Month",
  "lists": [1, 2, 3],
  "template_id": 1
}

Type: optin

Special campaign for opt-in confirmations
Sent to unconfirmed subscribers
Contains confirmation link
Triggered by double opt-in lists

Target subscribers with:

Status: enabled
Subscription status: unconfirmed
On double opt-in lists

Opt-in campaigns are typically automated and sent when subscribers join double opt-in lists.

{
  "name": "Subscription Confirmation",
  "type": "optin",
  "subject": "Please confirm your subscription",
  "body": "Click here to confirm: {{ .OptinURL }}"
}

Content Types

Defined in schema.sql:8, campaigns support multiple content formats:

Rich Text
HTML
Plain Text
Markdown
Visual

Type: richtext

Visual WYSIWYG editor
Easy formatting with toolbar
No coding required
Best for beginners
Automatically generates HTML

Features:

Bold, italic, underline
Headings and paragraphs
Lists and links
Images
Basic styling

Type: html

Raw HTML code
Complete design control
Custom styling
Advanced layouts
Requires HTML knowledge

Best for:

Custom designs
Complex layouts
Precise control
Developers

Type: plain

Plain text only
No formatting
Highest deliverability
Simple and direct
No HTML rendering

Advantages:

Never caught by spam filters
Personal feel
Accessible
Fast to compose

Type: markdown

Markdown syntax
Converted to HTML
Easy to write and read
Version control friendly
Balance of simplicity and features

Example:

# Welcome!

This is **bold** and this is *italic*.

- Item 1
- Item 2

[Link text](https://example.com)

Type: visual

Drag-and-drop visual editor
Pre-built blocks
Responsive design
No coding needed
Professional layouts

Use cases:

Professional newsletters
Marketing campaigns
Multi-section emails
Image-heavy content

Campaign Attributes

Campaigns have comprehensive configuration options:

{
  "id": 1,
  "uuid": "7f3e9c6a-2d8b-1a4e-3c9f-5a7d8e2b4c1f",
  "name": "March Newsletter",
  "subject": "Spring Updates & New Features",
  "from_email": "newsletter@example.com",
  "body": "<html>Campaign content...</html>",
  "altbody": "Plain text version...",
  "content_type": "html",
  "type": "regular",
  "status": "finished",
  "tags": ["newsletter", "monthly"],
  "send_at": "2024-03-01T10:00:00Z",
  "template_id": 1,
  "messenger": "email",
  "lists": [1, 2],
  "to_send": 10000,
  "sent": 10000,
  "archive": true,
  "archive_slug": "march-2024-newsletter",
  "started_at": "2024-03-01T10:00:00Z",
  "created_at": "2024-02-28T15:00:00Z",
  "updated_at": "2024-03-01T11:30:00Z"
}

Key Attributes:

name: Internal reference name
subject: Email subject line (supports templates)
from_email: Sender email address
body: Campaign content (format depends on content_type)
altbody: Plain text alternative (optional)
template_id: Wrapper template to use
lists: Array of list IDs to send to
send_at: Scheduled send time (null for immediate)
messenger: Delivery method (“email” or custom)
headers: Custom email headers as JSON
attribs: Custom campaign attributes as JSON
archive: Publish to public archive
archive_slug: URL slug for archived campaign

Progress Tracking:

to_send: Total subscribers to contact
sent: Messages successfully sent
max_subscriber_id: Highest subscriber ID in campaign
last_subscriber_id: Last processed subscriber ID

Campaign Analytics

listmonk tracks detailed analytics for each campaign:Metrics Available:

Delivery Metrics

To Send: Total target audience
Sent: Successfully delivered
Bounces: Delivery failures
Bounce Rate: Percentage of bounces

Engagement Metrics

Views: Email opens (tracked via pixel)
Open Rate: Percentage who opened
Clicks: Link clicks
Click Rate: Percentage who clicked
Click-to-Open Rate: Clicks / Opens

Analytics Tables:From schema.sql:156-166:

campaign_views: Tracks individual email opens with timestamps
link_clicks: Tracks individual link clicks with subscriber and timestamp
bounces: Records bounce events with type and metadata

Dashboard Charts:Materialized view mat_dashboard_charts (schema.sql:399-432) provides:

30-day rolling link click trends
30-day rolling campaign view trends
Aggregated by date for visualization

Analytics data is retained even if subscribers are deleted, ensuring accurate historical reporting.

Templates

Templates are reusable email layouts that wrap campaign content. They provide consistent branding and structure across all campaigns.

Template Types

Defined in schema.sql:10, templates have three types:

Campaign
Campaign Visual
Transaction

Type: campaign

Standard email templates
Wrap campaign content
Include header, footer, styling
Most common template type

Structure:

<!DOCTYPE html>
<html>
<head>
  <style>
    /* Your branding styles */
  </style>
</head>
<body>
  <header>
    <!-- Logo, branding -->
  </header>
  
  <main>
    {{ template "content" . }}
  </main>
  
  <footer>
    <!-- Unsubscribe, contact info -->
    <a href="{{ .UnsubscribeURL }}">Unsubscribe</a>
  </footer>
</body>
</html>

The {{ template "content" . }} directive inserts campaign content into the template.

Type: campaign_visual

Templates for visual editor
Support drag-and-drop blocks
Responsive design
Pre-defined sections

Features:

Block-based layout
Mobile responsive
Pre-styled components
No coding required

Type: tx

Transactional email templates
Used for system emails
Typically simpler design
Focused on information delivery

Use cases:

Order confirmations
Password resets
Account notifications
System alerts
Subscription confirmations

Example:

<!DOCTYPE html>
<html>
<body>
  <h1>{{ .Subject }}</h1>
  {{ template "content" . }}
  <p>This is an automated message.</p>
</body>
</html>

Template Structure

Templates use Go’s template syntax for dynamic content:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ .Subject }}</title>
  <style>
    body {
      font-family: Arial, sans-serif;
      line-height: 1.6;
      color: #333;
      max-width: 600px;
      margin: 0 auto;
      padding: 20px;
    }
    .header {
      background: #007bff;
      color: white;
      padding: 20px;
      text-align: center;
    }
    .content {
      padding: 20px;
      background: #f9f9f9;
    }
    .footer {
      padding: 20px;
      text-align: center;
      font-size: 12px;
      color: #666;
    }
    .button {
      display: inline-block;
      padding: 10px 20px;
      background: #007bff;
      color: white;
      text-decoration: none;
      border-radius: 4px;
    }
  </style>
</head>
<body>
  <div class="header">
    <h1>Your Company Name</h1>
  </div>
  
  <div class="content">
    {{ template "content" . }}
  </div>
  
  <div class="footer">
    <p>
      You're receiving this email because you subscribed to our mailing list.
    </p>
    <p>
      <a href="{{ .UnsubscribeURL }}">Unsubscribe</a> | 
      <a href="{{ .OptinURL }}">Manage Preferences</a> | 
      <a href="{{ .MessageURL }}">View in Browser</a>
    </p>
    <p>
      Company Name<br>
      123 Main St, City, State 12345<br>
      © {{ .Date.Year }} All rights reserved
    </p>
  </div>
</body>
</html>

Template Variables:listmonk provides these variables in all templates:

Campaign Variables
Subscriber Variables
URL Variables

{{ .Subject }} - Campaign subject
{{ .FromEmail }} - Sender email
{{ .Date }} - Current date/time
{{ .Campaign.Name }} - Campaign name
{{ .Campaign.UUID }} - Campaign UUID
{{ .Campaign.Tags }} - Campaign tags

{{ .Subscriber.UUID }} - Subscriber UUID
{{ .Subscriber.Email }} - Email address
{{ .Subscriber.Name }} - Full name
{{ .Subscriber.FirstName }} - First name
{{ .Subscriber.LastName }} - Last name
{{ .Subscriber.Status }} - Subscriber status
{{ .Subscriber.Attribs.key }} - Custom attributes

{{ .UnsubscribeURL }} - Unsubscribe link
{{ .OptinURL }} - Manage preferences
{{ .MessageURL }} - View in browser
{{ .TrackingPixelURL }} - Open tracking pixel
{{ .ArchiveURL }} - Public archive link

Template Functions:

<!-- Date formatting -->
{{ .Date.Format "January 2, 2006" }}

<!-- Conditionals -->
{{ if .Subscriber.Attribs.city }}
  Hello from {{ .Subscriber.Attribs.city }}!
{{ end }}

<!-- Loops -->
{{ range .Campaign.Tags }}
  <span class="tag">{{ . }}</span>
{{ end }}

<!-- String functions -->
{{ .Subscriber.Email | lower }}
{{ .Subscriber.Name | upper }}

Default Template

Every listmonk installation can have one default template (schema.sql:85):

is_default BOOLEAN NOT NULL DEFAULT false
CREATE UNIQUE INDEX ON templates (is_default) WHERE is_default = true;

Default Template Behavior:

Used when no template explicitly selected
Only one template can be default
Ensures consistent branding
Can be changed anytime

Setting Default Template:

Navigate to Settings → Templates
Edit desired template
Check “Set as default”
Save

The default template is automatically applied to new campaigns unless you choose a different template.

Template Best Practices

Keep It Responsive

Ensure templates work on all devices:

<meta name="viewport" content="width=device-width, initial-scale=1.0">

<style>
  @media only screen and (max-width: 600px) {
    .content {
      padding: 10px !important;
    }
    .button {
      display: block !important;
      width: 100% !important;
    }
  }
</style>

Include Required Links

Always include:

Unsubscribe link (often required by law)
Physical mailing address (CAN-SPAM requirement)
Preference management link
View in browser link

Failure to include an unsubscribe link violates anti-spam laws in most jurisdictions.

Optimize for Email Clients

Use table-based layouts for better compatibility
Inline CSS for older clients
Test in multiple email clients
Provide plain text alternative
Keep width ≤ 600px

Brand Consistency

Use your brand colors
Include logo
Consistent typography
Match website design
Professional footer

Performance

Optimize images
Keep HTML size reasonable
Minimize external resources
Use web-safe fonts as fallback

Relationships

Understanding how these concepts relate to each other:

Summary

Subscribers

Statuses: enabled, disabled, blocklistedSubscription Statuses: unconfirmed, confirmed, unsubscribedFeatures: Custom JSONB attributes, multiple list subscriptions

Lists

Types: public, private, temporaryOpt-in: single, doubleStatus: active, archived

Campaigns

Statuses: draft, scheduled, running, paused, cancelled, finishedTypes: regular, optinContent: richtext, html, plain, markdown, visual

Templates

Types: campaign, campaign_visual, txFeatures: Go template syntax, variables, functions, default template support

Next Steps

Templates Guide

Create custom email templates

Campaign Management

Learn advanced campaign features

Subscriber Management

Import, segment, and manage subscribers

Analytics

Track campaign performance

API Reference

Automate with the REST API

Bounce Handling

Configure automatic bounce processing

Get Started

Core Features

Configuration

Advanced

Development

Overview

Subscribers

Lists

Campaigns

Templates

Subscribers

Subscriber Attributes

Subscription Management

Lists

Campaigns

Delivery Metrics

Engagement Metrics

Templates

Relationships

Summary

Subscribers

Lists

Campaigns

Templates

Next Steps

Templates Guide

Campaign Management

Subscriber Management

Analytics

API Reference

Bounce Handling

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Advanced

Development

​Overview

Subscribers

Lists

Campaigns

Templates

​Subscribers

​Subscriber Attributes

​Subscription Management

​Lists

​Campaigns

Delivery Metrics

Engagement Metrics

​Templates

​Relationships

​Summary

Subscribers

Lists

Campaigns

Templates

​Next Steps

Templates Guide

Campaign Management

Subscriber Management

Analytics

API Reference

Bounce Handling

Build docs developers (and LLMs) love

Overview

Subscribers

Subscriber Attributes

Subscription Management

Lists

Campaigns

Templates

Relationships

Summary

Next Steps