Documentation

For developers who are looking to integrate SMSTech with an existing system, our comprehensive documentation provides all the information required to get you up and running.

Overview

SMS API Fundamentals

With our SMS messaging API you can:

  • Send SMS messages
  • Receive real time delivery reports (DLR) for all messages sent
  • Receive replies and inbound SMS messages
  • Access a range of other useful messaging functions such as Lists, Virtual Numbers, Keywords & Reseller features

Our simple REST API allows you to get up and running in minutes, just follow the helpful Quick Start guide. For advanced users, dig deeper into our technology and check our reference guides for more detailed functions and calls. We have a wide range of calls to mirror useful functionality on the site at both user and reseller level. We also offer a number of client libraries and code samples in order to make your experience using the API suite as clean as possible.

So let’s now look at how to use and get the best out of the REST API.

Numbers

Numbers are the Caller ID, or from field that your messages will come from. Although not mandatory for API use, we recommend users lease their own Dedicated Virtual Number to send and receive messages through the API. You can choose and lease a dedicated number in the NUMBERS section of your account. This will give you the benefit of having your own number identity that is unique to your account. You are welcome to use the free shared number pool, but will be sharing these numbers with many other small customers, and you won’t be likely to get the same number each time you send a message.

Request

All requests must be to the base URL. We provide you with an option of a response as a JSON object, or an XML string. You can choose which response you want by selecting the appropriate suffix (.json OR .xml) in your request.

Base URL

https://api.transmitsms.com

HTTP Methods

All requests are submitted through the HTTP POST or GET method using UTF-8 encoding and URL encoded values.

Security

To ensure security & privacy the API only works over HTTPS protocol for all requests. Also, for your own security, If you have a website with a form which sends SMS be sure to send the request from your server and not directly from the browser otherwise you will be giving away your API secret and opening the floodgates to unwanted charges.

Authentication

All API requests require your API credentials, you will find them once logged into your Account on the SETTINGS page. For Security API credentials must be passed as HTTP Basic Authentication headers not as CGI parameters.

Throttling

To provide the best service to all our customers we limit the number of API calls which can be made by each account to 2 calls per sec. For heavy users we can increase your throttling speed, but please contact us to discuss your requirements. If you exceed this limit we will return two indicators which you can use in your code to detect that you have been throttled. The first is the HTTP status code 429 “Too Many Requests”, the second is the error code “OVER_LIMIT” in the error block of the response body.

Timestamps

All timestamps are in ISO8601 format, e.g. YYYY-MM-DD HH:MM:SS. The zone is always UTC.

Pagination

Some responses are too large to be returned in one go so we paginate. To identify which calls use pagination look for the “page” and “max” parameters in the parameter descriptions for each API call. These calls include a “page” block in the response with two values, “count” and “number”. Count tells you how many pages are available and number indicates the page number you are on. The page parameter is used to request a certain page, it defaults to 1. The max parameter is used to limit the number of results returned per page, the default is 10, the maximum is 100.

Error Reporting

Always check if your API call was successful or resulted in error. You may check the following

  • 200 OK response header. It will be 4xx if an error occurred.
  • error->code structure should equal to ‘SUCCESS’. Please check the table below for common error constants. Note that some API functions can return custom errors of their own (listed in appropriate document sections). Check the error->description for details, e.g. which field caused an error or which resource you don’t have access to.
Code Header Description
AUTH_FAILED_NO_DATA 401 You have not provided auth data.
AUTH_FAILED 401 The auth data you have provided is invalid.
NOT_IMPLEMENTED 404 The method you are requesting is unsupported.
OVER_LIMIT 429 You have exceeded the request limit.
FIELD_EMPTY 400 Required field is empty.
FIELD_INVALID 400 Field has invalid format (see proper format in the description).
NO_ACCESS 400 You do not have access to this resource.
KEY_EXISTS 400 The resource with this key already exists.
NOT_FOUND 400 The resource with this key is not found.

HTTP Callbacks

The best way to get immediate notification on the events like SMS delivery or incoming message is to set up callback URLs. We will call this URL immediately after the event occurs and, if the call was unsuccessful, we will retry a few times later. We perform a GET request. If you need to pass a predefined parameter, include it in your URL e.g:

  • (with own pre-defined value to pass):
    http://www.myserver.com/process_dlr.php?myparameter=myvalue
  • (with default params):
    http://www.myserver.com/process_dlr.php

DLR’s (Delivery Receipts)

DLR’s or Delivery Receipts, are notifications received from the carriers relating to the success or otherwise of an attempted SMS Delivery. Your DLR Callback URL is the default URL we post incoming DLR’s to. You can also set the DLR Callback URL separately for individual messages. This is done using a parameter on the send-sms call.

Here is a list of parameters we include in our callback request:

PARAMETER DESCRIPTION
message_id Your message ID
mobile Recipient’s mobile
longcode The number message was delivered to
datetime Date/time of delivery. UTC.
status delivery status (see table below)

Callback Example

http://yoururl.com/?response=message&longcode=614XXXXXXXX&mobile=614XXXXXXXX

We simplify the native carrier codes into a range of 4 responses:

DLR RESPONSE DESCRIPTION
delivered Your message has been successfully delivered to the recipients handset.
pending We have delivered your message to the carrier and they are attempting to deliver it to the recipients handset.
soft-bounce The message timed out after 72 hrs, either the recipient was out of range, their phone was off for longer than 72 hrs or the message was unable to be delivered due to a network outage or other connectivity issue.
hard-bounce The number is invalid or disconnected. You can safely delete the number from your list.
status delivery status (see table below)

Reply Callback URL

The default Reply Callback URL is used to manage incoming SMS. This is the default URL we will post all incoming messages back to. You can set the Reply Callback URL separately for individual messages. This is set as a parameter on the Send-SMS call. If we should not be able to reach your configured http callback endpoint, we will retry the attempt a maximum of 4 times with a increasing delay of 1min, 5min, 1hr and finally 24hrs.

Incoming SMS are broadly similar, with 2 subtly different forms:

  • SMS Replies: are messages received ‘in response’ to an SMS message sent by you. Responses can come in on both the System Shared Number Pool or any Dedicated Virtual Number, and will be posted to the Default URL above if there was no URL set as a parameter in the Send-SMS call.
  • Inbound SMS: are messages that are received originating from a users mobile phone and are not in response to a message sent via Burst. Inbound SMS can only be received on a Dedicated Virtual Number and will only be posted to the Default URL supplied above.

Here is a list of parameters we include in our callback request:

PARAMETER DESCRIPTION
message_id Your message ID
mobile Sender’s mobile
longcode The number message was delivered to
datetime_entry Date/time that message was received. UTC.
response Message text
is_optout Opt-out flag. ‘yes’ or ‘no’

Global Opt Out

The Global Opt-Out (GOO) is an account wide function that allows for automated SPAM compliance with a minimum of hassle on your side.

If the GOO is switched ON: All recipients who reply with the word ‘STOP’ to any of your messages will be automatically added to the GOO list. All outbound messages are checked against the GOO and messages sent to any numbers on this list will be prevented from delivering.

If the GOO is switched OFF: None of the above functionality is enabled, and you are required to manage your own SPAM compliance in full.