Subscribers API - Listmonk

Query subscribers

curl -u 'username:password' 'https://listmonk.mysite.com/api/subscribers' \
  -G \
  -d 'page=1' \
  -d 'per_page=100' \
  -d 'list_id=1' \
  -d 'subscription_status=confirmed'

Retrieves a paginated list of subscribers with optional filtering. Authentication: Required
Permission: subscribers:get_all or subscribers:get

Query Parameters

page

integer

default:"1"

Page number for pagination

per_page

integer

default:"20"

Number of results per page (max 100)

query

string

SQL expression for advanced filtering (requires subscribers:sql_query permission)

string

Search term to filter subscribers by name or email

list_id

integer

Filter by list ID (can be specified multiple times)

subscription_status

string

Filter by subscription status: unconfirmed, confirmed, or unsubscribed

order_by

string

default:"id"

Field to order by: id, email, name, created_at, updated_at

order

string

default:"asc"

Sort order: asc or desc

Response

data

object

Show properties

results

array

Array of subscriber objects

Show subscriber object

integer

Subscriber ID

uuid

string

Unique UUID for the subscriber

string

Email address

name

string

Subscriber name

status

string

Status: enabled, disabled, or blocklisted

attribs

object

Custom attributes as key-value pairs

lists

array

Array of list subscriptions

created_at

string

Creation timestamp

updated_at

string

Last update timestamp

query

string

The SQL query used for filtering

total

integer

Total number of subscribers matching the query

per_page

integer

Results per page

page

integer

Current page number

Get subscriber

curl -u 'username:password' 'https://listmonk.mysite.com/api/subscribers/1'

Retrieves a single subscriber by ID. Authentication: Required
Permission: subscribers:get_all or subscribers:get

Path Parameters

integer

required

Subscriber ID

Response

Returns a single subscriber object with the same structure as the query endpoint.

Get subscriber activity

curl -u 'username:password' 'https://listmonk.mysite.com/api/subscribers/1/activity'

Retrieves a subscriber’s campaign views and link clicks. Authentication: Required
Permission: subscribers:get_all or subscribers:get

Path Parameters

integer

required

Subscriber ID

Response

data

object

Show properties

campaign_views

array

Array of campaign view records

link_clicks

array

Array of link click records

Export subscriber data

curl -u 'username:password' 'https://listmonk.mysite.com/api/subscribers/1/export' \
  -o subscriber-data.json

Exports a subscriber’s complete data including profile, subscriptions, campaign views, and link clicks as JSON. Authentication: Required
Permission: subscribers:get_all or subscribers:get

Path Parameters

integer

required

Subscriber ID

Response

Returns a JSON file download containing the subscriber’s complete data.

Create subscriber

curl -u 'username:password' 'https://listmonk.mysite.com/api/subscribers' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "john@example.com",
    "name": "John Doe",
    "status": "enabled",
    "lists": [1, 2],
    "attribs": {
      "city": "Bangalore",
      "projects": 3
    },
    "preconfirm_subscriptions": true
  }'

Creates a new subscriber. Authentication: Required
Permission: subscribers:manage

Request Body

string

required

Email address (must be valid and unique)

name

string

required

Subscriber name (max 2000 characters)

status

string

default:"enabled"

Subscriber status: enabled, disabled, or blocklisted

lists

array

Array of list IDs to subscribe to

attribs

object

Custom attributes as key-value pairs (JSON object)

preconfirm_subscriptions

boolean

default:"false"

If true, subscriptions are marked as confirmed without sending opt-in email

Response

Returns the created subscriber object.

Update subscriber

curl -u 'username:password' -X PUT 'https://listmonk.mysite.com/api/subscribers/1' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "john@example.com",
    "name": "John Doe Updated",
    "status": "enabled",
    "lists": [1, 3],
    "attribs": {
      "city": "New York",
      "projects": 5
    },
    "preconfirm_subscriptions": false
  }'

Updates an existing subscriber. Authentication: Required
Permission: subscribers:manage

Path Parameters

integer

required

Subscriber ID

Request Body

Same parameters as create subscriber. All fields are optional - only provided fields will be updated.

Send opt-in email

curl -u 'username:password' -X POST 'https://listmonk.mysite.com/api/subscribers/1/optin'

Sends a double opt-in confirmation email to a subscriber. Authentication: Required
Permission: subscribers:manage

Path Parameters

integer

required

Subscriber ID

Blocklist subscriber

curl -u 'username:password' -X PUT 'https://listmonk.mysite.com/api/subscribers/1/blocklist'

Blocklists a single subscriber. Authentication: Required
Permission: subscribers:manage

Path Parameters

integer

required

Subscriber ID

Blocklist subscribers (bulk)

curl -u 'username:password' -X PUT 'https://listmonk.mysite.com/api/subscribers/blocklist' \
  -H 'Content-Type: application/json' \
  -d '{"ids": [1, 2, 3]}'

Blocklists multiple subscribers. Authentication: Required
Permission: subscribers:manage

Request Body

ids

array

required

Array of subscriber IDs to blocklist

Manage subscriber lists

curl -u 'username:password' -X PUT 'https://listmonk.mysite.com/api/subscribers/lists/1' \
  -H 'Content-Type: application/json' \
  -d '{
    "ids": [1, 2, 3],
    "action": "add",
    "target_list_ids": [4, 5],
    "status": "confirmed"
  }'

Adds, removes, or unsubscribes subscribers from lists. Authentication: Required
Permission: subscribers:manage

Path Parameters

integer

List ID (optional when using request body ids)

Request Body

ids

array

