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 to true 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 to true 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 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 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" }