List Management

Through the List Management API you can create new lists, subscribe new users to your existing lists, manage segments and create or delete custom columns.

The List Management API is used to create and manage lists (collections) and the content of each list (content of each collection). The content of each list corresponds to the subscribers.Therefore, this API not only allows you to manage lists, also allows you to edit, create, delete subscribers and columns, among other functions.

• Lists: Create a new list where subscribers can be added or imported via JSON or CSV file.

• Subscribers: You can add or remove subscribers one by one or multiple subscribers, fetch and update their information and batch import new subscribers.

• Segments: Create targeted sub-groups of subscribers based on conditions you set.

• Columns: Allows you to create and index columns to the desired list.

Updating Lists

Keeping your subscriptions lists up to date is essential to reaching the right audience. There are a combination of APIs that allow you to add, edit or delete subscribers. With these methods you can ensure that no one misses out on your campaigns.

Adding subscribers

Subscribers might be added one by one or in bulk by sending their basic information.

When you add or edit subscribers , the response body contains the data of the subscriber or subscribers created:

{
  "meta": {
    "timestamp": 1597166699457,
    "transactionId": "70169d77-c165-4795-9932-35b8a3af96fb",
    "explain": "a descriptive text"
  },
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "key": "12341236545, 507f1f77bcf86cd799439011, [email protected]",
    "data": {
      "id": "5f7b1af6535f6b5151040776",
      "key": "5f7b1af6535f6b5151040776",
      "data": {
        "address": "12345",
        "member since": "2020-10-05T13:09:10.233573Z",
        "last updated": "2020-10-05T13:09:10.233573Z",
        "mobile": "unknown.5f7b1af6535f6b5151040776",
        "id": "5f7b1af6535f6b5151040776",
        "email": "The Tester"
      }
    }
  }
}

The parameters presented in the response body example when creating the subscribers are the following:

Adding single subscribers

You have the option to add one by one subscriber to the list.

HTTP Request : POST /lists/{listId}/subscribers

{
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}

To add a single subscriber, you need to provide the unique identifier of the list you want to add the subscriber.

Adding multiple subscribers

There are two options to add multiple subscribers:

• Add bulk subscribers by JSON

• Add bulk subscribers by CSV

Adding multiple subscribers by JSON

You can add bulk subscribers in JSON format.

HTTP Request : POST /lists/{listId}/subscribers/bulk

[
  {
    "mobile": "+5841474662698",
    "email": "[email protected]",
    "first Name": "Homer"
  },
  {
    "mobile": "+123456",
    "email": "[email protected]",
    "first Name": "Lisa"
  }
]

To add multiple subscribers, you need to provide the unique identifier of the list you want to add the multiple subscribers.

Adding multiple subscribers by CSV file

You can add bulk subscribers by CSV file.

HTTP Request : POST /lists/{listId}/subscribers

To add subscribers, you need to provide the unique identifier of the list you want to add the subscribers by CSV file.

Updating subscribers

In order to update a subscriber PUT and PATCH method might be used. Note that PUT method is going to REPLACE the current data of the subscriber for the data sent in the request (meaning fields not sent are going to be erased from subscriber) while PATCH method ONLY edits the fields sent in the request.

Updates a subscriber with the state defined by the representation enclosed in the request:

HTTP Request : PUT /lists/{listId}/subscribers/{subscriberId}

Edits only the fields sent in the request for a subscriber, the others remain the same:

HTTP Request : PATCH /lists/{listId}/subscribers/{subscriberId}

In both cases, the following request body is presented, together with the required fields:

{
  "name": "Homer",
  "email": "[email protected]"
}

To update a subscriber, you need to provide the unique identifier of the list and subscriber id you want to update.

Deleting subscriber

You can delete a specific subscriber from the desired list.

HTTP Request : DELETE /lists/{listId}/subscribers/{subscriberId}

To delete a subscriber, you need to provide the unique identifier of the list and subscriber id you want to delete.

Managing Segments

A segment can be defined as a subset of the main list given some conditions and it can be created from a CSV file or from a json body in the request.

When you create or edit segments, the response body contains the basic data of the segment created:

{
  "meta": {
    "timestamp": 1597166699457,
    "transactionId": "70169d77-c165-4795-9932-35b8a3af96fb",
    "explain": "a descriptive text"
  },
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "people who likes movies",
    "userName": "homer",
    "listId": 203,
    "queryRule": "movies[eq]=horror&age[gt]=21",
    "total": 7
  }
}

The parameters presented in the response body example when creating the segment are the following:

Creating a segment from a CSV file

Creates a segment from the main list given a CSV file. Note that some fields are required such as the name of the segment, the source column (column to segment from file) and the target column (column to apply segment from main list).

HTTP Request : POST /lists/{listId}/segments

To create a segment, you need to provide the unique identifier of the list you want to create the segment by CSV file.

Creating a segment from a JSON body

Creates a segment from the information given in the body of the request:

HTTP Request : POST /lists/{listId}/segments

{
  "name": "females",
  "queryRule": "gender[eq]=f",
  "segmentType": "DYNAMIC"
}

To create a segment, you need to provide the unique identifier of the list you want to create the segment by JSON body.

Updating a segment

Updates a segment according to the data sent in the request:

HTTP Request : PATCH ​/lists​/{listId}​/segments​/{segmentId}

{
  "name": "females",
  "queryRule": "gender[eq]=f",
  "segmentType": "DYNAMIC"
}

To update a segment, you need to provide the unique identifier of the list and segment id you want to update.

Deleting a segment

Deletes a specific segment from a list.

HTTP Request : DELETE ​/lists​/{listId}​/segments​/{segmentId}

To delete a segment, you need to provide the unique identifier of the list and segment id you want to delete.