required

Array of subscriber IDs

action

string

required

Action to perform: add, remove, or unsubscribe

target_list_ids

array

required

Array of list IDs to perform action on

status

string

Subscription status when adding: unconfirmed, confirmed, or unsubscribed

Delete subscriber

curl -u 'username:password' -X DELETE 'https://listmonk.mysite.com/api/subscribers/1'

Deletes a single subscriber permanently. Authentication: Required
Permission: subscribers:manage

Path Parameters

integer

required

Subscriber ID

Delete subscribers (bulk)

curl -u 'username:password' -X DELETE 'https://listmonk.mysite.com/api/subscribers?id=1&id=2&id=3'

Deletes multiple subscribers permanently. Authentication: Required
Permission: subscribers:manage

Query Parameters

integer

required

Subscriber ID (can be specified multiple times)

Delete subscribers by query

curl -u 'username:password' -X POST 'https://listmonk.mysite.com/api/subscribers/query/delete' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "subscribers.attribs->>\"city\" = \"Bangalore\"",
    "list_ids": [1, 2],
    "subscription_status": "unsubscribed"
  }'

Deletes subscribers based on an arbitrary SQL query. Authentication: Required
Permission: subscribers:manage and subscribers:sql_query

Request Body

query

string

SQL expression for filtering (requires subscribers:sql_query permission)

string

Search term to filter subscribers

list_ids

array

Filter by list IDs

subscription_status

string

Filter by subscription status

all

boolean

If true, deletes all subscribers (ignores other filters)

Blocklist subscribers by query

curl -u 'username:password' -X PUT 'https://listmonk.mysite.com/api/subscribers/query/blocklist' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "subscribers.attribs->>\"bounced\" = \"true\""
  }'

Blocklists subscribers based on an arbitrary SQL query. Authentication: Required
Permission: subscribers:manage and subscribers:sql_query

Request Body

Same parameters as delete by query.

Manage subscriber lists by query

curl -u 'username:password' -X PUT 'https://listmonk.mysite.com/api/subscribers/query/lists' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "subscribers.attribs->>\"city\" = \"Bangalore\"",
    "action": "add",
    "target_list_ids": [3],
    "status": "confirmed"
  }'

Manages list subscriptions for subscribers matching a query. Authentication: Required
Permission: subscribers:manage and subscribers:sql_query

Request Body

query

string

SQL expression for filtering

string

Search term

list_ids

array

Source list IDs to filter by

target_list_ids

array

required

Target list IDs for the action

action

string

required

Action: add, remove, or unsubscribe

status

string

Subscription status when adding

subscription_status

string

Filter by current subscription status

Export subscribers (CSV)

curl -u 'username:password' 'https://listmonk.mysite.com/api/subscribers/export' \
  -G \
  -d 'list_id=1' \
  -d 'subscription_status=confirmed' \
  -o subscribers.csv

Exports subscribers as a CSV file. Authentication: Required
Permission: subscribers:get_all or subscribers:get

Query Parameters

list_id

integer

Filter by list ID

integer

Export specific subscriber IDs (can be specified multiple times)

subscription_status

string

Filter by subscription status

query

string

SQL expression for filtering

string

Search term

Response

Returns a CSV file with columns: uuid, email, name, attributes, status, created_at, updated_at

Get subscriber bounces

curl -u 'username:password' 'https://listmonk.mysite.com/api/subscribers/1/bounces'

Retrieves bounce records for a subscriber. Authentication: Required
Permission: bounces:get

Path Parameters

integer

required

Subscriber ID

Delete subscriber bounces

curl -u 'username:password' -X DELETE 'https://listmonk.mysite.com/api/subscribers/1/bounces'

Deletes all bounce records for a subscriber. Authentication: Required
Permission: bounces:manage

Path Parameters

integer

required

Subscriber ID

API Overview

Endpoints

​Query subscribers

​Query Parameters

​Response

​Get subscriber

​Path Parameters

​Response

​Get subscriber activity

​Path Parameters

​Response

​Export subscriber data

​Path Parameters

​Response

​Create subscriber

​Request Body

​Response

​Update subscriber

​Path Parameters

​Request Body

​Send opt-in email

​Path Parameters

​Blocklist subscriber

​Path Parameters

​Blocklist subscribers (bulk)

​Request Body

​Manage subscriber lists

​Path Parameters

​Request Body

​Delete subscriber

​Path Parameters

​Delete subscribers (bulk)

​Query Parameters

​Delete subscribers by query

​Request Body

​Blocklist subscribers by query

​Request Body

​Manage subscriber lists by query

​Request Body

​Export subscribers (CSV)

​Query Parameters

​Response

​Get subscriber bounces

​Path Parameters

​Delete subscriber bounces

​Path Parameters

Build docs developers (and LLMs) love

Query subscribers

Query Parameters

Response

Get subscriber

Path Parameters

Response

Get subscriber activity

Path Parameters

Response

Export subscriber data

Path Parameters

Response

Create subscriber

Request Body

Response

Update subscriber

Path Parameters

Request Body

Send opt-in email

Path Parameters

Blocklist subscriber

Path Parameters

Blocklist subscribers (bulk)

Request Body

Manage subscriber lists

Path Parameters

Request Body

Delete subscriber

Path Parameters

Delete subscribers (bulk)

Query Parameters

Delete subscribers by query

Request Body

Blocklist subscribers by query

Request Body

Manage subscriber lists by query

Request Body

Export subscribers (CSV)

Query Parameters

Response

Get subscriber bounces

Path Parameters

Delete subscriber bounces

Path Parameters