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/{subscriber_id} | 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 | 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_id s. |
|
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 curl -u 'api_username:access_token' 'http://localhost:9000/api/subscribers?page=1&per_page=100'
curl -u curl -u 'api_username:access_token' 'http://localhost:9000/api/subscribers?list_id=1&list_id=2&page=1&per_page=100'
curl -u 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 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 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 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 | Attributes of the new subscriber. | |
preconfirm_subscriptions | bool | If true, subscriptions are marked as confirmed and no-optin emails are sent for double opt-in lists. |
Example Request¶
curl -u curl -u 'api_username:access_token' 'http://localhost:9000/api/subscribers' -H 'Content-Type: application/json' \
--data '{"email":"subsriber@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": "subsriber@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 optin confirmation email to subscribers.
Example Request¶
curl -u 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.
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":"subsriber@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=subsriber@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 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/{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.
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 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 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 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 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 curl -u 'api_username:access_token' -X DELETE 'http://localhost:9000/api/subscribers/9/bounces'
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 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 | Yes | SQL expression to filter subscribers with. |
list_ids | []number | No | Optional list IDs to limit the filtering to. |
Example Request¶
curl -u 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
}