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
Parameter | Comment |
username | Can be found by logging in to your account : Settings -> API Settings |
password | Can be found by logging in to your account : Settings -> API Settings |
orig | Who is the message from? This can be 11 alpha-numeric or 16 numeric characters |
number | The recipient. Please make sure you include the international code e.g 4477777777 |
message | up to 612 character message |
option | can be blank or set to xml (recommended) * |
* 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
http://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>
SUCCESS 4 |
Or |
FAILED invalid number, not an integer invalid number, too short 3 |
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 "http://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 "http://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