In addition to our simple HTTP SMS Gateway API, explained here, we also provide a ‘RESTful’ SMS API to give you access to information about your SMS marketing account (don’t have one? Create a free account).

If you are familiar with REST APIs, you may wish to jump to our REST API specification document.

WHAT’S A ‘RESTful’ SMS API?

REST is a term used to describe a type of two-way communication via the Internet. It is an architectural style, not a standard, but makes use of well-known web technologies such as HTTP, XML and MIME types. For more information about REST APIs, read this great description of REST.

At its most simple, our RESTful SMS API allows you to request (‘GET’) information. For example, from this ‘resource’

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

you can access the number of credits available in your account. The response is an XML document that looks like this:

<response processed_date="2010-03-19T09:37:26+00:00">
<credits>37</credits>
</response>

The SMS REST API is that simple!

WHAT ABOUT SECURITY?

Although it’s not apparent from the example above, the interface does require authentication using your SMS API account username/password. We provide two ways of passing this information to the server.

The first is via HTTP Basic Authentication, which is demonstrated by the login box that appears if you click on the resource link above. HTTP Basic authentication can of course be handled within your code. However if you prefer a simpler method, you can pass the parameters via the URL as GET arguments, e.g.

http://www.textmarketer.biz/services/rest/credits?username=myusername&password=mypassword

