> ## 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 from the Python SDK to create or update lists, add, remove, and replace users, and trigger broadcast notifications to segments.

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 `supr_client.subscribers_list.create` method to create a new list

<CodeGroup>
  ```python Request theme={"system"}
  from suprsend import SubscriberListBroadcast,SuprsendAPIException,SuprsendValidationError
  from suprsend import Suprsend
  # Initialize SDK
  supr_client = Suprsend("workspace_key", "workspace_secret")

  try:
      data = supr_client.subscriber_lists.create({
      "list_id": "_list_id_",   #Unique identifier for the list
      "list_name": "_list_name_", #readable name of the list (optional)
      "list_description": "_some sample description for the list_"
      })
      print(data)
  except (SuprsendAPIException,SuprsendValidationError) as ex:
      print(ex)
  ```

  ```python Response theme={"system"}
  {
     "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"
  }
  ```
</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 `supr_client.subscribers_list.get` method.

<CodeGroup>
  ```python Request theme={"system"}
  from suprsend import SubscriberListBroadcast, SuprsendAPIException, SuprsendValidationError
  from suprsend import Suprsend

  supr_client = Suprsend("workspace_key", "workspace_secret")

  try:
      data = supr_client.subscriber_lists.get("_list_id_")
      print(data)

  except (SuprsendAPIException, SuprsendValidationError) as ex:
      print(ex)
  ```

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

## Get all lists

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

<CodeGroup>
  ```python Request theme={"system"}
  from suprsend import SubscriberListBroadcast,SuprsendAPIException,SuprsendValidationError
  from suprsend import Suprsend
  # Initialize SDK
  supr_client = Suprsend("workspace_key", "workspace_secret")

  try:
  	const data = supr_client.subscribers_list.get_all();
      print(data)

  except (SuprsendAPIException,SuprsendValidationError) as ex:
      print(ex)
  ```

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

## Add Subscribers to the 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.

<CodeGroup>
  ```python Request theme={"system"}
  from suprsend import SubscriberListBroadcast, SuprsendAPIException, SuprsendValidationError
  from suprsend import Suprsend

  # Initialize SDK
  supr_client = Suprsend("workspace_key", "workspace_secret")

  try:
      data = supr_client.subscriber_lists.add("_list_id_", [
          "_distinct_id1_",
          "_distinct_id2_"
      ])
      print(data)

  except (SuprsendAPIException, SuprsendValidationError) as ex:
      print(ex)
  ```

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

## Remove Subscribers from the list

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

<CodeGroup>
  ```python Request theme={"system"}
  from suprsend import SubscriberListBroadcast, SuprsendAPIException, SuprsendValidationError
  from suprsend import Suprsend

  # Initialize SDK
  supr_client = Suprsend("workspace_key", "workspace_secret")

  try:
      data = supr_client.subscriber_lists.remove("_list_id_", [
          "_distinct_id1_",
          "_distinct_id2_"
      ])
      print(data)

  except (SuprsendAPIException, SuprsendValidationError) as ex:
      print(ex)
  ```

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

## Delete list

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

<CodeGroup>
  ```python Request theme={"system"}
  from suprsend import SubscriberListBroadcast, SuprsendAPIException, SuprsendValidationError
  from suprsend import Suprsend

  # Initialize SDK
  supr_client = Suprsend("workspace_key", "workspace_secret")

  try:
      data = supr_client.subscriber_lists.delete("_list_id_")
      print(data)

  except (SuprsendAPIException, SuprsendValidationError) as ex:
      print(ex)
  ```

  ```python Response theme={"system"}
  {
     "success": true,
     "message": "List deleted successfully"
  }
  ```
</CodeGroup>

Deleting a list is a permanent action and cannot be undone or restored.

## Replace users in list

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

<Warning>
  Use this method only if you want to completely overwrite the list members.
</Warning>

<Steps>
  <Step title="Start Sync to create a 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 existing users.

    <CodeGroup>
      ```python Request theme={"system"}
      data = supr_client.subscriber_lists.start_sync("_list_id_")
      ```
    </CodeGroup>
  </Step>

  <Step title="Add Subscribers to the draft list">
    You can use this method to add subscribers to the list's draft version created in Step-1. You'll get `version_id` in the start sync response.

    <CodeGroup>
      ```python Request theme={"system"}
      data = supr_client.subscriber_lists.add_to_version("_list_id_", "01HHCTXXXXXXXXXXX", ["_distinct_id1_", "_distinct_id2_"])
      ```
    </CodeGroup>
  </Step>

  <Step title="Remove Subscribers from the draft list">
    You can use this method to remove subscribers from the list's draft version created in Step-1. You'll get `version_id` in the start sync response.

    <CodeGroup>
      ```python Request theme={"system"}
      data = supr_client.subscriber_lists.remove_from_version("_list_id_", "01HHCTXXXXXXXXXXX", ["_distinct_id1_", "_distinct_id2_"])
      ```
    </CodeGroup>
  </Step>

  <Step title="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 the above steps live.

    <CodeGroup>
      ```python Request theme={"system"}
      data = supr_client.subscriber_lists.finish_sync("_list_id_", "01HHCTXXXXXXXXXXX")
      ```
    </CodeGroup>
  </Step>
</Steps>

### Delete Draft list

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

<CodeGroup>
  ```python Request theme={"system"}
  data = supr_client.subscriber_lists.delete_version("_list_id_", "01HHCTXXXXXXXXXXX")
  ```
</CodeGroup>