For an overview of what REST and our RESTful SMS API is all about you may like to read our RESTful SMS API Overview.

If you prefer you can use the simple SMS gateway, rather than our RESTful implementation.

To get straight into the details, jump to:

Quick Start
Error codes

Sandbox

You can preform the following actions using the REST web service:

• send an SMS (sms post)
• get the number of credits available (credits get)
• transfer credits from one account to another (credits post)
• get a list of delivery reports (deliveryReports get)
• get the contents of a specific delivery report (deliveryReport get)
• check availability of a given keyword on our ShortCode number (keywords get)
• check the names and IDs of your send groups (groups get)
• add number(s) to a send group (group post)

Specification of the resources

1. credits
2. deliveryReports
3. deliveryReport
4. sms
5. keywords
6. group
7. groups

QUICK START
Three things are essentially needed to use the REST SMS API:

1. Ability to make a HTTP request
   • e.g. to https://www.textmarketer.biz/services/rest/credits
2. Ability to read the HTTP response headers
   • e.g. ’200 OK’
3. Ability to parse the XML response
   • e.g. <credits>37</credits>

The Request URI Explained

You will make the HTTP request to a request URI such as:

https://www.textmarketer.biz/services/rest/credits

The base request URI is thus composed of :

‘https://www.textmarketer.biz/services/rest/‘ + a string that denotes the resource to be accessed, e.g. ‘credits‘, ‘deliveryReports‘, etc.

You can use http instead of https, but https is recommended.

Note that cAsE matters, i.e. ‘deliveryReports‘ will work, whereas ‘deliveryreports‘ (lower case ‘r’) will return an error.

You must obviously identify yourself during the request. If you know how to handle HTTP Digest Authentication, that is the preferred method of authentication.

Otherwise you should attach the following to the end of the resource URI:

?username=myAPIusername&password=myAPIpassword

Or, in the case of a POST request, such as for sending an SMS, include the username/password parameters in the POST parameters (e.g. see sms post).

In our example, the complete URI that results is:

https://www.textmarketer.biz/services/rest/credits?username=myAPIusername&password=myAPIpassword

And this should return XML containing the number of credits available on your account.

The HTTP Response Headers

The only vital part of the response headers that you need is the status code. 200 means a successful request, all other codes returned will be errors.

If you get an error, the status message may give you some extra information about the error. For more details about the error codes and their meanings, see Error Codes below.

The XML response

The structure of the XML response is generally quite simple. The response to our credits request example would look like this:

<response processed_date="2010-03-19T14:08:40+00:00">
<credits>37</credits>
</response>

Your preferred programming language will have a method for parsing the XML response to obtain the value.

Example PHP code

<?php
/**
 * GET request on the 'credits' resource
 */
$url = 'http://www.textmarketer.biz/services/rest/credits';
$username = 'myAPIusername'; // CHANGE THIS!!!
$password = 'myAPIpassword'; // CHANGE THIS!!!
$url = "$url?username=$username&password=$password";

// we're using the curl library to make the request
$curlHandle = curl_init();
curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
$responseBody = curl_exec($curlHandle);
$responseInfo  = curl_getinfo($curlHandle);
curl_close($curlHandle);

// deal with the response
if ($responseInfo['http_code']==200)
{
	$xml_obj = simplexml_load_string($responseBody);
	$credits = (int) $xml_obj->credits;
	// do something with the result
	echo $credits;

} else {
	// handle the error
	var_dump($responseBody);
}

?>

See the REST API Code Examples for some more example code that you can use.

That’s the end of the Quick Start. You know to send the request, check the status code is 200, and then parse the XML according to its declared structure.

Error codes

ERROR CODES

The HTTP status codes returned by our REST SMS API follow normal HTTP conventions. An example of the HTTP response headers from a request to our REST API:

Date: Wed, 24 Mar 2010 14:45:54 GMT
Server: Apache/2.2.3 (Red Hat)
X-Powered-By: PHP/5.2.11 ZendServer/4.0
Content-Length: 317
Connection: close
Content-Type: application/xml

404 Not Found :  (ERR101)

You see the status code, 404 on the last line. Their meaning of the status codes in the context of our REST SMS API are as follows:

This list is not exhaustive, any code from the complete list of HTTP status codes may be returned.