It is also recommended that you use encrypted communication with the REST Web Services by accessing resources via the HTTPS protocol (https://… etc.).

HOW DOES THE RESTful API HANDLE ERRORS?

An advantage of using a RESTful API is that the underlying technologies already do a lot of the work for us. All responses via the HTTP protocol include headers that give us some information about the response. The headers in the above example would look like this:

Date: Fri, 19 Mar 2010 10:11:40 GMT
Server: Apache/2.2.3 (Red Hat)
X-Powered-By: PHP/5.2.11 ZendServer/4.0
Content-Length: 272
Connection: close
Content-Type: application/xml

200 OK

The MIME type (Content-Type) is set to application/xml which identifies the type of content in the response. It is followed by the response status code ’200′ and the status message ‘OK’. This is a standard response to a successful request.

If we had tried to access a resource which didn’t exist, e.g.

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

we would get the following response headers:

Date: Fri, 19 Mar 2010 10:18:23 GMT
Server: Apache/2.2.3 (Red Hat)
X-Powered-By: PHP/5.2.11 ZendServer/4.0
Content-Length: 549
Connection: close
Content-Type: application/xml

404 Not Found :  (ERR101)

The status code is 404, which is the HTTP protocol’s standard code for ‘resource not found’. The status message also contains some additional debugging information (ERR91) which you can ignore.

In addition to the status code, the response body contains XML detailing the error. In this example it might look like this:

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

Thus, you can check the header status code for an error code, as well as the response body.

WHAT RESOURCES CAN I ACCESS THROUGH THE REST SMS API?

At the moment, the resource URIs available to you are:

• http://www.textmarketer.biz/services/rest/credits – to get the credits available on your account / transfer credits between accounts
• http://www.textmarketer.biz/services/rest/deliveryReports – to list your delivery reports
• http://www.textmarketer.biz/services/rest/deliveryReport/a_report_name – to access the details of a specific report
• http://www.textmarketer.biz/services/rest/sms – to send an SMS
• http://www.textmarketer.biz/services/rest/keywords – to get the availability of a given keyword (see Short Code SMS Service)

More will be added in the future.

Here are 2 walk-through examples for using the REST SMS API.

EXAMPLE REQUEST 1 – GET CREDITS

Make an HTTP GET request like this:

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

Obviously, replace ‘myAPIusername’ and ‘myAPIpassword’ in the URL with the ones you received when you signed up.

When you send this request using your favorite programming language, you should receive the following HTTP headers in response:

Date: Wed, 24 Mar 2010 15:17:28 GMT
Server: Apache/2.2.3 (Red Hat)
X-Powered-By: PHP/5.2.11 ZendServer/4.0
Content-Length: 272
Connection: close
Content-Type: application/xml

200 OK

Using your programming language, you can easily extract the status code (200 in this case), which indicates success (200) or failure (not 200). The status code of 200 here shows us the request was successful, i.e. the response contains the number of credits in your account.

Thus the HTTP response body that you receive will contain XML similar to this:

<response processed_date="2010-03-24T15:17:28+00:00">
<credits>10</credits>
</response>

In your programming language you can parse the XML to extract the value of the credits, in this case 10.

But if, for example, you use an incorrect password, the response headers will look like this:

Date: Wed, 24 Mar 2010 15:30:10 GMT
Server: Apache/2.2.3 (Red Hat)
X-Powered-By: PHP/5.2.11 ZendServer/4.0
Content-Length: 377
Connection: close
Content-Type: application/xml

403 Forbidden : Your username/password combination did not match an account. (ERR145)

The 403 status code shows that an error occurred (all codes except 200 indicate an error). And the XML response body will also contain:

<response processed_date="2010-03-24T15:29:22+00:00">
<errors>
	<error code="403">Forbidden : Your username/password combination did not match an account. (ERR145)</error>
</errors>
</response>

EXAMPLE REQUEST 2 – SEND SMS

In your programming language, create an HTTP POST request to this URL:

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

Since this is a POST request, you cannot pass the username and password via the URL, so you need to use HTTP Digest Authentication, or simply include these parameters along with the other POST parameters you’ll need:

• message=’my message’
• originator=’me’
• mobile_number=’447777777777′
• username=’myAPIusername’ (replace with your own – or skip this parameter and use HTTP Digest Authentication)
• password=’myAPIpassword’ (replace with your own – or skip this parameter and use HTTP Digest Authentication)

POSTing an HTTP request using the above as POST parameters would send an SMS message of ‘my message’ to the mobile number 447777777777 from “me”.

NOTE: It will not work to pass these parameters as GET arguments (e.g. by appending them to the URL); this is the principle of a REST API.

Your HTTP POST request should return something similar to the following response headers:

Date: Wed, 24 Mar 2010 15:17:28 GMT
Server: Apache/2.2.3 (Red Hat)
X-Powered-By: PHP/5.2.11 ZendServer/4.0
Content-Length: 272
Connection: close
Content-Type: application/xml

200 OK

…the ’200′ status code showing that your request was successful. The HTTP response body will consist of XML containing the ID of the SMS sent as well as the number of credits used to send it:

<response processed_date="2010-03-23T10:31:39+00:00">
	<message_id>4172870907</message_id>
	<credits_used>1</credits_used>
</response>

If, however, there was a problem with your request parameters, for example you set mobile_number to ‘garbage’, you would get similar response headers to this:

Date: Wed, 24 Mar 2010 15:30:10 GMT
Server: Apache/2.2.3 (Red Hat)
X-Powered-By: PHP/5.2.11 ZendServer/4.0
Content-Length: 377
Connection: close
Content-Type: application/xml

404 Bad request

And the response body would contain XML detailing the precise problems with your request, like this:

<response processed_date="2010-03-24T14:37:41+00:00">
<errors>
	<error code="10">invalid number or not an integer</error>
	<error code="9">invalid number or too short</error>
</errors>
</response>

See the specification of the sms resource for more details of the possible error codes.

TESTING/SANDBOX

A sandbox service is available for testing your code without changing your account or using any credits.

MORE INFORMATION

For detailed information about our RESTful SMS API, please see our REST API specification document.

For reference, a list of the DTDs that correspond to the resources available can be found here.

Adding SMS as a communication method to a system is often very useful, for instance you don’t have issues with spam filtering, it doesn’t require the person to make an immediate response like a phone call, so it’s great for alerts and triggers. Another good application for SMS (text messaging) which is often over looked is the ability to use it as a method to update a system or retrieve information without needing any equipment other than a mobile phone, any one would work. This is done using a short code.

Consider this example:

You own a fictitious “temporary employment agency” with several hundred people on your books.  Your client has asked you to fulfill a specific job such as a receptionist. You send an SMS:

Receptionist cover required for 2 weeks 4 hr per day @ £10 per hr, location Bristol. Reply with “more 4567a” for more info.

The last bit (more 4567a) is the information that allows us to automate things, the keyword more is used to identify you, and the code would be a reference to the job. The potential candidate could then reply where by (in this case) you could :

1. Send more details from the job description
2. Update the database that this person is a likely candidate
3. The person has expressed interest in the receptionist job, we could make an assumption that they maybe interested in other receptionist jobs so you could start creating groups that could be used for later targeting.

Implementation

So how do we set up the SMS gateway and send messages? Fortunately it’s easy.
First you need an account (it’s free) and automated. You’ll get the user name and password you need plus you get some free sends. You will also need to ask for the API URL.

Next use the out bound API (sometimes called an SMS gateway) for your message. This is a simple HTTP GET request which can either be sent via http or https. You will need to url encode the message.
http://<request the url>?username=myUsername&password=myPassword&number=447777777777&message=Receptionist+cover+required+for+2+weeks+4+hr+per+day+%40+%C2%A310+per+hr%2C+location+Bristol.+Reply+with+%22more+4567a%22&orig=88802
You can try the above in any old browser.

There is an example class (in PHP 5) that would do this for you

Next we want to use the incoming response from the recipient

This is the bit where we need to speak to or email the company,  a keyword is required  (which is free) on the 88802 short code, in our example we are using the word “more”. You then supply Text Marketer with a URL on your domain that will get notified with the parameters once a response is received. For example www.mydomain.com/myscript.php

If the applicant replied with “more 4567a” you would receive an HTTP GET like this http://www.mydomain.com/myscript.php?number=4477777777&message=more+4567a&network=ORANGEUK

It is then up to you how you use this information, the example gives a few ideas.