SMS Broadcast API (HTTP)
Updated
by
RM
Access
The API can be accessed via both HTTP GET and POST at the following URL (All fields must be URL encoded.) :
For GET requests the parameters must be specified in the URL. For example:
POST requests can either be sent with the fields in the URL or with the fields specified in the form data of the request.
Fields
Field | Notes |
username | The username for your API account |
password | The password for your API account |
mobile | This can be a single mobile or a comma separated list.
Mobiles can be sent in UK format (i.e starting 07) but will be converted to international format (i.e starting 447) for sending. |
message | A single SMS can be up to 160 characters long. Messages over 160 characters will be sent as a multi-part message which is reassembled at the recipient’s mobile into one long message, but sent as chunks of up to 153 characters. |
sender* | This is the number or text to show as the sender of the message. If alphanumeric, this can be no more than 11 characters. For numeric senders the maximum is 16 digits. If this is not specified, the default for your account will be used. |
encoding* | If you have hex encoded your message as anything other than UTF-8, the encoding used must be specified. |
param1* | This allows you to store a reference for this message. This will be returned in the delivery receipt if a handler is specified. |
param2* | This allows you to store a second reference for this message. This will be returned in the delivery receipt if a handler is specified. |
handler* | This allows you to specify a URL to send delivery reports to. |
hex* | If your message has been converted to hex, set this to 1 otherwise it will be assumed that your message is in plain text. |
Return Values
An HTML message will be returned containing either a success message and the ID of your batch, or an error code.
Result | HTTP Status Code | Reason/Action |
00 - Success | 200 OK | Your batch was sent |
11 - Username/Password incorrect | 401 Unauthorised | Check your API credentials. |
16 - Invalid request - variable 'mobile' not specified | 400 Bad Request | The required field ‘mobile’ has not been provided. |
17 - Invalid request - variable 'message' not specified | 400 Bad Request | The required field ‘message’ has not been provided. |
18 - Invalid Mobile Number - too short | 400 Bad Request | The mobile number received is too short to be valid. Please check and retry. |
19 - Invalid request - unable to parse | 400 Bad Request | The request was not formed correctly and the server was unable to extract the data necessary to send the batch. |
| 500 Internal Server Error | The server encountered an error processing the request. |
Delivery Reports
If a handler is specified in your request the delivery report will be forwarded on to that URL via HTP POST. The delivery report will be in XML and contain the following fields:
Field | Description |
batch_id | The Batch ID returned when the request was submitted. |
mobile | The mobile number of the recipient (If supplied in UK format this will have been reformatted to international format) |
report | This will either be ‘Success’ or ‘Fail’. |
code | A numeric code for more detail of delivery problems. (See Delivery Codes below.) |
param1 | The value sent as param1 when submitting the request. |
param2 | The value sent as param2 when submitting the request. |
An example delivery report:
Delivery Codes
Code | Description |
2 | Sent |
3 | Failed to send to SMS provider |
4 | Provider failed to send the message to the end user. |
6 | Provider rejected the message. |
7 | Expired |
8 | Undelivered |
10 | Failed to send after 3 attempts |
15 | Invalid originator |
