API / Subscribers¶
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/subscribers | Query and retrieve subscribers. |
| GET | /api/subscribers/{subscriber_id} | Retrieve a specific subscriber. |
| GET | /api/subscribers/{subscriber_id}/export | Export a specific subscriber. |
| GET | /api/subscribers/{subscriber_id}/bounces | Retrieve a subscriber bounce records. |
| POST | /api/subscribers | Create a new subscriber. |
| POST | /api/subscribers/{subscriber_id}/optin | Sends optin confirmation email to subscribers. |
| POST | /api/public/subscription | Create a public subscription. |
| PUT | /api/subscribers/lists | Modify subscriber list memberships. |
| PUT | /api/subscribers/query/lists | Bulk modify list memberships using SQL/Search queries. |
| PUT | /api/subscribers/{subscriber_id} | Update a specific subscriber. |
| PATCH | /api/subscribers/{subscriber_id} | Partially update a specific subscriber. |
| PUT | /api/subscribers/{subscriber_id}/blocklist | Blocklist a specific subscriber. |
| PUT | /api/subscribers/blocklist | Blocklist one or many subscribers. |
| PUT | /api/subscribers/query/blocklist | Blocklist subscribers based on SQL expression. |
| DELETE | /api/subscribers/{subscriber_id} | Delete a specific subscriber. |
| DELETE | /api/subscribers/{subscriber_id}/bounces | Delete a specific subscriber's bounce records. |
| DELETE | /api/subscribers/{subscriber_id}/activity/{type} | Clear a subscriber's campaign views or link clicks. |
| DELETE | /api/subscribers | Delete one or more subscribers. |
| POST | /api/subscribers/query/delete | Delete subscribers based on SQL expression. |
GET /api/subscribers¶
Retrieve all subscribers.
Query parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | Subscriber search by SQL expression. | |
| list_id | int[] | ID of lists to filter by. Repeat in the query for multiple values. | |
| subscription_status | string | Subscription status to filter by if there are one or more list_ids. |
|
| order_by | string | Result sorting field. Options: name, status, created_at, updated_at. | |
| order | string | Sorting order: ASC for ascending, DESC for descending. | |
| page | number | Page number for paginated results. | |
| per_page | number | Results per page. Set as 'all' for all results. |
Example Request¶
curl -u 'api_username:access_token' 'http://localhost:9000/api/subscribers?page=1&per_page=100'
curl -u 'api_username:access_token' 'http://localhost:9000/api/subscribers?list_id=1&list_id=2&page=1&per_page=100'
curl -u 'api_username:access_token' -X GET 'http://localhost:9000/api/subscribers' \
--url-query 'page=1' \
--url-query 'per_page=100' \
--url-query "query=subscribers.name LIKE 'Test%' AND subscribers.attribs->>'city' = 'Bengaluru'"
Example Response¶
{
"data": {
"results": [
{
"id": 1,
"created_at": "2020-02-10T23:07:16.199433+01:00",
"updated_at": "2020-02-10T23:07:16.199433+01:00",
"uuid": "ea06b2e7-4b08-4697-bcfc-2a5c6dde8f1c",
"email": "john@example.com",
"name": "John Doe",
"attribs": {
"city": "Bengaluru",
"good": true,
"type": "known"
},
"status": "enabled",
"lists": [
{
"subscription_status": "unconfirmed",
"id": 1,
"uuid": "ce13e971-c2ed-4069-bd0c-240e9a9f56f9",
"name": "Default list",
"type": "public",
"tags": [
"test"
],
"created_at": "2020-02-10T23:07:16.194843+01:00",
"updated_at": "2020-02-10T23:07:16.194843+01:00"
}
]
},
{
"id": 2,
"created_at": "2020-02-18T21:10:17.218979+01:00",
"updated_at": "2020-02-18T21:10:17.218979+01:00",
"uuid": "ccf66172-f87f-4509-b7af-e8716f739860",
"email": "quadri@example.com",
"name": "quadri",
"attribs": {},
"status": "enabled",
"lists": [
{
"subscription_status": "unconfirmed",
"id": 1,
"uuid": "ce13e971-c2ed-4069-bd0c-240e9a9f56f9",
"name": "Default list",
"type": "public",
"tags": [
"test"
],
"created_at": "2020-02-10T23:07:16.194843+01:00",
"updated_at": "2020-02-10T23:07:16.194843+01:00"
}
]
},
{
"id": 3,
"created_at": "2020-02-19T19:10:49.36636+01:00",
"updated_at": "2020-02-19T19:10:49.36636+01:00",
"uuid": "5d940585-3cc8-4add-b9c5-76efba3c6edd",
"email": "sugar@example.com",
"name": "sugar",
"attribs": {},
"status": "enabled",
"lists": []
}
],
"query": "",
"total": 3,
"per_page": 20,
"page": 1
}
}
GET /api/subscribers/{subscriber_id}¶
Retrieve a specific subscriber.
Parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
| subscriber_id | Number | Yes | Subscriber's ID. |
Example Request¶
curl -u 'api_username:access_token' 'http://localhost:9000/api/subscribers/1'
Example Response¶
{
"data": {
"id": 1,
"created_at": "2020-02-10T23:07:16.199433+01:00",
"updated_at": "2020-02-10T23:07:16.199433+01:00",
"uuid": "ea06b2e7-4b08-4697-bcfc-2a5c6dde8f1c",
"email": "john@example.com",
"name": "John Doe",
"attribs": {
"city": "Bengaluru",
"good": true,
"type": "known"
},
"status": "enabled",
"lists": [
{
"subscription_status": "unconfirmed",
"id": 1,
"uuid": "ce13e971-c2ed-4069-bd0c-240e9a9f56f9",
"name": "Default list",
"type": "public",
"tags": [
"test"
],
"created_at": "2020-02-10T23:07:16.194843+01:00",
"updated_at": "2020-02-10T23:07:16.194843+01:00"
}
]
}
}
GET /api/subscribers/{subscriber_id}/export¶
Export a specific subscriber data that gives profile, list subscriptions, campaign views and link clicks information. Names of private lists are replaced with "Private list".
Parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
| subscriber_id | Number | Yes | Subscriber's ID. |
Example Request¶
curl -u 'api_username:access_token' 'http://localhost:9000/api/subscribers/1/export'
Example Response¶
{
"profile": [
{
"id": 1,
"uuid": "c2cc0b31-b485-4d72-8ce8-b47081beadec",
"email": "john@example.com",
"name": "John Doe",
"attribs": {
"city": "Bengaluru",
"good": true,
"type": "known"
},
"status": "enabled",
"created_at": "2024-07-29T11:01:31.478677+05:30",
"updated_at": "2024-07-29T11:01:31.478677+05:30"
}
],
"subscriptions": [
{
"subscription_status": "unconfirmed",
"name": "Private list",
"type": "private",
"created_at": "2024-07-29T11:01:31.478677+05:30"
}
],
"campaign_views": [],
"link_clicks": []
}
GET /api/subscribers/{subscriber_id}/bounces¶
Get a specific subscriber bounce records.
Parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
| subscriber_id | Number | Yes | Subscriber's ID. |
Example Request¶
curl -u 'api_username:access_token' 'http://localhost:9000/api/subscribers/1/bounces'
Example Response¶
{
"data": [
{
"id": 841706,
"type": "hard",
"source": "demo",
"meta": {
"some": "parameter"
},
"created_at": "2024-08-22T09:05:12.862877Z",
"email": "thomas.hobbes@example.com",
"subscriber_uuid": "137c0d83-8de6-44e2-a55f-d4238ab21969",
"subscriber_id": 99,
"campaign": {
"id": 2,
"name": "Welcome to listmonk"
}
},
{
"id": 841680,
"type": "hard",
"source": "demo",
"meta": {
"some": "parameter"
},
"created_at": "2024-08-19T14:07:53.141917Z",
"email": "thomas.hobbes@example.com",
"subscriber_uuid": "137c0d83-8de6-44e2-a55f-d4238ab21969",
"subscriber_id": 99,
"campaign": {
"id": 1,
"name": "Test campaign"
}
}
]
}
POST /api/subscribers¶
Create a new subscriber.
Parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
| string | Yes | Subscriber's email address. | |
| name | string | Yes | Subscriber's name. |
| status | string | Yes | Subscriber's status: enabled, blocklisted. |
| lists | number[] | List of list IDs to subscribe to. | |
| attribs | JSON | Optional JSON object attributes for the subscriber that can be used in message templates. Example {"location": "Somewhere"} |
|
| preconfirm_subscriptions | bool | If true, subscriptions are marked as confirmed and no opt-in emails are sent for double opt-in lists. |
Example Request¶
curl -u 'api_username:access_token' 'http://localhost:9000/api/subscribers' -H 'Content-Type: application/json' \
--data '{"email":"subscriber@domain.com","name":"The Subscriber","status":"enabled","lists":[1],"attribs":{"city":"Bengaluru","projects":3,"stack":{"languages":["go","python"]}}}'
Example Response¶
{
"data": {
"id": 3,
"created_at": "2019-07-03T12:17:29.735507+05:30",
"updated_at": "2019-07-03T12:17:29.735507+05:30",
"uuid": "eb420c55-4cfb-4972-92ba-c93c34ba475d",
"email": "subscriber@domain.com",
"name": "The Subscriber",
"attribs": {
"city": "Bengaluru",
"projects": 3,
"stack": { "languages": ["go", "python"] }
},
"status": "enabled",
"lists": [1]
}
}
POST /api/subscribers/{subscribers_id}/optin¶
Sends opt-in confirmation email to subscribers.
Example Request¶
curl -u 'api_username:access_token' 'http://localhost:9000/api/subscribers/11/optin' -H 'Content-Type: application/json' \
--data {}
Example Response¶
{
"data": true
}
POST /api/public/subscription¶
Create a public subscription, accepts both form encoded or JSON encoded body.
Requires Enable public subscription API turned on in Settings → General. This is independent of the public subscription page. Note that this API does not enforce CAPTCHA and if you are turning it on, you might want to configure rate limits and other protections in a reverse proxy or WAF.
Parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
| string | Yes | Subscriber's email address. | |
| name | string | Subscriber's name. | |
| list_uuids | string[] | Yes | List of list UUIDs. |
Example JSON Request¶
curl 'http://localhost:9000/api/public/subscription' -H 'Content-Type: application/json' \
--data '{"email":"subscriber@domain.com","name":"The Subscriber","list_uuids": ["eb420c55-4cfb-4972-92ba-c93c34ba475d", "0c554cfb-eb42-4972-92ba-c93c34ba475d"]}'
Example Form Request¶
curl -u 'http://localhost:9000/api/public/subscription' \
-d 'email=subscriber@domain.com' -d 'name=The Subscriber' -d 'l=eb420c55-4cfb-4972-92ba-c93c34ba475d' -d 'l=0c554cfb-eb42-4972-92ba-c93c34ba475d'
Note: For form request, use l for multiple lists instead of lists.
Example Response¶
{
"data": true
}
PUT /api/subscribers/lists¶
Modify subscriber list memberships.
Parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
| ids | number[] | Yes | Array of user IDs to be modified. |
| action | string | Yes | Action to be applied: add, remove, or unsubscribe. |
| target_list_ids | number[] | Yes | Array of list IDs to be modified. |
| status | string | Required for add |
Subscriber status: confirmed, unconfirmed, or unsubscribed. |
Example Request¶
curl -u 'api_username:access_token' -X PUT 'http://localhost:9000/api/subscribers/lists' \
-H 'Content-Type: application/json' \
--data-raw '{"ids": [1, 2, 3], "action": "add", "target_list_ids": [4, 5, 6], "status": "confirmed"}'
Example Response¶
{
"data": true
}
PUT /api/subscribers/query/lists¶
Modify list memberships for multiple subscribers dynamically using a search query and/or SQL expression.
Parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | Action to be applied: add, remove, or unsubscribe. |
| target_list_ids | number[] | Yes | Array of list IDs that the matching subscribers should be added to or removed from. |
| query | string | No | SQL expression to filter subscribers (e.g., subscribers.email LIKE '%@domain.com'). |
| search | string | No | Free-text search string targeting name, email, or other general text attributes. |
| list_ids | number[] | No | Optional list IDs to limit the query filter scope (only checks subscribers in these source lists). |
| status | string | Required for add |
Subscription status to set when subscribing: confirmed, unconfirmed, or unsubscribed. |
| subscription_status | string | No | Optional subscription status filter to apply to the source lists specified in list_ids. |
Example Requests¶
Subscribing Query Matches to a List¶
curl -u 'api_username:access_token' -X PUT 'http://localhost:9000/api/subscribers/query/lists' \
-H 'Content-Type: application/json' \
--data-raw '{
"query": "subscribers.email LIKE '\''%@domain.com'\''",
"action": "add",
"target_list_ids": [3],
"status": "confirmed"
}'
Removing Disqualified Subscribers from a List¶
curl -u 'api_username:access_token' -X PUT 'http://localhost:9000/api/subscribers/query/lists' \
-H 'Content-Type: application/json' \
--data-raw '{
"query": "NOT subscribers.email LIKE '\''%@domain.com'\''",
"action": "remove",
"target_list_ids": [3]
}'
Example Response¶
{
"data": true
}
PUT /api/subscribers/{subscriber_id}¶
Update a specific subscriber.
Refer to parameters from POST /api/subscribers. Note: All parameters must be set, if not, the subscriber will be removed from all previously assigned lists.
PATCH /api/subscribers/{subscriber_id}¶
Partially update a subscriber. Only fields present in the request body are updated. Unlike PUT, omitting the lists field preserves existing list subscriptions. PUT treats empty lists as a signal to clear all subscriptions.
Parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
| string | Subscriber's email address. Updated only if provided. | ||
| name | string | Subscriber's name. Updated only if provided. | |
| status | string | Subscriber's status: enabled, disabled, blocklisted. Updated only if provided. |
|
| lists | number[] | Array of list IDs. If provided, replaces the subscriber's current list subscriptions. If omitted, existing subscriptions are kept. | |
| attribs | JSON | JSON object of subscriber attributes. If provided, merged with existing attributes. | |
| preconfirm_subscriptions | bool | If true, subscriptions are marked as confirmed and no opt-in emails are sent for double opt-in lists. |
Example Request¶
curl -u 'api_username:access_token' -X PATCH 'http://localhost:9000/api/subscribers/1' \
-H 'Content-Type: application/json' \
--data '{"name":"Updated Name"}'
Example Response¶
{
"data": {
"id": 1,
"created_at": "2020-02-10T23:07:16.199433+01:00",
"updated_at": "2020-03-10T16:37:17.228327+01:00",
"uuid": "ea06b2e7-4b08-4571-b436-5c5cf31c5cd4",
"email": "subscriber@domain.com",
"name": "Updated Name",
"attribs": {},
"status": "enabled",
"lists": [{
"subscription_status": "unconfirmed",
"id": 1,
"uuid": "ce13e971-c2ed-4069-bd0c-240e9a9f56f9",
"name": "Default list",
"type": "public",
"optin": "single"
}]
}
}
PUT /api/subscribers/{subscriber_id}/blocklist¶
Blocklist a specific subscriber.
Parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
| subscriber_id | Number | Yes | Subscriber's ID. |
Example Request¶
curl -u 'api_username:access_token' -X PUT 'http://localhost:9000/api/subscribers/9/blocklist'
Example Response¶
{
"data": true
}
PUT /api/subscribers/blocklist¶
Blocklist multiple subscriber.
Parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
| ids | Number | Yes | Subscriber's ID. |
Example Request¶
curl -u 'api_username:access_token' -X PUT 'http://localhost:8080/api/subscribers/blocklist' -H 'Content-Type: application/json' --data-raw '{"ids":[2,1]}'
Example Response¶
{
"data": true
}
PUT /api/subscribers/query/blocklist¶
Blocklist subscribers based on SQL expression.
Refer to the querying and segmentation section for more information on how to query subscribers with SQL expressions.
Parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | SQL expression to filter subscribers with. |
| list_ids | []number | No | Optional list IDs to limit the filtering to. |
Example Request¶
curl -u 'api_username:access_token' -X POST 'http://localhost:9000/api/subscribers/query/blocklist' \
-H 'Content-Type: application/json' \
--data-raw '{"query":"subscribers.name LIKE \'John Doe\' AND subscribers.attribs->>'\''city'\'' = '\''Bengaluru'\''"}'
Example Response¶
{
"data": true
}
DELETE /api/subscribers/{subscriber_id}¶
Delete a specific subscriber.
Parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
| subscriber_id | Number | Yes | Subscriber's ID. |
Example Request¶
curl -u 'api_username:access_token' -X DELETE 'http://localhost:9000/api/subscribers/9'
Example Response¶
{
"data": true
}
DELETE /api/subscribers/{subscriber_id}/bounces¶
Delete a subscriber's bounce records
Parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
| id | subscriber_id | Yes | Subscriber's ID. |
Example Request¶
curl -u 'api_username:access_token' -X DELETE 'http://localhost:9000/api/subscribers/9/bounces'
Example Response¶
{
"data": true
}
DELETE /api/subscribers/{subscriber_id}/activity/{type}¶
Clear a subscriber's activity. type must be campaign_views or link_clicks.
Only the selected activity type is deleted. Requires subscribers:manage and access to the subscriber.
Example Request¶
curl -u 'api_username:access_token' -X DELETE 'http://localhost:9000/api/subscribers/1/activity/campaign_views'
Example Response¶
{
"data": true
}
DELETE /api/subscribers¶
Delete one or more subscribers.
Parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
| id | number[] | Yes | Array of subscriber's IDs. |
Example Request¶
curl -u 'api_username:access_token' -X DELETE 'http://localhost:9000/api/subscribers?id=10&id=11'
Example Response¶
{
"data": true
}
POST /api/subscribers/query/delete¶
Delete subscribers based on SQL expression.
Parameters¶
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | No | SQL expression to filter subscribers with. |
| list_ids | []number | No | Optional list IDs to limit the filtering to. |
| all | bool | No | When set to true, ignores any query and deletes all subscribers. |
Example Request¶
curl -u 'api_username:access_token' -X POST 'http://localhost:9000/api/subscribers/query/delete' \
-H 'Content-Type: application/json' \
--data-raw '{"query":"subscribers.name LIKE \'John Doe\' AND subscribers.attribs->>'\''city'\'' = '\''Bengaluru'\''"}'
Example Response¶
{
"data": true
}