Skip to main content

​
Query lists

curl -u 'username:password' 'https://listmonk.mysite.com/api/lists' \
  -G \
  -d 'page=1' \
  -d 'per_page=100'
Retrieves all mailing lists with subscriber counts. Authentication: Required
Permission: Filtered by user’s list permissions

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination
​
per_page
integer
default:"20"
Number of results per page
​
query
string
Search term to filter lists by name
​
tag
string
Filter by tag (can be specified multiple times)
​
type
string
Filter by type: private or public
​
optin
string
Filter by opt-in type: single or double
​
status
string
Filter by status: active or archived
​
order_by
string
default:"created_at"
Field to order by: id, name, created_at, updated_at
​
order
string
default:"asc"
Sort order: asc or desc
​
minimal
boolean
default:"false"
If true, returns minimal list data without subscriber counts (faster)

​
Response

​
data
object

​
Get list

curl -u 'username:password' 'https://listmonk.mysite.com/api/lists/1'
Retrieves a single list by ID. Authentication: Required
Permission: User must have get permission for the list

​
Path Parameters

​
id
integer
required
List ID

​
Response

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

​
Create list

curl -u 'username:password' 'https://listmonk.mysite.com/api/lists' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My New List",
    "type": "private",
    "optin": "double",
    "status": "active",
    "tags": ["customers", "newsletter"],
    "description": "Monthly newsletter subscribers"
  }'
Creates a new mailing list. Authentication: Required
Permission: lists:manage_all

​
Request Body

​
name
string
required
List name (max 2000 characters, must be unique)
​
type
string
default:"private"
List type: private (not shown on public pages) or public (shown on public subscription pages)
​
optin
string
default:"single"
Opt-in type:
  • single: Subscribers are automatically confirmed
  • double: Subscribers receive a confirmation email
​
status
string
default:"active"
Status: active or archived
​
tags
array
Array of tags (strings) for categorization
​
description
string
Optional description of the list

​
Response

​
data
object
Returns the created list object

​
Update list

curl -u 'username:password' -X PUT 'https://listmonk.mysite.com/api/lists/1' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated List Name",
    "type": "public",
    "optin": "single",
    "status": "active",
    "tags": ["updated", "newsletter"],
    "description": "Updated description"
  }'
Updates an existing list. Authentication: Required
Permission: User must have manage permission for the list

​
Path Parameters

​
id
integer
required
List ID

​
Request Body

Same parameters as create list. All fields are optional - only provided fields will be updated.
​
name
string
List name (max 2000 characters)
​
type
string
List type: private or public
​
optin
string
Opt-in type: single or double
​
status
string
Status: active or archived
​
tags
array
Array of tags
​
description
string
List description

​
Response

​
data
object
Returns the updated list object

​
Delete list

curl -u 'username:password' -X DELETE 'https://listmonk.mysite.com/api/lists/1'
Deletes a single list. This will also remove all subscriber associations with the list. Authentication: Required
Permission: User must have manage permission for the list

​
Path Parameters

​
id
integer
required
List ID

​
Response

​
data
boolean
Returns true on successful deletion

​
Delete lists (bulk)

curl -u 'username:password' -X DELETE 'https://listmonk.mysite.com/api/lists?id=1&id=2&id=3'
Deletes multiple lists by IDs or by query. Authentication: Required
Permission: User must have manage permission for each list

​
Query Parameters

​
id
integer
List ID to delete (can be specified multiple times)
​
query
string
Search term to match list names for deletion
​
all
boolean
If true, deletes all lists (use with caution)

​
Response

​
data
boolean
Returns true on successful deletion
Deleting lists will permanently remove all subscriber associations with those lists. This action cannot be undone.

Build docs developers (and LLMs) love

Get started for freeTalk to us