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

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.
You must url encode the orig and message parameters, if you dont do this you’ll get gateway failures or odd results.
The GSM alphabet is a subset of ISO-8859-1. The SMS GSM characters we can support is documented here
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

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>
invalid number, not an integer
invalid number, too short

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 "">
<response status="success" id="1213465434">

XML Example (failure)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE response SYSTEM "">
<response status="failed" id="0">
   <reason>invalid message or missing</reason>
   <reason>invalid number or too short</reason>

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