Lists

The Lists SDK methods lets you create / manage list of subscribers. You can then send broadcast to all the users in the list or create a workflow that triggers when a new user enters / exits list.

Create / Update List

You can use supr_client.subscribers_list.create method to create a new list

const { Suprsend } = require("@suprsend/node-sdk");

const supr_client = new Suprsend("workspace_key", "workspace_secret");

// create list API call
const response = supr_client.subscriber_lists.create({
  list_id: "_list_id_",
  list_name: "_list_name_",
  list_description: "_some sample descritpion for list_",
});

data.then((res) => console.log(res)).catch((err) => console.log(err));

{
   "list_id":"_list_id_",
   "list_name":"_list_name_",
   "list_description":"_some sample description for the list_",
   "list_type":"static_list",
   "subscribers_count":0,
   "source":"None",
   "is_readonly":false,
   "status":"active",
   "track_user_entry":false,
   "track_user_exit":false,
   "requested_for_delete":false,
   "created_at":"2025-03-14T13:42:45.641000Z",
   "updated_at":"2025-03-14T13:42:45.641000Z",
   "drafts":"None"
}

Guidelines on defining the list_id

list_id is case-insensitive. Suprsend first converts list_id to lowercase before storing it or doing any sort of comparison on it.
list_id can be of max 64 characters.
It can contain characters [a-z0-9_-] that is alphanumeric characters, _(underscore) and -(hyphen).

Get list data

You can get the latest information of a list using supr_client.subscribers_list.get method.

const data = supr_client.subscriber_lists.get("_list_id_");

{
	"list_id": "list-id",
	"list_name": "List Name",
  "updated_at": "2022-12-18T10:40:27.268417+00:00",
	"list_description": "List description"
}

Get list of lists

To get the data of all the lists created in your workspace, use supr_client.subscribers_list.get_all() method

const data = supr_client.subscriber_lists.get_all(); // default limit 20

const data = supr_client.subscriber_lists.get_all({limit:20, offset:0}); //  max limit 1000

{
  "meta": {
    "count": 14,
    "limit": 20,
    "offset": 0
  },
  "results": [
    {
      "list_id": "newsletter_subscribers",
      "list_name": "Newsletter Subscribers",
      "list_description": "all users who opted in to receive product updates",
      "list_type": "static_list",
      "subscribers_count": 0,
      "source": "None",
      "is_readonly": false,
      "status": "active",
      "track_user_entry": false,
      "track_user_exit": false,
      "requested_for_delete": false,
      "created_at": "2025-01-14T13:42:45.641000Z",
      "updated_at": "2025-01-14T13:42:45.641000Z",
      "drafts": "None"
    },
    {
      "list_id": "abandoned_application",
      "list_name": "Signups abandoned application",
      "list_description": "Users who didn’t finish application",
      "list_type": "static_list",
      "subscribers_count": 0,
      "source": "None",
      "is_readonly": false,
      "status": "active",
      "track_user_entry": true,
      "track_user_exit": true,
      "requested_for_delete": false,
      "created_at": "2025-02-14T13:42:45.641000Z",
      "updated_at": "2025-02-14T13:42:45.641000Z",
      "drafts": "None"
    }
	...
  ]
}

Add subscribers to list

Use supr_client.subscribers_list.add() to add list subscribers. There is no limit to the number of subscribers that you can add to a list.

const list_id = "_list_id_";
const subscribers = ["_distinct_id1_","_distinct_id2_", ..... ];

const data = supr_client.subscriber_lists.add(list_id, subscribers);

{
   "success":true
}

Remove subscribers from list

You can remove subscribers from the list using supr_client.subscribers_list.remove()

const list_id = "_list_id_";
const subscribers = ["_distinct_id1_","_distinct_id2_", ..... ];

const data = supr_client.subscriber_lists.remove(list_id, subscribers);

{
   "success":true
}

Delete list

const data = supr_client.subscriber_lists.delete("_list_id_");

Replace users in the list

In case you want to refresh list with a new set of users completely, you can replace users by creating a draft version of the list and updating users in it.

Start Sync to create draft version of the list

This method will create a draft version of the list where you can add the new set of users to replace users.

const data = supr_client.subscriber_lists.start_sync("_list_id_");

Add Subscribers to draft list

You can use this method to add subscribers to List draft version created in the Step-1. You’ll get version_id in start sync response.

const data = supr_client.subscriber_lists.add_to_version("_list_id_", "01HHCTXXXXXXXXXXX", ["_user_id_1","user_id_2"])

Remove Subscribers from draft list

You can use this method to remove subscribers from List draft version created in Step-1. You’ll get version_id in start sync response.

const data = supr_client.subscriber_lists.remove_from_version("_list_id_", "01HHCTXXXXXXXXXXX", ["_user_id_1","_user_id_2"])

Finish Sync to make the draft version live

Once your subscribers are updated in the list, use this method to finish sync and make the draft version updated in above steps live.

const data = supr_client.subscriber_lists.finish_sync("_list_id_", "01HHCTXXXXXXXXXXX")

Delete draft list

You can also delete draft list if it’s created by mistake.

const data = supr_client.subscriber_lists.delete_version("_list_id_", "01HHCTXXXXXXXXXXX");

Developer Resources

Updates and Versioning

Authentication

Security

SDKs and APIs

Features

Testing

Monitoring and Logging

Create / Update List

Get list data

Get list of lists

Add subscribers to list

Remove subscribers from list

Delete list

Replace users in the list

Delete draft list

​Create / Update List

​Get list data

​Get list of lists

​Add subscribers to list

​Remove subscribers from list

​Delete list

​Replace users in the list

​Delete draft list

Create / Update List

Get list data

Get list of lists

Add subscribers to list

Remove subscribers from list

Delete list

Replace users in the list

Delete draft list