Subscribers - Listmonk

Subscribers are the core of your mailing list. listmonk provides comprehensive tools to manage subscriber data, attributes, and privacy settings.

Subscriber Data Model

Each subscriber in listmonk has the following properties:

ID: Unique numeric identifier
UUID: Unique universal identifier for public-facing operations
Email: Unique email address (case-insensitive)
Name: Subscriber’s name
Attribs: JSONB custom attributes field for flexible data storage
Status: enabled, disabled, or blocklisted
Created At: Timestamp when subscriber was added
Updated At: Timestamp of last modification

Adding Subscribers

Manual Creation
CSV Import
API

Add subscribers individually through the admin interface:

Navigate to Subscribers

Click on Subscribers in the main menu

Create New Subscriber

Click the New button and fill in:

Email address (required, validated)
Name (1-500 characters)
Custom attributes in JSON format
Select lists to subscribe to

Set Subscription Options

Choose whether to preconfirm subscriptions
For double opt-in lists, confirmation emails are sent automatically

Bulk import subscribers from CSV or ZIP files:

Prepare Your File

CSV must include headers: email, name, attributes

email,name,attributes
user@example.com,John Doe,"{""city"": ""Bengaluru"", ""plan"": ""premium""}"

Configure Import

Mode: subscribe or blocklist
Lists: Select target lists
Subscription Status: confirmed or unconfirmed
Overwrite: Choose whether to update existing subscribers
Delimiter: Usually comma (,)

Upload and Process

The importer processes records in batches of 10,000 for optimal performance

ZIP files are automatically extracted and CSV files inside are processed

Create subscribers programmatically via the REST API:

curl -u 'username:password' -X POST 'http://localhost:9000/api/subscribers' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "name": "John Doe",
    "status": "enabled",
    "lists": [1, 2],
    "attribs": {
      "city": "Bengaluru",
      "plan": "premium"
    },
    "preconfirm_subscriptions": true
  }'

Subscriber Statuses

Subscribers can have one of three statuses:

Enabled

Active subscribers who can receive campaigns

Disabled

Temporarily disabled subscribers (excluded from campaigns)

Blocklisted

Permanently blocked subscribers who cannot receive any emails

Status vs Subscription Status

Subscriber Status (enabled/disabled/blocklisted) is global, while Subscription Status (unconfirmed/confirmed/unsubscribed) is per-list in the subscriber_lists table.

Custom Attributes

Subscribers support flexible JSONB attributes for storing custom data:

{
  "city": "Bengaluru",
  "plan": "premium",
  "signup_date": "2024-01-15",
  "preferences": {
    "newsletter": true,
    "marketing": false
  }
}

Using Attributes in Templates

Access subscriber attributes in campaign templates:

<p>Hello {{ .Subscriber.Name }} from {{ .Subscriber.Attribs.city }}!</p>
<p>Your {{ .Subscriber.Attribs.plan }} plan is active.</p>

Querying and Filtering

Search Subscribers

Search by email or name using the search bar in the admin interface.

SQL Queries

SQL query functionality requires the subscribers:sql_query permission

Execute custom SQL queries for advanced filtering:

SUBSCRIBERS.attribs->>'city' = 'Bengaluru' AND SUBSCRIBERS.status = 'enabled'

SUBSCRIBERS.created_at > '2024-01-01' AND SUBSCRIBERS.attribs->>'plan' = 'premium'

Filter by Lists

Filter subscribers by:

List membership
Subscription status (unconfirmed/confirmed/unsubscribed)
Multiple list combinations

Subscriber Management

Bulk Operations

Perform actions on multiple subscribers:

Add to Lists: Subscribe to one or more lists
Remove from Lists: Delete subscriptions
Unsubscribe: Mark as unsubscribed from lists
Blocklist: Permanently block subscribers
Delete: Remove subscribers entirely

By Selection
By Query

Select specific subscriber IDs and apply bulk actions

Use search or SQL queries to target subscribers for bulk operations:

{
  "query": "SUBSCRIBERS.attribs->>'plan' = 'free'",
  "action": "add",
  "target_list_ids": [5],
  "status": "confirmed"
}

Managing List Subscriptions

For individual or bulk subscribers:

Add to Lists: Specify target lists and subscription status
Remove from Lists: Delete subscriber-list relationships
Unsubscribe: Sets subscription status to unsubscribed

Export Subscribers

Export subscriber data as CSV:

Choose Export Scope

All subscribers
Filtered by search/query
Selected subscribers by ID
By list or subscription status

Download CSV

