Lists
The List Resource allows you interact with your user lists on Engage. You can learn more about lists here.
- The List Object
- Create a List
- Get All Lists
- Update a List
- Archive a List
- Subscribe to a List
- Update subscriber status
- Remove subscriber from List
The List object
{
"id": "5fc6477241fcec31a9548e98",
"title": "Waitlist",
"description": "Awesome product waiting list",
"subscriber_count": 0,
"broadcast_count": 0,
"double_optin": true,
"redirect_url": "http://www.shorturl.com/home",
"created_at": "2011-10-05T14:48:00.000Z"
}
id
- A unique internal identifier for the List object.title
- List title. 64 characters max.description
- The List description. Subscribers will see this. Maximum of 255 characters.subscriber_count
- Number of subscribers in this List. Includes pending confirmations.broadcast_count
- Number of broadcasts that has been sent to this List.double_optin
- If to send a confirmation mail to subscribers for approval/permission.redirect_url
- URL to redirect users to after subscription. Does not apply to subscription via the API.created_at
- List creation date if exists.
Create a List
Adds a new List to your Engage account.
Works with username & password authentication.
POST /lists
Parameters:
title
- Required. List title.description
- Optional. String attached to the object.redirect_url
- Optional. URL to redirect users to after subscription.double_optin
- Optional. Set totrue
if you want subscribers to receive confirmation mail.
Example response payload:
{
"id": "60036440419768607192801b",
"title": "Monthly subscription",
"description": "Awesome product waiting list",
"subscriber_count": 0,
"broadcast_count": 0,
"double_optin": false,
"redirect_url": null,
"created_at": "2011-10-05T14:48:00.000Z"
}
Get all List
Get all List objects.
Works with username authentication.
GET /lists
Parameters:
limit
- Optional. Number of Lists to return. Defaults to 10. Maximum of 30.next_cursor
- Optional. Pagination cursor for next dataset page.previous_cursor
- Optional. Pagination cursor for previous dataset page.
NB: See pagination for more.
Example response payload:
{
"data": [
{
"id": "5fc6477241fcec31a9548e98",
"title": "Waitlist",
"description": null,
"subscriber_count": 12,
"broadcast_count": 0,
"double_optin": true,
"redirect_url": null,
"created_at": "2011-10-05T14:48:00.000Z"
},
{...},
{...}
],
"next_cursor": "5fc6477241fcec31a9548e98"
}
Get a List by id
Get the List object.
Works with username authentication.
GET /lists/{id}
Example response payload:
{
"id": "60036440419768607192801b",
"title": "Monthly subscription",
"description": "Awesome product waiting list",
"subscriber_count": 0,
"broadcast_count": 0,
"double_optin": false,
"redirect_url": null,
"created_at": "2011-10-05T14:48:00.000Z"
}
Update a List
Update List object.
Works with username authentication.
PUT /lists/{id}
Parameters can be any or more of the following:
title
- The List title.description
- The List description.redirect_url
- Valid URL to redirect users to after subscription.double_optin
- Set totrue
if you want subscribers to receive confirmation mail.
Example response payload (Returns updated List object):
{
"id": "60036440419768607192801b",
"title": "Monthly subscription",
"description": "Awesome product waiting list",
"subscriber_count": 0,
"broadcast_count": 0,
"double_optin": false,
"redirect_url": null,
"created_at": "2011-10-05T14:48:00.000Z"
}
Archive a List
Archive a List. This means new subscribers can’t be added. Existing subscribers will not be affected.
Works with username and password authentication.
DELETE /lists/{id}
Example response payload:
{ "status": "ok" }
Subscribe to a List
Creates a user and subscribes the user to a List. If user already exists (either by email or number), the user will be added to the List as well. If it is known that a user already exists and the user’s uid is known, the update subscriber status endpoint can be used instead.
POST /lists/{id}/subscribers
Parameters:
first_name
- Optional. The user’s first namelast_name
- Optional. The user’s last nameemail
- The user’s email. Requires both username and password authentication.number
- Optional. The user’s phone number in international format/created_at
- Optional. Creation date if exists.meta
- Optional. An object containing additional user attributes to add or update. Should be string, number or boolean.
Sample response payload:
{ "uid": "1456" }
Update subscriber status
Setting this to true
updates the subscriber’s subscription to true. false
unsubscribes the user from the List.
PUT /lists/{id}/subscribers/{uid}
Example response payload
{ "subscribed": false }
Remove subscriber from List
Remove subscriber from a List
DELETE /lists/:id/subscribers/{uid}
Example response payload:
{ "status": "ok" }