SMS Gateway API – Specification

This blog post has been superseded with our website documentation

It is recommended that you use the  RESTful version of the API which has largely superseded this document (you can do more with it). However if you want to get up and running quickly then it might still be the best way for you.
When you create a free account you can also use the Text Marketer API (sometimes known as a gateway).
The API uses simple HTTP GET requests to communicate with the Text Marketer gateway server. The requests allow you to send SMS’s through the system, you can also retrieve delivery reports discussed here.

HTTP GET Request Parameters

* optional parameter, discussed below.
URL ENCODING
You must url encode the orig and message parameters, if you dont do this you’ll get gateway failures or odd results.
SUPPORTED CHARACTERS
The GSM alphabet is a subset of ISO-8859-1. The SMS GSM characters we can support is documented here
CONCATENATION
If you exceed 160 characters you automatically convert to concatenation sending, this has the following connotations. Each message consists of a 153 character ‘chunk’ (not 160 chars) the extra characters are used to glue the messages together. Therefore a message that is 307 characters long will require 3 messages to send.

An Example HTTP GET Request

https://api.textmarketer.co.uk/gateway/?username=n&password=s&number=4477777777&message=test&orig=me&option=xml

This would send an SMS to 4477777777 from “me” with the message “test”, remember the username “n” and password “p” can be found un your account under the Text Response => API Settings menu option.
SSL (HTTPS) Support
The API also supports SSL, just use port 443 instead ( https:// )

Gateway Responses

The API or Gateway can respond in 2 formats depending if you have set the option=xml (recommended) or not.
No option parameter (or option blank).  Simple ‘plain text’ response
Once you have made a successful connection (HTTP 200) to our server and sent the request the server will reply in two different ways.

• SUCCESS <new line><number of credits remaining><new line>
• FAILED <new line> <reasons><number of credits remaining if available><new line>

The final line of the response contains the number of credits you have remaining, you get 10 free credits with your account.
A simple PHP 5 class for sending bulk SMS is available here
Using the option=xml (recommended)
A better way of decoding the response is to use the parameter option, this will make the gateway respond in the  XML format which gives room for future proofing and also it’s a better way to interpret / parse the results.
XML Example (success)

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE response SYSTEM "https://api.textmarketer.co.uk/dtd/api_response.dtd">

<response status="success" id="1213465434">

    <credits>1000</credits>

   <credits_used>1</credits_used>

</response>

XML Example (failure)

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE response SYSTEM "https://api.textmarketer.co.uk/dtd/api_response.dtd">

<response status="failed" id="0">

   <reason>invalid message or missing</reason>

   <reason>invalid number or too short</reason>

</response>
 

The DTD for the xml is available here

. In reality it doesn’t get any more complicated than the above.
A simple PHP 5 class for sending bulk SMS is available here
Help and an example of our short code API

Supported and Unsupported characters in Text Messages – GSM Character Set

PHP 5 Delivery Report Helper Class for our SMS Gateway

PHP 5 SMS Send Class implementing listeners on our SMS Gateway

Using the SMS Gateway API, Automating Delivery Report Collection

Text Marketer short code API options