CSV includes: UUID, email, name, attributes (JSON), status, created_at, updated_at

Privacy Features

listmonk includes built-in privacy tools configurable via settings:

Subscriber Self-Service

Blocklist

Allow subscribers to blocklist themselves (privacy.allow_blocklist)

Data Export

Let subscribers export their data (privacy.allow_export)

Preferences

Enable subscription preference management (privacy.allow_preferences)

Data Wipe

Allow subscribers to delete all their data (privacy.allow_wipe)

Data Export for Subscribers

Exportable data types (configured in privacy.exportable):

profile: Subscriber profile information
subscriptions: List memberships
campaign_views: View tracking data
link_clicks: Click tracking data

Exported as JSON with all requested data types.

Domain Filtering

Domain Blocklist: Prevent subscriptions from specific domains (privacy.domain_blocklist)
Domain Allowlist: Only allow subscriptions from specific domains (privacy.domain_allowlist)

Tracking Controls

Individual Tracking: Track opens/clicks per subscriber (privacy.individual_tracking)
Disable Tracking: Turn off all tracking (privacy.disable_tracking)
Record Opt-in IP: Store IP addresses during subscription (privacy.record_optin_ip)

Bounce Management

View and manage bounces for subscribers:

Bounces are tracked per subscriber and campaign
Types: soft, hard, complaint
Delete all bounces for a subscriber to reset their bounce count

Automatic Actions

Configure bounce handling in settings:

Soft bounces: Action after N occurrences
Hard bounces: Immediate blocklist
Complaints: Immediate blocklist

Subscriber Activity

View subscriber engagement:

Campaign Views: Which campaigns they opened
Link Clicks: Links they clicked with timestamps
Activity is tracked per campaign (if tracking is enabled)

Activity tracking requires privacy.individual_tracking to be enabled

Advanced Features

Orphan Subscribers

Subscribers not subscribed to any lists are considered “orphans” and tracked in dashboard statistics.

Double Opt-in Workflow

For lists with optin: double:

Subscriber Joins

New subscription is created with status unconfirmed

Confirmation Email Sent

System sends opt-in email with confirmation link

Subscriber Confirms

Clicking link changes status to confirmed

Manually trigger opt-in emails via the subscriber management interface.

Database Schema

CREATE TABLE subscribers (
    id              SERIAL PRIMARY KEY,
    uuid            UUID NOT NULL UNIQUE,
    email           TEXT NOT NULL UNIQUE,
    name            TEXT NOT NULL,
    attribs         JSONB NOT NULL DEFAULT '{}',
    status          subscriber_status NOT NULL DEFAULT 'enabled',
    created_at      TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at      TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

Subscription Relationship

CREATE TABLE subscriber_lists (
    subscriber_id   INTEGER REFERENCES subscribers(id),
    list_id         INTEGER REFERENCES lists(id),
    status          subscription_status NOT NULL DEFAULT 'unconfirmed',
    meta            JSONB NOT NULL DEFAULT '{}',
    created_at      TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at      TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    PRIMARY KEY(subscriber_id, list_id)
);

Subscription status values: unconfirmed, confirmed, unsubscribed

Get Started

Core Features

Configuration

Advanced

Development

​Subscriber Data Model

​Adding Subscribers

​Subscriber Statuses

Enabled

Disabled

Blocklisted

​Status vs Subscription Status

​Custom Attributes

​Using Attributes in Templates

​Querying and Filtering

​Search Subscribers

​SQL Queries

​Filter by Lists

​Subscriber Management

​Bulk Operations

​Managing List Subscriptions

​Export Subscribers

​Privacy Features

​Subscriber Self-Service

Blocklist

Data Export

Preferences

Data Wipe

​Data Export for Subscribers

​Domain Filtering

​Tracking Controls

​Bounce Management

​Automatic Actions

​Subscriber Activity

​Advanced Features

​Orphan Subscribers

​Double Opt-in Workflow

​Database Schema

​Subscription Relationship

Build docs developers (and LLMs) love

Subscriber Data Model

Adding Subscribers

Subscriber Statuses

Status vs Subscription Status

Custom Attributes

Using Attributes in Templates

Querying and Filtering

Search Subscribers

SQL Queries

Filter by Lists

Subscriber Management

Bulk Operations

Managing List Subscriptions

Export Subscribers

Privacy Features

Subscriber Self-Service

Data Export for Subscribers

Domain Filtering

Tracking Controls

Bounce Management

Automatic Actions

Subscriber Activity

Advanced Features

Orphan Subscribers

Double Opt-in Workflow

Database Schema

Subscription Relationship