> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lists

> Manage SuprSend subscriber lists with the Java SDK to create or update lists, add and remove users, and trigger bulk notifications and broadcast sends.

The Lists SDK methods lets you create / manage list of subscribers. You can then send [broadcast](/docs/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

<CodeGroup>
  ```java Request theme={"system"}
  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);
          }
  	}
  ```

  ```java Response theme={"system"}
  {
    "list_id": "list-id",
    "list_name": "List Name",
    "updated_at": "2022-12-18T10:40:27.268417+00:00",
    "list_description": "List description"
  }
  ```
</CodeGroup>

<Note>
  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).
</Note>

## Get list data

You can get the latest information of a list using  `suprClient.subscriberLists.get`  method.

<CodeGroup>
  ```java Request theme={"system"}
    ...
    String listId = "_list_id_";
    JSONObject res = suprClient.subscriberLists.get(listId);
    System.out.println(res);
  ```

  ```java Response theme={"system"}
  {
    "list_id": "list-id",
    "list_name": "List Name",
    "updated_at": "2022-12-18T10:40:27.268417+00:00",
    "list_description": "List description"
  }
  ```
</CodeGroup>

## Get all lists

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

<CodeGroup>
  ```java Request theme={"system"}
    ...
      // 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);
  ```

  ```java Response theme={"system"}
  {
    "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"
      }
    ]
  }
  ```
</CodeGroup>

## 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.

<CodeGroup>
  ```java Request theme={"system"}

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

  ```java Response theme={"system"}
  {
     "success":true
  }
  ```
</CodeGroup>

## Remove Subscribers from the list

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

<CodeGroup>
  ```java Request theme={"system"}

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

  ```java Response theme={"system"}
  {
     "success":true
  }
  ```
</CodeGroup>

## Delete list

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

<CodeGroup>
  ```java Request theme={"system"}
  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);
      }
    }
  }
  ```

  ```java Response theme={"system"}
  {
     "success": true
  }
  ```
</CodeGroup>

## 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.

<Steps>
  <Step title="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.

    <CodeGroup>
      ```java Request theme={"system"}
      JSONObject data = suprClient.subscriberLists.startSync("_list_id_");
      ```
    </CodeGroup>
  </Step>

  <Step title="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.

    <CodeGroup>
      ```java Request theme={"system"}
      JSONObject data = suprClient.subscriberLists.addToVersion("_list_id_", "01HHCTXXXXXXXXXXX", Arrays.asList("_user_id_1", "_user_id_2"));
      ```
    </CodeGroup>
  </Step>

  <Step title="Remove Subscribers from draft list">
    Remove subscribers from the draft version created in Step-1.

    <CodeGroup>
      ```java Request theme={"system"}
      JSONObject data = suprClient.subscriberLists.removeFromVersion("_list_id_", "01HHCTXXXXXXXXXXX", Arrays.asList("_user_id_1", "_user_id_2"));
      ```
    </CodeGroup>
  </Step>

  <Step title="Finish Sync to make the draft version live">
    Finalize the sync and make the draft version live.

    <CodeGroup>
      ```java Request theme={"system"}
      JSONObject data = suprClient.subscriberLists.finishSync("_list_id_", "01HHCTXXXXXXXXXXX");
      ```
    </CodeGroup>
  </Step>
</Steps>

### Delete Draft list

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

<CodeGroup>
  ```java Request theme={"system"}
  JSONObject data = suprClient.subscriberLists.deleteVersion("_list_id_", "01HHCTXXXXXXXXXXX");
  ```
</CodeGroup>