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 segments, 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.

Manage Lists

The List endpoints allow you to create, delete, and get Lists on behalf of an authenticated user. For these endpoints, there are three methods available: POST, DELETE and GET. The POST method allows you to create a List, the DELETE method allows you to delete a List, and the GET method allows you to get information from a list.

Creating List

The first step is creating a new list by adding subscribers via JSON body or from a CSV file.

To set up a list, you need to define the columns and rows that the new list will contain. Once defined, the next step is to add one or more subscribers to the list.

Therefore, this endpoint allows you to create a new list and add subscribers to the list in the same request.

📘

NOTE

Type for list's columns will be inferred using the first value found for the column if using a CSV file.

HTTP Request : POST /lists

In the following request body example, we are going to create a list called "NewSusbcribers" that includes 2 columns defined as ("name" and "email") and 1 subscriber named (“Julian”).

📘

NOTE

When you create a new list, three columns will be added automatically : “id”, “email”, “mobile”, “devices”, “devices_type”.

When you create any of the automatically generated columns (“id”, “email”, “mobile”, “devices”, “devices_type”) with the same name, they will be replaced with the new column you create.

Let's create the request body example by creating the list and adding one subscriber in JSON format.

• JSON format

{
  "name": "NewSubscribers",
  "columns": [
    {
      "name": "name",
      "type": "STRING"
    },
    {
      "name": "email",
      "type": "STRING"
    }
  ],
  "rows": [
    {
      "Name": "Julian",
      "Email": "[email protected]"
    }
  ]
}

The parameters presented in the request body example when creating the List in JSON format are the following:

Now let's create the request body example by creating the list and adding one subscriber by importing a CSV file locally.

• CSV file

Example CSV File format:

📘

NOTE

The maximum size of the CSV file should be 200 MB as a limit. If the file exceeds, the response will fail.

curl -X POST "https://elastic.messangi.me/qarth/v3/lists?trackLastActivity=false&name=<LIST_NAME>&usesAut7Columns=true&caseSensitive=false&usesGeneratedData=true" -H "accept: application/json" -H "Authorization: Bearer <API_KEY>" -H "Content-Type: multipart/form-data" -F "csvFile=@<CSV_FILE_NAME>.csv;type=text/csv"

The parameters presented in the request body example when creating the List by importing a CSV file are the following:

When you created the list in JSON format or imported a CSV file, the response body contains the following data:

{
  "meta": {
    "timestamp": 1689704359002,
    "transactionId": "2bab46a1-c3ee-45e4-b396-c846"
  },
  "data": {
    "id": 95343,
    "columns": [
      {
        "name": "name",
        "type": "STRING",
        "defaultValue": null,
        "indexed": false,
        "required": false,
        "unique": false,
        "customConfiguration": null
      },
      {
        "name": "email",
        "type": "STRING",
        "defaultValue": null,
        "indexed": true,
        "required": false,
        "unique": true,
        "customConfiguration": null
      },
      {
        "name": "id",
        "type": "STRING",
        "defaultValue": null,
        "indexed": true,
        "required": true,
        "unique": true,
        "customConfiguration": null
      },
      {
        "name": "mobile",
        "type": "STRING",
        "defaultValue": null,
        "indexed": true,
        "required": false,
        "unique": true,
        "customConfiguration": null
      },
      {
        "name": "devices",
        "type": "STRING",
        "defaultValue": null,
        "indexed": true,
        "required": false,
        "unique": false,
        "customConfiguration": null
      },
      {
        "name": "devices_type",
        "type": "STRING",
        "defaultValue": null,
        "indexed": true,
        "required": false,
        "unique": false,
        "customConfiguration": null
      }
    ],
    "name": "NewSubscribers",
    "userName": "[email protected]",
    "size": 1,
    "key": "id",
    "autoId": true,
    "usesAutoColumns": true,
    "caseSensitive": false,
    "usesGeneratedData": true,
    "lastUpdated": "2023-07-18T18:19:18.977256025",
    "createdAt": "2023-07-18T18:19:18.825373698",
    "status": "OK",
    "totalLines": 1,
    "percentProcessed": 100
  }
}

Parameters presented in the response body example when creating the list are the following:

📘

NOTE

Copy the parameter data.id ("listId") located in the response body for future requests.

Getting List

When a List is previously created, we proceed to get the information from a single list.

HTTP Request : GET /lists/{listId}

To get a list information, you need to provide the unique identifier of the list you want to retrieve the information.

Deleting List

When a List is previously created, we can delete a single list.

HTTP Request : DELETE /lists/{listId}

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

Manage Subscribers

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

The second step is adding new subscribers to the list created via JSON body or importing a CSV file.

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

In the following example, we are going to add 3 new subscribers to the “New Subscribers” list created previously.

To add subscribers to a specific list, you need to provide the unique identifier of the list you want to add the new subscribers to.

Let's create the request body example by creating the list and adding the three subscribers in JSON format.**

• JSON format

[
  {
    "name": "Albert",
    "email": "[email protected]"
  },
  {
    "name": "Elizabeth",
    "email": "[email protected]"
  },
  {
    "name": "Amanda",
    "email": "[email protected]"
  }
]

The parameters presented in the request body example when creating the List in JSON format are the 2 columns that were defined when the list was created: "name" and "email". And the values that correspond to the previously mentioned columns.

Now let's create the request body example by creating the list and adding the three subscribers by importing a CSV file locally.

• CSV file

Example CSV File format:

📘

NOTE

The maximum size of the CSV file should be 200 MB as a limit. If the file exceeds, the response will fail.

curl -X POST "https://elastic.messangi.me/qarth/v3/lists/<LIST_ID>/subscribers/bulk" -H "accept: application/json" -H "Authorization: Bearer <API_KEY>" -H "Content-Type: multipart/form-data" -F "csvFile=@<CSV_FILE_NAME>.csv;type=text/csv"

When you added the subscribers to the list in JSON format or imported a CSV file, the response body contains the following data:

{
  "meta": {
    "timestamp": 1689736657744,
    "transactionId": "8e8ac3e5-8394-4342-9aa8"
  },
  "data": {
    "subscriberUpdated": 0,
    "subscriberAdded": 3,
    "subscribersError": []
  }
}

Parameters presented in the response body example when creating the list are the following:

Getting Subscribers

When the subscribers have been added to a specific list, we proceed to get the information of all the subscribers that the list contains.

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

To get subscribers information, you need to provide the unique identifier of the list you want to retrieve the subscribers information.

Once executed the API call, from the response body you can get the unique identifier (“id”) of each subscriber the list contains.

Deleting Subscriber

When the subscribers have been added to a specific list, we can delete a single subscriber.

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

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