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

from suprsend import SubscriberListBroadcast,SuprsendAPIException,SuprsendValidationError
from suprsend import Suprsend
# Initialize SDK
supr_client = Suprsend("_api_key_", "_api_secret_")

try:
    data = supr_client.subscriber_lists.create({
    "list_id": "_list_id",
    "list_name": "_list_name",
    "list_description": "_some sample description for the list_",
    })
    print(data)
except (SuprsendAPIException,SuprsendValidationError) as ex:
    print(ex)

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 supr_client.subscribers_list.get method

from suprsend import SubscriberListBroadcast,SuprsendAPIException,SuprsendValidationError
from suprsend import Suprsend
# Initialize SDK
supr_client = Suprsend("_api_key_", "_api_secret_")

try:
    data = supr_client.subscribers_list.get("_list_id_");
    print(data)
    
except (SuprsendAPIException,SuprsendValidationError) as ex:
    print(ex)

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 supr_client.subscribers_list.get_all() method

from suprsend import SubscriberListBroadcast,SuprsendAPIException,SuprsendValidationError
from suprsend import Suprsend
# Initialize SDK
supr_client = Suprsend("_api_key_", "_api_secret_")

try:
	const data = supr_client.subscribers_list.get_all();
    print(data)
    
except (SuprsendAPIException,SuprsendValidationError) as ex:
    print(ex)

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 supr_client.subscribers_list.add(). There is no limit to the number of subscribers that you can add to a list.

from suprsend import SubscriberListBroadcast,SuprsendAPIException,SuprsendValidationError
from suprsend import Suprsend
# Initialize SDK
supr_client = Suprsend("_api_key_", "_api_secret_")

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

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

Response

{ success: true }

5. Remove Subscribers from the list

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

from suprsend import SubscriberListBroadcast,SuprsendAPIException,SuprsendValidationError
from suprsend import Suprsend
# Initialize SDK
supr_client = Suprsend("_api_key_", "_api_secret_")

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

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

Response

{ success: true }