IMPORTANT NOTE: Error 503 may be returned if you exceed a certain number of requests per minute. You will see an error message similar to: “Your 201 requests exceed the maximum allowed of 100 requests within 15 minute(s). Please try again later”. This to reduce load on our servers, in order to guarantee a good service to all our users.  There is no restriction on SMS sends.

USEFUL NOTE: the HTTP status message may contain more specific information. If you encounter an unexpected error, the ‘(ERRnn)’ found in the status message is useful in any reports you send us.

In addition to the status codes, an error will also produce an XML response containing details of the error. In this example the XML response might look like this:

<response processed_date="2010-03-24T14:45:54+00:00">
<errors>
	<error code="404">Not Found :  (ERR101)</error>
</errors>
</response>

Some resources, such as http://www.textmarketer.biz/services/rest/sms, have additional error codes specific to the resource. These are documented along with the description of the resource.

Resource Identifier

THE RESOURCE IDENTIFIER

The example of a resource identifier used previously was:

https://www.textmarketer.biz/services/rest/credits

All our REST SMS Web Service resource identifiers take the general form:

PROTOCOL://RESOURCE_NAMESPACE/RESOURCE_NAME[/RESOURCE_ID]

where

PROTOCOL = http|https
RESOURCE_NAMESPACE = www.textmarketer.biz/services/rest
RESOURCE_NAME = credits|deliveryReports|deliveryReport|sms|keywords|etc

RESOURCE_ID = an_ID (optional) which specifies a particular resource element, e.g. a specific delivery report

e.g.

https://www.textmarketer.biz/services/rest/deliveryReport/GatewayAPI_09-02-10

will access a delivery report named ‘GatewayAPI_09-02-10‘.

Resources

RESOURCES

The currently implemented resources are:

1. credits
2. deliveryReports
3. deliveryReport
4. sms
5. keywords
6. group
7. groups

1. credits

http://www.textmarketer.biz/services/rest/credits

• GET method - get the number of credits currently available on your account
• POST method - transfer credits between accounts

See the full description of this resource for details.

2. deliveryReports

http://www.textmarketer.biz/services/rest/deliveryReports

• GET method - Gets a list of available delivery report names

See the full description of this resource for details.

3. deliveryReport

http://www.textmarketer.biz/services/rest/deliveryReport/test-190310

• GET method - Gets the contents of a delivery report – the delivery status of sent messages for a given day/campaign.

See the full description of this resource for details.

NOTE: An individual delivery report that is accessed using this resource shows the current known status of all messages sent on a given day, or for a particular campaign. The REST API resource deliveryReports (note the trailing ’s’) gets a list of available delivery report names, including delivery reports for campaigns (see above).

4. sms

http://www.textmarketer.biz/services/rest/sms

• POST method - Used to send an SMS message.

See the full description of this resource for details.

5. keywords

http://www.textmarketer.biz/services/rest/keywords/mykeyword

• GET method - get the availability of a given keyword (see Short Code SMS Service)

See the full description of this resource for details.

6. group

http://www.textmarketer.biz/services/rest/group

• POST method - add number(s) to a send group

See the full description of this resource for details.

7. groups

http://www.textmarketer.biz/services/rest/groups

• GET method - list the available send groups

See the full description of this resource for details.

Sandbox

TESTING/SANDBOX

A sandbox service is available to allow you to test your integration code without using any credits or executing any function that would modify the data in your account. The service is available at

http://sandbox.textmarketer.biz/services/rest

i.e. only the hostname changes from www.textmarketer.biz to sandbox.textmarketer.biz within the resource URI.

The sandbox will do the same validation of your request as the live REST API and return the appropriate errors, but will not perform any action that modifies your account data or your credits. Nor will it actually send any SMS messages, so no delivery report will be generated.

NOTE: Accesses to the sandbox is limited to a certain number of requests per minute – to reduce load on our servers – in order to guarantee a good service to all our users. Therefore you may prefer to use the Sandbox only to check that individual requests work correctly, rather than testing bulk SMS sends. There is no restriction on SMS sends on the live system.

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 covert 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://www.textmarketer.biz/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 "http://www.textmarketer.biz/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://www.textmarketer.biz/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

Help with ASP Bulk SMS

NET Examples

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