Lists

The List Resource allows you to interact with your user lists on Engage. You can learn more about Lists here.

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 have been sent to this List.

• double_optin - If set, send a confirmation mail to subscribers for approval/permission.

• redirect_url - URL to redirect users to after subscription. Does not apply to subscriptions via the API.

• created_at - List creation date if exists.

Create a List

Adds a new List to your Engage account.

Works with username and password authentication.

POST /v1/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 to true if you want subscribers to receive a 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 /v1/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 /v1/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 /v1/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 to true if you want subscribers to receive a 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 /v1/lists/{id}

Example response payload:

{ "status": "ok" }

Subscribe User to a List

Creates a user and subscribes the user to a List. This is the ideal endpoint to use if you have created a subscription form to add users to a List. If the user already exists (either by email or number), the user will be added to the List as well.

If opt-in confirmation email is enabled on the List, a confirmation email will be sent to the subscriber to confirm their subscription.

If the user already exists on Engage, the update subscriber status endpoint can be used instead.

POST /v1/lists/{id}/subscribers

Parameters:

• first_name - Optional. The user’s first name

• last_name - Optional. The user’s last name

• email - 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 a string, number, or boolean.

Sample response payload:

{ "uid": "1456" }

Update subscriber status

Update a user's subscription status of a List.

PUT /v1/lists/{id}/subscribers/{uid}

Parameters

• subscribed - Set to true to subscribe a user to a List or re-subscribe a user that has unsubscribed from a List. false unsubscribes the user from the List.

Unsubscribe from a List vs Delete/Remove from a List

When a user "unsubscribes" from a List, the user will still exist in the List but will not receive engagements sent to that List. When a user is "removed" from a List, they are completely deleted from the List.

Example response payload

{ "subscribed": false }

To add or remove a user to/from multiple Lists at once, see Add Users to Lists and Remove Users from Lists on the User API.

Remove a subscriber from a List

Remove a user from a List

DELETE /v1/lists/:id/subscribers/{uid}

Example response payload:

{ "status": "ok" }