Skip to content

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_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 'username:password' 'http://localhost:9000/api/subscribers?page=1&per_page=100' 
curl -u 'username:password' 'http://localhost:9000/api/subscribers?list_id=1&list_id=2&page=1&per_page=100'
curl -u 'username:password' -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 'username:password' '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 'username:password' '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 'username:password' '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
email 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 'username:password' '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 'username:password' '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
email 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 'username:password' -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 'username:password' -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 'username:password' -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.

Example Request
curl -u 'username:password' -X PUT 'http://localhost:9000/api/subscribers/query/blocklist' \
--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 'username:password' -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 'username:password' -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 'username:password' -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.

Example Request
curl -u 'username:password' -X POST 'http://localhost:9000/api/subscribers/query/delete' \
--data-raw '"query=subscribers.name LIKE '\''John Doe'\'' AND subscribers.attribs->>'\''city'\'' = '\''Bengaluru'\''"'
Example Response
{
    "data": true
}