Using the Taximail API

Base URL

All the Taximail API's are accessed through a base URL which is - api.taximail.com. All API calls should be made over HTTPS. It works with any language that has an HTTP library, such as cURL, urllib.

For using the Taximail API directly in your browser, you can make an API request like follows:

GET /v2/status?pretty=true HTTP/1.1
Host: api.taximail.com

You can try using the above API by clicking this this link from your web browser.

Normally, You will get the response as below:

{
  "status": "success",
  "code": "200",
  "desc": "Service is operating normally"
}

HTTP Methods

The latest version of Taximail API uses the standard HTTP methods to perform various actions on a resource. HTTP defines a set of request methods to indicate the desired action to be performed for a given resource.

Generate a session_id from Authentication API

• A session_id will be required, whenever you build and use your own app.
• It will be returned from /user/login API.
• After successful authentication, your app will be able to obtain a session_id.
• A session_id provides temporary, secure access to other Taximail APIs.

Most of the Taximail API requests require the use of session_id which your app can generate by two ways:

1. Using the API Key and Secret Key.

This section will cover how to generate a session_id from Authentication API using the API Key and Secret Key.

Firstly, you need to generate API Key and Secret Key from the Integration module API Key

After successful Integration, your app will be able to obtain an API Key and Secret Key.

The request parameters that are required for /user/login API and resource URL are:

POSThttps://api.taximail.com/v2/user/login

Example Request

Following is an example request which can be made.

POST /v2/user/login HTTP/1.1
Host: api.taximail.com

api_key= eeaefbf86d290564d054b48XXXXXXXXXXXX&secret_key=0dd5ddb05726caed0bfe231XXXXXXXXXXXX

Example Result

Once you execute the above API call, you will receive either a success data or error data in JSON format

{
    "status": "success",
    "code": "201",
    "data": {
              "expire": 1450950774,
              "user_type": "user",
              "session_id": "24bca90bac40b23e9fdcc8082299049d"
       }
}

You should use API Key and Secret Key for getting session_id when your Maximum Password Age under Password Policy has a value other than 'Never Expires'.

2. Authentication using Basic Auth.

You can authenticate by selecting Basic Auth and specifying the username and password parameters in the Authentication API and then specify the description as the API key and Secret key:

This method by Authentication using Basic Auth can be used with all APIs.
This information is an example to call transactional API.

POSThttps://api.taximail.com/v2/transactional

Example from the Authentication in Postman application.

Example Result

Once you execute the above API call, you will receive either a success data or error data in JSON format

{
    "status": "success",
    "code": "202",
    "data": {
              "message_id": "66cc0f81839f2b3e6e780aba",
              "claimed": 1
       }
}

Response Code

The session_id has a lifetime of 15 minutes. Therefore, for performance reasons, it is highly recommended to reuse the session_id until it is expired. If the Unauthorized (401) error occurs, you should make a request for another session_id.

Authentication is required for all endpoints in the Taximail public API. The API accepts HTTP Bearer authentication for all endpoints.

API versions

The Taximail API has multiple versions available to access at any one time. Each version contains a set of core fields and edge operations. We guarantee that those core APIs will be available and un-modified in that version for at least 2 years from release. The platform changelog can tell you which versions are currently available. Everything outside of these core APIs is called extended APIs. These APIs are still accessed through versioned paths. They can also be potentially modified or removed at any time, subject to 120-day migrations that would be announced on our platform roadmap. Alternatively, they may simply be included in the next available API version.

Next Steps

• Since you've covered the basics till here, it is highly recommended you should keep learning about the Taximail API.
• You can explore through the next section Reference. It will help you to find what you're looking for.
• It will be interesting to read about /list API.
• It will be worthwhile reading about the creation of a new list which will be required to use to use in /campaigns API API requests.