SMS Transactional

Taximail makes sending SMS easy. Using this API, you can send SMS messages with an option to generate a link and report webhook. On a successful request, it will return the remaining balance available for the user, the message price and the message count.

MSISDN means Mobile Station International Subscriber Directory Number and it's a number used to identify a phone number internationally. It is composed of the country code and the national destination's code. The MSISDN format will get rid of the + sign and of any 0 before the mobile number.

Sending

To send a new outgoing message to a number, you need to make an HTTP POST request to the following Taximail API.

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

The various parameters that are required for this request are:

Parameter Type Description Required
from string From specifies the sender name for your message. Yes
to integer This parameter determines the destination phone number for your SMS message. It is MSIDSN of the recipient that the message will be sent to. Format this number with a country code, e.g. 66175551212 (66 is TH code). Yes
text string The text parameter includes the full text of the message you want to send. It is the message content in which you can include any URL Yes
report_webhook boolean If this parameter is true, the sender can specify the Webhook settings for this API.

Defaults to false.
message_id string The message ID is a random identifier used for tracking statistics and should not be duplicated. It will be returned in the successful response.
transactional_group_name string Transactional's group name.

Defaults to Default group.
generate_link boolean If true, Taximail will generate hyperlink for all the URL in the message content.

Defaults to true.

Example Request

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

from=TXSMS&to=66992345856&text=HelloUser&report_webhook=true&message_id=A45734&transactional_group_name=newsms&generate_link=true

Example Result

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

{
    "status": "success",
    "code": 202,
    "data": {
        "message_id": "A45734",
        "remaining_balance": 129.94169,
        "message_price": 0.05831028006,
        "message_count": 1
    }
}

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.message_id integer Returns the message id provided in request call.
data.remaining_balance integer Returns the remaining balance which sender can use for sending SMS.
data.message_price array Returns the price of message. It depends on the length of message content.
data.message_count object Returns the no. of messages.

Response Code

Code Result Description
202 success Response to a successful request.
400 error The request is malformed or missing some required parameters.
Invalid MSISDN format.
This service is not available in your country.
The number of existed subscribers exceed your plan limit.
401 error Authentication failure or session expired.
409 error Duplicate message ID.
No more credit.
503 error Connection error, please try again later.

Message status

  • This Taximail API endpoint allows you to get the status of delivered transactional email to the recipient.
  • You are required to send GET request to transactional/{message_id} API.
  • Taximail API will return message status object such as email, ready time, sent time, open time and other.

GET https://api.taximail.com/v2/transactional/{message_id}

Example Request

GET v2/transactional/mid_0000001 HTTP/1.1
Host: api.taximail.com
Authorization: "Bearer YOUR_SESSION_ID"

Example Result

{
    "status": "success",
    "code": 200,
    "data": {
                "email": "john@example.com",
                "ready": "2016-01-07 10:13:15",
                "sent": "2016-01-07 10:13:19",
                "open": [
                      "2016-01-07 10:14:03"
                ],
                "open_count": 1,
                "click": [],
                "click_count": 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.email string Returns recipient's email.
data.ready string Returns datetime ready to send email.
data.send string Returns datetime to send email.
data.open string Returns datetime recipient open the email.
data.open_count string Returns summary open email count.
data.click string Returns datetime recipient click the email.
data.click_count string Returns summary click email count.

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 message id not found.

Sending OTP

To send a new outgoing OTP message to a number, you need to make an HTTP POST request to the following Taximail API.

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

The various parameters that are required for this request are:

Parameter Type Description Required
to integer This parameter determines the destination phone number for your SMS message. It is MSIDSN of the recipient that the message will be sent to. Format this number with a country code, e.g. 66175551212 (66 is TH code). Yes
sms_template_key string The sms otp template key need to use sms content. Yes
report_webhook boolean If this parameter is true, the sender can specify the Webhook settings for this API.

Defaults to false.
generate_link boolean If true, Taximail will generate hyperlink for all the URL in the message content.

Defaults to true.

Example Request

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

sms_template_key=54763bf8886e9b82&to=66992345856&report_webhook=true&generate_link=true

Example Result

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

{
    "status": "success",
    "code": 202,
    "data": {
        "message_id": "63bf89390fe2f00008a236c3",
        "remaining_balance": 25269.87,
        "message_price": 0.19,
        "message_count": 1,
        "otp_ref_no": "PD1HBC"
    }
}

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.message_id integer Returns the message id provided in request call.
data.remaining_balance integer Returns the remaining balance which sender can use for sending SMS.
data.message_price array Returns the price of message. It depends on the length of message content.
data.message_count object Returns the no. of messages.
data.otp_ref_no object Returns the ref no. of otp messages.

Response Code

Code Result Description
202 success Response to a successful request.
400 error The request is malformed or missing some required parameters.
Invalid MSISDN format.
This service is not available in your country.
The number of existed subscribers exceed your plan limit.
401 error Authentication failure or session expired.
404 error Not found template.
409 error No more credit.
503 error Connection error, please try again later.

Verify OTP

To verify OTP, you need to make an HTTP POST request to the following Taximail API.

GET https://api.taximail.com/v2/otp/verify/{message_id}

The various parameters that are required for this request are:

Parameter Type Description Required
otp_code string OTP to verify Yes

Example Request

GET v2/otp/verify HTTP/1.1
Host: api.taximail.com
Authorization: "Bearer YOUR_SESSION_ID"

message_id=54763bf8886e9b82&to=66992345856&otp_code=9999

Example Result

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

{
    "status": "success",
    "code": 202,
    "data": {}
}

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
202 success Response to a successful request.
400 error The request is missing some required parameters.
401 error Authentication failure or session expired.
404 error This message_id is expired or not exis.
503 error Connection error, please try again later.

Multipart SMS messages

If the message length sent through SMS API, exceeds the SMS character limit of 160 characters in the case of 7bit encoding (or 70 characters for UCS-2 encoding), the message will split to multiple separate SMS and sent to the sender separately.

For messages on the phone, a special header (UDH) is set for each message, it states the order and message each part belongs to. This special UDH shortens the length of each combined 7-bit message to 153 characters (67 characters for UCS-2).

GSM Encoding : The Latin-based languages such as Chinese, Spanish, and Greek use GSM character encoding. Each GSM character accounts for 7 bits, thus allowing a maximum of 160 characters per SMS. The Languages not based on Latin use a different encoding process called Unicode. It is commonly known as Unicode Transformation Format (UTF-16).

Unicode Encoding : Each UTF-16 character accounts for 16 bits per character, it allows a maximum of 70 characters per text. Depending on how many UTF-16 characters are used, this will make a small change on the final character count.

It's important to use this calculator and make sure that you don't exceed the limit and pay more than you planned.

Number of SMS GSM Characters Unicode Characters
1 160 70
2 306 (160 + 146), deducted 14 134 (70 + 64), deducted 6
3 459 (160 + 146 + 153), deducted 7 (one of the 2 messages) 201 (70 + 64 + 67), deducted 3 (half of text 2)
4 612 (160 + 146 + 153 + 153), deducted 7 (half of text 2) 268 (70 + 64 + 67 + 67), deducted 3 (half of text 2)
5 765 (160 + 146 + 153 + 153 + 153), deducted 7 (half of text 2) 335 (70 + 64 + 67 + 67 + 67), deducted 3 (half of text 2)
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