REST SMS Gateway API – Specification Document

  • Why not share:
  • Social sharing button for Facebook
  • Social sharing button for Linkedin
  • Social sharing button for Twitter
  • Social sharing button for Googleplus
  • Social sharing button for Pinterest

This blog post has been superseded with our website documentation

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:

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://api.textmarketer.co.uk/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://api.textmarketer.co.uk/services/rest/credits

The base request URI is thus composed of :

https://api.textmarketer.co.uk/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://api.textmarketer.co.uk/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://api.textmarketer.co.uk/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:

Code Meaning
200 OK. We were able to successfully execute the requested operation.
400 Bad request. There was a problem with your request data, see the status message for details.
403 You do not have sufficient rights to access the specified resource.
404 The resource specified could not be found.
405 The specified method (get, post, put or delete) is not allowed for this resource.
500 An unexpected error occurred.
501 The method requested has not been implemented.
503 Service Unavailable. The Web Service is not currently available to serve your request.

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://api.textmarketer.co.uk/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://api.textmarketer.co.uk/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 = api.textmarketer.co.uk/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://api.textmarketer.co.uk/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://api.textmarketer.co.uk/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://api.textmarketer.co.uk/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://api.textmarketer.co.uk/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://api.textmarketer.co.uk/services/rest/sms
  • POST method - Used to send an SMS message.

See the full description of this resource for details.

5. keywords

http://api.textmarketer.co.uk/services/rest/keywords/mykeyword

See the full description of this resource for details.

6. group

http://api.textmarketer.co.uk/services/rest/group
  • POST method - add number(s) to a send group

See the full description of this resource for details.

7. groups

http://api.textmarketer.co.uk/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 api.textmarketer.co.uk 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.


Related articles

  1. REST SMS API Code Examples
    This blog post has been superseded with our website documentation In our REST API specification document we saw, in general terms, how to...
  2. 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...
  3. The SMS Gateway
    How to use an SMS Gateway Continue reading →...
  4. Top Notch Health Clubs Integrate with Text Marketer’s SMS Gateway
    South East based health club chain, Top Notch Health Clubs are using Text Marketer’s SMS gateway to keep in touch...
  5. PHP and SMS
    PHP is the very popular web scripting language, to make things easy for the PHP programmer we have provided some...
  6. 5 Reasons Why You Can’t Afford To Ignore Mobile Marketing
    1. It’s the most responsive direct marketing channel available. Using bulk sms as a way of communicating an offer to...
  7. SMS Dominance to Continue
    The popularity of sms messaging will continue for the foreseeable future according to a new report. The report, released by...