> ## 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 Go SDK to create or update lists, add and remove users, and power bulk notifications and broadcast campaigns.
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
```go Request theme={"system"}
package main
import (
"context"
"log"
suprsend "github.com/suprsend/suprsend-go"
)
func main() {
// Initialize SDK
opts := []suprsend.ClientOption{
// suprsend.WithDebug(true),
}
suprClient, err := suprsend.NewClient("__api_key__", "__api_secret__", opts...)
if err != nil {
log.Println(err)
}
ctx := context.Background()
// ================= Create subscriber list
subscriberListCreated, err := suprClient.SubscriberLists.Create(ctx, &suprsend.SubscriberListCreateInput{
ListId: "prepaid-users", // max length 64 characters
ListName: "Users With Prepaid Vouchers",
ListDescription: "Users With Prepaid Vouchers above $250",
})
if err != nil {
log.Fatalln(err)
}
log.Println(subscriberListCreated)
}
```
```go Response theme={"system"}
{
"list_id":"prepaid-users",
"list_name":"Users With Prepaid Vouchers",
"list_description":"Users With Prepaid Vouchers above $250",
"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"
}
```
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).
## Get list data
You can get the latest information of a list using `suprClient.SubscriberLists.Get` method.
```go Request theme={"system"}
subscriberListData, err := suprClient.SubscriberLists.Get(ctx, "_list_id_")
```
```go 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"
}
```
## Get all lists
To get the data of all the lists created in your workspace, use `suprClient.SubscriberLists.GetAll` method
```go Request theme={"system"}
allSubscriberList, err := suprClient.SubscriberLists.GetAll(ctx, &suprsend.SubscriberListAllOptions) // default limit 20
allSubscriberList, err := suprClient.SubscriberLists.GetAll(ctx, &suprsend.SubscriberListAllOptions{Limit: 10, Offset: 0}) // max limit 1000
```
```go 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"
}
...
]
}
```
## 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.
```go Request theme={"system"}
addDistinctIds := []string{"distinct_id_1", "distinct_id_2"}
addResponse, err := suprClient.SubscriberLists.Add(ctx, "users-with-prepaid-vouchers-1", addDistinctIds)
if err != nil {
log.Fatalln(err)
}
log.Println(addResponse)
```
```go Response theme={"system"}
{
"success":true
}
```
## Remove subscribers from the list
```go Request theme={"system"}
removeDistinctIds := []string{"distinct_id_1", "distinct_id_2"}
removeResponse, err := suprClient.SubscriberLists.Remove(ctx, "users-with-prepaid-vouchers-1", removeDistinctIds)
if err != nil {
log.Fatalln(err)
}
log.Println(removeResponse)
```
```go Response theme={"system"}
{
"success":true
}
```
## Delete list
```go Request theme={"system"}
deleteListResp, err := suprClient.SubscriberLists.Delete(ctx, "users-with-prepaid-vouchers-1")
if err != nil {
log.Fatalln(err)
}
log.Println("delete list resp: ", deleteListResp)
```
## Replace users from the list
In case you want to refresh 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.
This method will create a draft version of the list where you can add the new set of users to replace users.
```go Request theme={"system"}
// start sync
newVersion, err := suprClient.SubscriberLists.StartSync(ctx, "users-with-prepaid-vouchers-1")
if err != nil {
log.Fatalln(err)
}
log.Println("start sync resp: ", newVersion)
versionId := newVersion.VersionId
```
You can use this method to add subscribers to List draft version created in Step 1. You'll get `version_id` in start sync response.
```go Request theme={"system"}
// ================= Add users to a draft list (with versionId)
addDistinctIds := []string{"id-399999", "id-399998"}
addResponse, err := suprClient.SubscriberLists.AddToVersion(ctx, "users-with-prepaid-vouchers-1", versionId, addDistinctIds)
if err != nil {
log.Fatalln(err)
}
log.Println("add to version resp:", addResponse)
```
You can use this method to remove subscribers from List draft version created in Step 1. You'll get `version_id` in start sync response.
```go Request theme={"system"}
// ================= remove users from a list
removeDistinctIds := []string{"distinct_id_1", "distinct_id_2"}
removeResponse, err := suprClient.SubscriberLists.RemoveFromVersion(ctx, "users-with-prepaid-vouchers-1", versionId, removeDistinctIds)
if err != nil {
log.Fatalln(err)
}
log.Println("remove from version resp: ", removeResponse)
```
Once your subscribers are updated in the list, use this method to finish sync and make the draft version updated in above steps live.
```go Request theme={"system"}
// finish sync
finishSyncResp, err := suprClient.SubscriberLists.FinishSync(ctx, "users-with-prepaid-vouchers-1", versionId)
if err != nil {
log.Fatalln(err)
}
log.Println("finish sync resp: ", finishSyncResp)
```
### Delete Draft list
You can also delete draft list if it's created by mistake.
```go Request theme={"system"}
deleteVersionResp, err := suprClient.SubscriberLists.DeleteVersion(ctx, "users-with-prepaid-vouchers-1", tempListVersion.VersionId)
if err != nil {
log.Fatalln(err)
}
log.Println("delete version resp: ", deleteVersionResp)
```