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 suprClient.subscriberLists.create method to create a new list

import org.json.JSONObject;

import suprsend.Suprsend;
import suprsend.SuprsendAPIException;
import suprsend.SubscriberListBroadcast;
import suprsend.SuprsendValidationError;

public class Lists {
  public static void main(String[] args) throws Exception {
    createList();
  }

  private static Subscriber createList() throws SuprsendException {
		Suprsend suprsendClient = new Suprsend("_workspace_key_", "_workspace_secret_");

    // Create List JSON payload
    JSONObject payload = new JSONObject().put("list_id", "_list_id_");
                                         .put("list_name", "_list_name_ ");
    		                            .put("list_description", "_some sample description for the list_");
        try {
            JSONObject res = suprClient.subscriberLists.create(payload);
            System.out.println(res);
        } catch (SuprsendException e) {
            System.out.println(e);
        }
	}

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

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 suprClient.subscriberLists.get method.

  ...
  String listId = "_list_id_";
  JSONObject res = suprClient.subscriberLists.get(listId);
  System.out.println(res);

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

Get all lists

To get the data of all the lists created in your workspace, use suprClient.subscriberLists.getAll() method

  ...
    // To get the list of 20 subscriber lists
  JSONObject res = suprClient.subscriberLists.getAll();

  // Get list with offset = 10 and limit = 20
  // JSONObject res = suprClient.subscriberLists.getAll(20,10);
  System.out.println(res);

{
  "meta": {
    "limit": 20,
    "offset": 0,
    "count": 1
  },
  "results": [
    {
      "list_id": "list-id1",
      "list_name": "List Name1",
      "updated_at": "2022-12-18T10:40:27.268417+00:00",
      "list_description": "List description1"
    },
    {
      "list_id": "list-id2",
      "list_name": "List Name2",
      "updated_at": "2022-12-19T10:40:27.268417+00:00",
      "list_description": "List description2"
    }
  ]
}

Add Subscribers to the list

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

  //Add one or more distinct ids in the list
  String distinctId1 = "id-1";
  String distinctId2 = "id-2";
  String distinctId3 = "id-3";
  ArrayList<String> distinctIds = new ArrayList<>(Arrays.asList(distinctId1,distinctId2,distinctId3));
  try {
    String listId = "l-001";
    JSONObject res = suprClient.subscriberLists.add(listId, distinctIds);
    System.out.println(res);
  }

{
   "success":true
}

Remove Subscribers from the list

You can remove subscribers from the list using suprClient.subscriberLists.remove()

  //Add one or more distinct ids in the list
  String distinctId1 = "id-1";
  String distinctId2 = "id-2";
  ArrayList<String> distinctIds = new ArrayList<>(Arrays.asList(distinctId1,distinctId2,distinctId3));
  try {
    String listId = "l-001";
    JSONObject res = suprClient.subscriberLists.remove(listId, distinctIds);
    System.out.println(res);
  }

{
   "success":true
}

Delete list

You can delete a subscriber list using the supr_client.subscriberLists.delete() method.

import org.json.JSONObject;

import suprsend.Suprsend;
import suprsend.SuprsendAPIException;
import suprsend.SubscriberListBroadcast;
import suprsend.SuprsendValidationError;

public class Lists {
  public static void main(String[] args) throws Exception {
    deleteList();
  }

  private static void deleteList() throws SuprsendException {
    Suprsend suprsendClient = new Suprsend("_workspace_key_", "_workspace_secret_");

    try {
      String listId = "_list_id_";
      JSONObject res = suprsendClient.subscriberLists.delete(listId);
      System.out.println(res);
    } catch (SuprsendException e) {
      System.out.println(e);
    }
  }
}

{
   "success": true
}

Replace users in the List

In case you want to refresh a 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.

JSONObject data = suprClient.subscriberLists.startSync("_list_id_");

Add Subscribers to draft list

Add subscribers to the draft version created in Step-1. You’ll get version_id in the Start Sync response.

JSONObject data = suprClient.subscriberLists.addToVersion("_list_id_", "01HHCTXXXXXXXXXXX", Arrays.asList("_user_id_1", "_user_id_2"));

Remove Subscribers from draft list

Remove subscribers from the draft version created in Step-1.

JSONObject data = suprClient.subscriberLists.removeFromVersion("_list_id_", "01HHCTXXXXXXXXXXX", Arrays.asList("_user_id_1", "_user_id_2"));

Finish Sync to make the draft version live

Finalize the sync and make the draft version live.

JSONObject data = suprClient.subscriberLists.finishSync("_list_id_", "01HHCTXXXXXXXXXXX");

Delete Draft list

You can also delete a draft list if it was created by mistake.

JSONObject data = suprClient.subscriberLists.deleteVersion("_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 all lists

Add Subscribers to the list

Remove Subscribers from the list

Delete list

Replace users in the List

Delete Draft list

​Create / Update List

​Get list data

​Get all lists

​Add Subscribers to the list

​Remove Subscribers from the list

​Delete list

​Replace users in the List

​Delete Draft list

Create / Update List

Get list data

Get all lists

Add Subscribers to the list

Remove Subscribers from the list

Delete list

Replace users in the List

Delete Draft list