> ## 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 Go SDK: create or update lists, and modify users in the list.
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)
```