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);
        }
	}

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_-] i.e. 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);

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);

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);
  }

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);
  }

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);
    }
  }
}

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.

1

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_");
2

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"));
3

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"));
4

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");