Lists

The campaigns can be sent to a group of contacts which is called a list.

  • Every campaign is required to be sent to at least one list.
  • Contacts can be added to and removed from lists manually in the UI of the campaigns.
  • It returns a collection of subscriber's list which holds the subscriber's information such as Email address, Firstname, Lastname, etc.

Reading

In this section, we will explain the procedure of reading a list.

You can use the following Taximail API to make an API request to read list.

GET https://api.taximail.com/v2/list

The various parameters that are required for this request are:

Parameter Type Description Required
order_by enum {list_name, create_date} Specify the column used to sort the result-set.

Defaults to create_date.
order_type enum {asc, desc} To sort the records in a ascending or descending order.

Defaults to desc.
page integer Specify the page number for reading result.

Defaults to 1.
limit integer The number of items to return per page, up to a maximum of 100.

Defaults to 25.

Example Request

Following is an example request which can be made.

GET /v2/list?order_by=list_name&page=1 HTTP/1.1
Host: api.taximail.com
Authorization: "Bearer YOUR_SESSION_ID"

Example Result

You will receive either a success data or an error data which will be in JSON format.

{
  "status": "success",
  "code": 200,
  "data": {
            "list_count": 46,
            "lists": [
                  {
                      "list_id": 182,
                      "list_name": "List A",
                      "sync_status": "F",
                      "optin_content": "T",
                      "all_subscribers": 3,
                      "created_date": "2015-02-08 10:01:43"
                  },
                  {
                      "list_id": 174,
                      "list_name": "List B",
                      "sync_status": "F",
                      "optin_content": "T",
                      "all_subscribers": 2,
                      "created_date": "2015-04-28 12:13:54"
                  }
            ],
            "global_supp_list": {
                "list_id": "global",
                "list_name": "Global suppression",
                "list_type": "bounce",
                "subscribers": 22255
            },
            "max_page": 2,
       }
}

Fields

The various fields required for this requests are as follows :

Name Type Description
status enum {success, error} Returns the status of the result.
code integer Returns the response code of the result.
err_msg string When error occur, returns the error's detail of the result.
data.list_count integer Number of total list.
data.max_page integer Maximum number of result page.
data.lists array The array of list data.
data.global_supp_list object The information of global suppression list.

Response Code

The example below shows the response code’s which we can get while making this API request.

Code Result Description
200 success Response to a successful request.
400 error The request is malformed or missing some required parameters.
401 error Unauthorized or the session_id was expired.

Creating

  • This API endpoint allows you to create a new list.
  • You need to generate the list_id by POST to /list API.
  • After that, you need to update the list's name by PUT to /list/{list_id} API.

POST https://api.taximail.com/v2/list

Parameter Type Description Required
create_mode enum {active, draft} Select status of list.

Defaults to draft.

Example Request

POST /v2/list HTTP/1.1
Host: api.taximail.com
Authorization: "Bearer YOUR_SESSION_ID"

Example Result

{
   "status": "success",
   "code": 201,
   "data": {
              "list_id": 314
       }
}

Fields

Name Type Description
status enum {success, error} Returns the status of the result.
code integer Returns the response code of the result.
err_msg string When error occur, returns the error's detail of the result.
data.list_id integer The list_id of the new created list.

Response Code

Code Result Description
201 success The new resource was created successfully.
400 error The request is malformed or missing some required parameters.
401 error Unauthorized or the session_id was expired.
403 error Forbidden, you've reached the limit of list number.

Updating

  • This API endpoint allows you to update the name list.
  • You're required to put the parameters and authentication by Taximail.

PUT https://api.taximail.com/v2/list/{list_id}

Parameter Type Description Required
list_name string The name of the list you want to update. Yes

Example Request

PUT /v2/list/314 HTTP/1.1
Host: api.taximail.com
Authorization: "Bearer YOUR_SESSION_ID"

list_name=VIP+customer

Example Result

{
   "status": "success",
   "code": 200
}

Fields

Name Type Description
status enum {success, error} Returns the status of the result.
code integer Returns the response code of the result.
err_msg string When error occur, returns the error's detail of the result.

Response Code

