Skip to content

API / Subscribers

Method Endpoint Description
GET /api/subscribers Gets all subscribers.
GET /api/subscribers/:id Gets a single subscriber.
GET /api/subscribers/lists/:id Gets subscribers in a list.
GET /api/subscribers Gets subscribers in one or more lists.
GET /api/subscribers Gets subscribers filtered by an arbitrary SQL expression.
POST /api/subscribers Creates a new subscriber.
POST /api/public/subscription Unauthenticated API that enables public subscription.
PUT /api/subscribers/lists Modify subscribers' list memberships.
PUT /api/subscribers/:id Updates a subscriber by ID.
PUT /api/subscribers/:id/blocklist Blocklists a single subscriber.
PUT /api/subscribers/blocklist Blocklists one or more subscribers.
PUT /api/subscribers/query/blocklist Blocklists subscribers with an arbitrary SQL expression.
DELETE /api/subscribers/:id Deletes a single subscriber.
DELETE /api/subscribers Deletes one or more subscribers .
POST /api/subscribers/query/delete Deletes subscribers with an arbitrary SQL expression.

GET /api/subscribers

Gets all subscribers.

Example Request
curl -u 'username:password' 'http://localhost:9000/api/subscribers?page=1&per_page=100' 

To skip pagination and retrieve all records, pass per_page=all.

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/:id

Gets a single subscriber.

Parameters
Name Parameter type Data type Required/Optional Description
id Path parameter Number Required The id value of the subscriber you want to get.
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

Gets subscribers in one or more lists.

Parameters
Name Parameter type Data type Required/Optional Description
List_id Request body Number Required ID of the list to fetch subscribers from.
Example Request
curl -u 'username:password' 'http://localhost:9000/api/subscribers?list_id=1&list_id=2&page=1&per_page=100'

To skip pagination and retrieve all records, pass per_page=all.

Example Response
{
  "data": {
    "results": [
      {
        "id": 1,
        "created_at": "2019-06-26T16:51:54.37065+05:30",
        "updated_at": "2019-07-03T11:53:53.839692+05:30",
        "uuid": "5e91dda1-1c16-467d-9bf9-2a21bf22ae21",
        "email": "test@test.com",
        "name": "Test Subscriber",
        "attribs": {
          "city": "Bengaluru",
          "projects": 3,
          "stack": {
            "languages": ["go", "python"]
          }
        },
        "status": "enabled",
        "lists": [
          {
            "subscription_status": "unconfirmed",
            "id": 1,
            "uuid": "41badaf2-7905-4116-8eac-e8817c6613e4",
            "name": "Default list",
            "type": "public",
            "tags": ["test"],
            "created_at": "2019-06-26T16:51:54.367719+05:30",
            "updated_at": "2019-06-26T16:51:54.367719+05:30"
          }
        ]
      }
    ],
    "query": "",
    "total": 1,
    "per_page": 20,
    "page": 1
  }
}

GET /api/subscribers

Gets subscribers with an SQL expression.

Example Request
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'"

To skip pagination and retrieve all records, pass per_page=all.

Refer to the querying and segmentation section for more information on how to query subscribers with SQL expressions.

Example Response
{
  "data": {
    "results": [
      {
        "id": 1,
        "created_at": "2019-06-26T16:51:54.37065+05:30",
        "updated_at": "2019-07-03T11:53:53.839692+05:30",
        "uuid": "5e91dda1-1c16-467d-9bf9-2a21bf22ae21",
        "email": "test@test.com",
        "name": "Test Subscriber",
        "attribs": {
          "city": "Bengaluru",
          "projects": 3,
          "stack": {
            "frameworks": ["echo", "go"],
            "languages": ["go", "python"]
          }
        },
        "status": "enabled",
        "lists": [
          {
            "subscription_status": "unconfirmed",
            "id": 1,
            "uuid": "41badaf2-7905-4116-8eac-e8817c6613e4",
            "name": "Default list",
            "type": "public",
            "tags": ["test"],
            "created_at": "2019-06-26T16:51:54.367719+05:30",
            "updated_at": "2019-06-26T16:51:54.367719+05:30"
          }
        ]
      }
    ],
    "query": "subscribers.name LIKE 'Test%' AND subscribers.attribs-\u003e\u003e'city' = 'Bengaluru'",
    "total": 1,
    "per_page": 20,
    "page": 1
  }
}

