List.Subscribers
After List.Init, manage subscribers on that list — add, retrieve, unsubscribe, update, upsert, and optional tracking retrieval.
After List.Init, use list.Subscribers to work with subscribers on that publication list.
Requires Platform.Load("core", "1.1.5") before use.
Methods
| Method | Returns | Description |
|---|---|---|
<ListInstance>.Subscribers.Add(properties) |
string | Add a subscriber to the list |
<ListInstance>.Subscribers.Retrieve([filter]) |
object[] | Return subscribers (optional filter) |
<ListInstance>.Subscribers.Unsubscribe(emailAddress) |
string | Remove subscriber from this list |
<ListInstance>.Subscribers.Update(emailAddress, status) |
string | Change subscriber status on the list |
<ListInstance>.Subscribers.Upsert(emailAddress, attributes) |
string | Add or update subscriber attributes |
<ListInstance>.Subscribers.Tracking.Retrieve(filter) |
object[] | Tracking data for subscribers on the list |
<ListInstance>.Subscribers.Add
Adds a subscriber to the initialized list. Properties typically include EmailAddress and SubscriberKey, plus optional list-specific fields.
Syntax
<ListInstance>.Subscribers.Add(properties)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
properties |
object | Yes | Subscriber properties (EmailAddress, SubscriberKey, …) |
Return value
"OK" on success, or throws on failure.
Examples
Platform.Load("core", "1");
var list = List.Init("MY_LIST_KEY");
var result = list.Subscribers.Add({
EmailAddress: "test@example.com",
SubscriberKey: "test@example.com"
});
Write(Stringify(result));
<ListInstance>.Subscribers.Retrieve
Returns subscribers on the list. Omit filter to return all subscribers on the list; pass a WSProxy-style filter to narrow results.
Syntax
<ListInstance>.Subscribers.Retrieve([filter])
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
filter |
object | No | Optional filter object |
Return value
object[] — subscriber rows.
Examples
Platform.Load("core", "1");
var list = List.Init("MY_LIST_KEY");
var subscribers = list.Subscribers.Retrieve();
<ListInstance>.Subscribers.Unsubscribe
Removes the subscriber from this list. emailAddress may be a string or an object { EmailAddress, SubscriberKey } identifying the subscriber.
Syntax
<ListInstance>.Subscribers.Unsubscribe(emailAddress)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
emailAddress |
string | Yes | Email or identifying object |
Return value
"OK" on success, or throws on failure.
Examples
Platform.Load("core", "1.1.5");
var myList = List.Init("myList");
var status = myList.Subscribers.Unsubscribe("aruiz@example.com");
<ListInstance>.Subscribers.Update
Updates the subscriber’s status for this list.
Syntax
<ListInstance>.Subscribers.Update(emailAddress, status)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
emailAddress |
string | Yes | Email or { EmailAddress, SubscriberKey } |
status |
string | Yes | New status on the list (e.g. "Active") |
Return value
"OK" on success, or throws on failure.
Examples
Platform.Load("core", "1.1.5");
var myList = List.Init("myList");
var status = myList.Subscribers.Update("aruiz@example.com", "Active");
<ListInstance>.Subscribers.Upsert
Adds the subscriber if they are not on the list; otherwise updates the supplied attributes. If attributes.Status is set, the list status is updated accordingly.
Syntax
<ListInstance>.Subscribers.Upsert(emailAddress, attributes)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
emailAddress |
string | Yes | Email or { EmailAddress, SubscriberKey } |
attributes |
object | Yes | Attributes to set or merge |
Return value
"OK" on success, or throws on failure.
Examples
Platform.Load("core", "1.1.5");
var myList = List.Init("myList");
var status = myList.Subscribers.Upsert("aruiz@example.com", { ZipCode: "46202" });
<ListInstance>.Subscribers.Tracking.Retrieve
Returns tracking rows for subscribers on this list that match the filter.
Syntax
<ListInstance>.Subscribers.Tracking.Retrieve(filter)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
filter |
object | Yes | WSProxy-style filter (e.g. on SubscriberKey) |
Return value
object[] — tracking records.
Examples
Platform.Load("core", "1.1.5");
var myList = List.Init("MyList");
var results = myList.Subscribers.Tracking.Retrieve({
Property: "SubscriberKey",
SimpleOperator: "equals",
Value: "MyKey"
});