Code Result Description
200 success Response to a successful request.
400 error The request is malformed or missing some required parameters.
401 error Unauthorized or the session_id was expired.
409 error Duplicated list's name.

Showing

  • This API endpoint display's the list's detail.
  • You need to send GET request and list_id to /list/{list_id} API.
  • If successful requests,Taximail API will return object data such as subscribers_count , all_domain , graph_stat and other.

GET https://api.taximail.com/v2/list/{list_id}

Example Request

GET /v2/list/314 HTTP/1.1
Host: api.taximail.com
Authorization: "Bearer YOUR_SESSION_ID"

Example Result

{
  "status": "success",
  "code": 200,
  "data": {
              "optin_pending_count": 0,
              "global_supp_count": 3,
              "spam_complaint_count": 0,
              "graph_stat": {
                     "subscriber": [
                          [
                              1448384400000,
                              10
                          ],
                          [
                              1448470800000,
                              20
                          ],
                          [
                              1448557200000,
                              3
                          ]
                     ],
                     "unsubscriber": [
                          [
                              1448384400000,
                              1
                          ],
                          [
                              1450890000000,
                              2
                          ]
                     ]
              },
              "subscribers_count": 33,
              "unsubscribers_count": 3,
              "email_service": [
                    {
                        "domain_name": "gmail.com",
                        "percent": 75
                    },
                    {
                        "domain_name": "hotmail.com",
                        "percent": 25
                    }
              ],
              "all_domain": [
                    "gmail.com",
                    "hotmail.com"
              ],
              "subscribers_ratios": {
                    "in_active": 50,
                    "active_opt_in": 0,
                    "active_non_opt_in": 50,
                    "opt_in_pending": 0
              },
              "open_stat": {
                    "percent": 56.67,
                    "average": 9.63,
                    "diff": 47.04
              },
              "click_stat": {
                    "percent": 30.75,
                    "average": 0.04,
                    "diff": 30.71
              }
      }
}

Fields

Name Type Description
status enum {success, error} Returns the status of the result.
code integer Returns the response code of the result.
err_msg string When error occur, returns the error's detail of the result.
data.optin_pending_count integer Returns summary sunscriber in optin pending.
data.global_supp_count integer Returns summary sunscriber in global suppression list.
data.spam_complaint_count integer Returns summary sunscriber in spam complaint.
data.graph_stat object Returns summary sunscriber graph statistics.
data.subscribers_count integer Returns summary sunscribers.
data.unsubscribers_count integer Returns summary unsubscriber.
data.email_service array Returns array of domain statistics.
data.all_domain array Returns array of all domain name each list.
data.subscribers_ratios object Returns object of sunscriber ratios.
data.open_stat object Returns object of sunscriber open email.
data.click_stat object Returns object of sunscriber click email.

Response Code

Code Result Description
200 success Response to a successful request.
400 error The request is malformed or missing some required parameters.
401 error Unauthorized or the session_id was expired.
404 error The list not found.

Deleting

  • This API endpoint allows you to delete a list
  • You can send a DELETE request to list/{list_id} API.

DELETE https://api.taximail.com/v2/list/{list_id}

Example Request

DELETE /v2/list/314 HTTP/1.1
Host: api.taximail.com
Authorization: "Bearer YOUR_SESSION_ID"

Example Result

{
  "session_id": "24bca90bac40b23e9fdcc8082299049d"
}

Fields

Name Type Description
status enum {success, error} Returns the status of the result.
code integer Returns the response code of the result.
err_msg string When error occur, returns the error's detail of the result.

Response Code

Code Result Description
200 success Response to a successful request.
400 error The request is malformed or missing some required parameters.
401 error Unauthorized or the session_id was expired.
404 error The list not found.
Title
Title SEO [Optional]
Description SEO [Optional]
Friendly URL [Optional]
IFRAME Content [Optional]
Priority
Markdown
We use cookies
This website uses cookies to enhance your browsing experience on our website, to show you personalized content and targeted ads, to analyze our website traffic, and to understand where our visitors are coming from. You can manage your preferences by clicking Change Preferences. Learn more about this on Cookie policy
Change Preferences
Accept All