POST /api/subscribers

Creates a new subscriber.

Parameters
Name Parameter type Data type Required/Optional Description
email Request body String Required The email address of the new subscriber.
name Request body String Required The name of the new subscriber.
status Request body String Required The status of the new subscriber. Can be enabled, disabled or blocklisted.
lists Request body Numbers Optional Array of list IDs to subscribe to (marked as unconfirmed by default).
attribs Request body json Optional JSON list containing new subscriber's attributes.
preconfirm_subscriptions Request body Bool Optional If true, marks subscriptions as confirmed and no-optin e-mails 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/public/subscription

This is a public, unauthenticated API meant for directly integrating forms for public subscription. The API supports both form encoded or a JSON encoded body.

Parameters
Name Parameter type Data type Required/Optional Description
email Request body String Required The email address of the subscriber.
name Request body String Optional The name of the new subscriber.
list_uuids Request body Strings Required Array 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'

Notice that in form request, there param is l that is repeated for multiple lists, and not lists like in JSON.

Example Response
{
  "data": true
}

PUT /api/subscribers/lists

Modify subscribers list memberships.

Parameters
Name Parameter type Data type Required/Optional Description
ids Request body Numbers Required The ids of the subscribers to be modified.
action Request body String Required Whether to add, remove, or unsubscribe the users.
target_list_ids Request body Numbers Required The ids of the lists to be modified.
status Request body String Required for add confirmed, unconfirmed, or unsubscribed status.
Example Request

To subscribe users 1, 2, and 3 to lists 4, 5, and 6:

curl -u 'username:password' -X PUT 'http://localhost:9000/api/subscribers/lists' \
--data-raw '{"ids": [1, 2, 3], "action": "add", "target_list_ids": [4, 5, 6], "status": "confirmed"}'
Example Response
{
    "data": true
} 

PUT /api/subscribers/:id

Updates a single subscriber.

Parameters

Parameters are the same as POST /api/subscribers used for subscriber creation.

Please note that this is a PUT request, so all the parameters have to be set. For example if you don't provide lists, the subscriber will be deleted from all the lists he was previously signed on.

PUT /api/subscribers/:id/blocklist

Blocklists a single subscriber.

Parameters
Name Parameter type Data type Required/Optional Description
id Path parameter Number Required The id value of the subscriber you want to blocklist.
Example Request
curl -u 'username:password' -X PUT 'http://localhost:9000/api/subscribers/9/blocklist'
Example Response
{
    "data": true
} 

PUT /api/subscribers/query/blocklist

Blocklists subscribers with an arbitrary sql expression.

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'\''"'

Refer to the querying and segmentation section for more information on how to query subscribers with SQL expressions.

Example Response
{
    "data": true
}

DELETE /api/subscribers/:id

Deletes a single subscriber.

Parameters
Name Parameter type Data type Required/Optional Description
id Path parameter Number Required The id of the subscriber you want to delete.
Example Request
curl -u 'username:password' -X DELETE 'http://localhost:9000/api/subscribers/9'
Example Response
{
    "data": true
}

DELETE /api/subscribers

Deletes one or more subscribers.

Parameters
Name Parameter type Data type Required/Optional Description
id Query parameters Number Required The id of the subscribers you want to delete.
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

Deletes subscribers with an arbitrary 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'\''"'

Refer to the querying and segmentation section for more information on how to query subscribers with SQL expressions.

Example Response
{
    "data": true
}