Lists

The Lists SDK methods lets you create / manage list of subscribers. You can then send bulk messages to all the subscribers in the list with a single API call.

Data structure of List:

These are all the possible configurations of a list

{
	"list_id": "_list_id_",
	"list_name": "_list_name",
	"list_description: "_some sample description_"
}

Field Description:

Field	Descriptiom	Obligation
list_id	Unique identifier for the list. Follow these guidelines for naming the list: - list_id can be of max 64 characters. - It can contain characters [a-z0-9_-] i.e. alphanumeric characters, _(underscore) and -(hyphen). - list_id is case-insensitive. Suprsend first converts list_id to lowercase before storing it or doing any sort of comparison on it.	mandatory
list_name	Name of the list. This is for your reference and can be referred to understand what this list is for.	optional
description	Description of the list to identify what type of users belong to this list.	optional

Sample list body

{
	"list_id": "list_1",
	"list_name": "city_san_francisco",
	"list_description: "All Users whose last updated city is San Francisco"
}

List Methods

Below are some methods that you can use to create and update list

1. Create a 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);
        }
	}

Response

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

2. Get list data

You can get the latest information of a list using suprClient.subscriberLists.get 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 {
    getList();
  }
  
  private static Subscriber getList() throws SuprsendException {
		Suprsend suprsendClient = new Suprsend("_workspace_key_", "_workspace_secret_");
	
    try {
            String listId = "_list_id_";
            JSONObject res = suprClient.subscriberLists.get(listId);
            System.out.println(res);
        } catch (SuprsendException e) {
            System.out.println(e);
        }
	}

Response

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

3. Get all lists

To get the data of all the lists created in your workspace, use suprClient.subscriberLists.getAll() 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 {
    getList();
  }
  
  private static Subscriber getList() throws SuprsendException {
		Suprsend suprsendClient = new Suprsend("_workspace_key_", "_workspace_secret_");
		
    try {
             // 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);
        } catch (SuprsendException e) {
            System.out.println(e);
        }
	}

Response

{
  "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"
    }
  ]
}

4. Add Subscribers to the list

You can add subscribers to the list using suprClient.subscriberLists.add(). There is no limit to the number of subscribers that you can add to a 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 {
    subscriberAdd();
  }
  
  private static Subscriber subscriberAdd() throws SuprsendException {
		Suprsend suprsendClient = new Suprsend("_workspace_key_", "_workspace_secret_");
		
    //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);
    } catch (SuprsendException e) {
      System.out.println(e);
    }
	}

Response

{ success: true }

5. Remove Subscribers from the list

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

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 {
    subscriberRemove();
  }
  
  private static Subscriber subscriberAdd() throws SuprsendException {
		Suprsend suprsendClient = new Suprsend("_workspace_key_", "_workspace_secret_");
		
    //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);
    } catch (SuprsendException e) {
      System.out.println(e);
    }
	}

Response

{ success: true }