This blog post has been superseded with our website documentation
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.
At its most simple, our RESTful SMS API allows you to request (‘GET’) information. For example, from this ‘resource’
https://api.textmarketer.co.uk/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.
https://api.textmarketer.co.uk/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.
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.
https://api.textmarketer.co.uk/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:
- https://api.textmarketer.co.uk/services/rest/credits – to get the credits available on your account / transfer credits between accounts
- https://api.textmarketer.co.uk/services/rest/deliveryReports – to list your delivery reports
- https://api.textmarketer.co.uk/services/rest/deliveryReport/a_report_name – to access the details of a specific report
- https://api.textmarketer.co.uk/services/rest/sms – to send an SMS
- https://api.textmarketer.co.uk/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:
https://api.textmarketer.co.uk/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:
https://api.textmarketer.co.uk/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.