Help Center    API  

Contacts

Contacts are the center of activity in Campaign. They represent the target people.

In this guide, you’ll learn how to use the contacts endpoint to create, update and delete contacts, manage contacts with the Taximail API.

•••

Importing

  • The Taximail API has mainly 2 modes to add contacts.
  • It will send POST request to list/{list_id}/subscribers/import API.
  • You also need to send object data for adding a contact in each list and mapping field data with custom fields.
  • The two modes are "copyandpaste" mode or upload CSV file by "fromfile" mode.
  • If the request is successful, Taximail API will return generated key_import and token. They will use for sending request into the results of imported contact (https://www.taximail.com/en/support/api/result-imported-subscriber).

This API endpoint allows you to Import a contact

POST https://api.taximail.com/v2/list/{list_id}/subscribers/import

The various parameters that are required for this request are:

Parameter Type Description Required
mode_import enum {copyandpaste, fromfile} The mode to import contacts. Yes
subscribers_data string Contacts data to import.

It's option in copyandpaste mode.

When you want to import two or more contacts, you can use |:| to separate contact data.

Ex. "john@example.com,john doe|:|adam@example.com,adam doe|:|josafh@example.com,josafh brown"		 Yes
path_file string Path csv file to import contact. files size is no more than 50MB.

It's option in fromfile mode.		 Yes
matched_fields array Match field respectively using email, custom field ID or custom field key.

In case of non-unique list, you have to add matching id field.

If you want to ignore any field, set those fields value to 0.

For example, you just want to match your email and country.

Your subscribers_data is "john@example.com,john,thailand”.

Thus, matched_fields will be “email,0,5” while 5 is custom field ID of country.

Default to 0.		 Yes
field_terminator enum {comma, semicolon, tap} Select the symbol terminator to separate when import data.

Default to comma.
field_encloser enum {empty value, single quote, double quote} Select the symbol encloser to separate when import data.

Default to empty value.
update_duplicates boolean Update data for duplicate contact.

Defaults to true.
not_send_optin_email boolean Set status to send email opt-in.

Defaults to true.
add_to_suppression_list enum {global, none} When you want to add a contact to global suppresstion.

Defaults to none.

subscriber_data : When you want to import two or more contacts, you can use |:| to separate contact data. Ex. "john@example.com,john doe|:|adam@example.com,adam doe|:|josafh@example.com,josafh brown"

Example Request

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

mode_import=copyandpaste&subscribers_data=john%40example.com%2Cjohn+doe%7C%3A%7Cadam%40example.com%2Cadam+doe%7C%3A%7C&field_terminator=%2C&matched_fields%5B%5D=email&matched_fields%5B%5D=208&update_duplicates=true&not_send_optin_email=true&add_to_suppression_list=none

Example Result

{
  "status": "success",
  "code": 201,
  "data": {
              "token": "dbbdb6f03d5cb333fbc9f9d7a7f8a20a",
              "key_import": "8f7979162b735ac71565a950352e5e4c"
      }
}
•••

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.key_import string Returns generated import key.
data.token string Returns generated token.
•••

Response Code

Code Result Description
202 success Response to a request is accepted.
400 error The request is malformed or missing some required parameters.
Can't read file contact or no contact in file.
Invalid File.
Missing email field.
401 error Unauthorized or the session_id was expired.
404 error The list not found.
Missing contact file.
This key has been used or invalid.
409 error Duplicate custom field key in list.
503 error Field duplicate.
•••

Results for imported contact

  • Here, the process has finished importing the contact.
  • You can send GET request to list/{list_id}/subscribers/{key_import}/commit/{token} API.
  • Taximail API will return the result imported contact such as total subscribers_count , total import success , total import failed and duplicate contact in list.

Following are the API endpoint and required parameters.

GET https://api.taximail.com/v2/list/{list_id}/subscribers/{key_import}/commit/{token}

Example Request

GET v2/list/314/subscribers/8f7979162b735ac71565a950352e5e4c/Commit/dbbdb6f03d5cb333fbc9f9d7a7f8a20a HTTP/1.1
Host: api.taximail.com
Authorization: "Bearer YOUR_SESSION_ID"

Example Result

{
  "status": "success",
  "code": 200,
  "data": {
              "subscribers_count": 2,
              "success": 2,
              "duplicate": 0,
              "failed": 0
      }
}
•••

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.subscribers_count integer The summary import contacts.
data.success integer Returns summary for import successful.
data.duplicate integer Returns summary for duplicate contact.
data.failed integer Returns summary for import failed.
•••

Response Code

Code Result Description
202 success Response to a request is accepted.
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.
This token has been used or invalid.
•••

Showing

  • This API endpoint would allow you to get all contacts in each list.
  • You need to send GET request to /list/{list_id}/subscribers API.

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

Parameter Type Description Required
display_mode enum {default, all} Specify display mode to get subscribers.

Default to all.		 Yes
browse enum {segment_id, all} Browse mode to specify segment id to search in segment rule.

Default to all.
order_by enum {email, date} Specify the column which is used to sort the result-set.
order_type enum {asc, desc} To sort the records in 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.
keyword_search string The keyword to search in contact list database. Leave empty to disable search.

Example Request

GET v2/list/314/subscribers?display_mode=all&order_by=email&order_type=desc&page=1&limit=3&keyword_search=example.com HTTP/1.1
Host: api.taximail.com
Authorization: "Bearer YOUR_SESSION_ID"

Example Result

{
  "status": "success",
  "code": 200,
  "data": {
              "list_subscriber": [
                    {
                          "subscriber_id": 2,
                          "firstname": "Adam",
                          "lastname": "Smith",
                          "email": "adam@example.com",
                          "subscription_status": "Subscribed",
                          "bounce_type": "Not Bounced",
                          "subscription_date": "2015-10-29 11:10:19",
                          "custom_field_208": "Mr. Adam Smith"
                    },
                    {
                          "subscriber_id": 3,
                          "firstname": "John",
                          "lastname": "Smith",
                          "email": "john@example.com",
                          "subscription_status": "Subscribed",
                          "bounce_type": "Not Bounced",
                          "subscription_date": "2015-10-29 11:10:19",
                          "custom_field_208": "Mr. John Smith"
                    }
              ],
              "field_subscriber": [
                    {
                          "field_name": "subscriber_id",
                          "field_key": "subscriber_id"
                    },
                    {
                          "field_name": "firstname",
                          "field_key": "firstname"
                    },
                    {
                          "field_name": "lastname",
                          "field_key": "lastname"
                    },
                    {
                          "field_name": "email",
                          "field_key": "email"
                    },
                    {
                          "field_name": "subscription_status",
                          "field_key": "subscription_status"
                    },
                    {
                          "field_name": "bounce_type",
                          "field_key": "bounce_type"
                    },
                    {
                          "field_name": "subscription_date",
                          "field_key": "subscription_date"
                    },
                    {
                          "field_name": "Customer Fullname",
                          "field_key": "custom_field_208"
                    }
              ],
              "subscriber_filter_count": 2,
              "subscriber_count": 5
       }
}
•••

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_subscriber array Returns array of contact object.
data.field_subscriber array Returns all input field object in list.
data.subscriber_filter_count integer Returns summary contact in list with filter search.
data.subscriber_count integer Returns summary contact in list.
•••

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.
•••

Contact‘s detail

  • This API endpoint allows you to get the contact detail.
  • You should send GET request and subscriber_id to list/{list_id}/subscribers/{subscriber_id} API.
  • On a successful request, Taximail API will return object of contact's detail such as email , array of custom_field , subscription_status etc.

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

Example Request

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

Example Result

{
  "status": "success",
  "code": 200,
  "data": {
              "email": "john@example.com",
              "custom_field": [
                    {
                          "custom_field_id": "firstname",
                          "custom_field_name": "Firstname",
                          "custom_field_value": "",
                          "type": "text",
                          "data": "John"
                    },
                    {
                          "custom_field_id": "lastname",
                          "custom_field_name": "Lastname",
                          "custom_field_value": "",
                          "type": "text",
                          "data": "Smith"
                    },
                    {
                          "custom_field_id": 208,
                          "custom_field_name": "This is fullname",
                          "custom_field_value": "",
                          "type": "text",
                          "data": "Mr. John Smith"
                    }
              ],
              "subscription_status": "Subscribed",
              "bounce_type": "Not Bounced",
              "subscription_date": "2015-10-29 11:10:19"
    }
}
•••

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.email string Returns contact's email.
data.custom_field array Returns array of custom field data.
data.subscription_status string Returns status subscribed.
data.bounce_type string Returns bounce type of contacts.
data.subscription_date string Returns date time to subscribed.
•••

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.
The contact not found.
•••

Updating

  • This API Endpoint allows to update or edit contacts information.
  • You need to PUT the object information to list/{list_id}/subscribers/{subscriber_id} API.

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

Parameter Type Description Required
custom_field object Custom field value need update, object key is prefix CustomField and followed by custom_field_id.

You should submit your information matching with pattern below.

Ex. {"CustomField208":"Adam doe","CustomField210":"089-1234567"}		 Yes
•••

Example Request

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

custom_field%5BCustomField208%5D=Adam+doe&custom_field%5BCustomField210%5D=089-1234567

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 expired.
404 error The list not found.
The contact not found.
•••

Selecting

  • The Taximail API supports a selection of multiple contacts.
  • You can send POST request and array of subscriber_id to list/{list_id}/subscribers/selection API.
  • Taximail API will return token of array subscribers to use in delete subscriber.

POST https://api.taximail.com/v2/list/{list_id}/subscribers/selection

Parameter Type Description Required
subscribers_id string The string of subscriber_id separated by comma.

Ex. "2,3"		 Yes

Example Request

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

subscribers_id=2%2C3

Example Result

{
  "status": "success",
  "code": 202,
  "data": {
                "token": "c2a1cee399efe568383c71ff2ce7cdf1"
         }
}
•••

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.token string Returns generated token of the delete select contact.
•••

Response Code

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

Deleting

  • This API Endpoint allows you to delete a contact.
  • In the first step, you will receive a token from selection.
  • After that, you can send DELETE request to list/{list_id}/subscribers/selection/{token} API.

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

Example Request

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

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 expired.
404 error The list not found.
This token has been used or invalid.
•••

Unsubscribing

  • This API Endpoint allows you to unsubscribe each contact.
  • You need to send POST request and email of the contact to list/{list_id}/subscribers/unsubscribe API.
  • The contact is no longer subscribed to the list.

POST https://api.taximail.com/v2/list/{list_id}/subscribers/unsubscribe

Parameter Type Description Required
email string The contact's email address must be unsubscribed. Yes

Example Request

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

email=john%40example.com

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 expired.
404 error The list not found.
The contact not found.
Title
Title SEO [Optional]
Description SEO [Optional]
Friendly URL [Optional]
IFRAME Content [Optional]
Priority
Markdown

Choose language

ภาษาไทย
English
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