> ## 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 subscriber lists with Python SDK: create/update list, add/remove/replace users.

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>