SMS Broadcast APIs (REST)
Updated
by
RM
Access
The API can be accessed via POST only at the following URL:
Authentication
Requests must contain a basic authentication header, containing your username and password.
Fields
Field | Notes |
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. |
subject* | 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, then 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. |
Content Format
Set the 'Content-Type' header field to one of the following in order to specify the format of the request:
Format | Content-Type |
XML | application/xml |
JSON | application/json |
Form Values | application/x-www-form-urlencoded |
Response Format
Set the 'Accept' header field to one of the following to specify a response format. If no 'Accept' header is specified, the server will respond with XML by default.
Format | Accept |
XML | text/xml |
JSON | text/json |
HTML (table) | text/html |
CSV | text/csv |
An example XML submission:
An example JSON submission:
An example XML response:
An example JSON response:
An example CSV response:
An example HTML response
Return Codes
HTTP Status Code | Reason/Action |
200 OK | Your batch was sent |
400 Bad Request | Missing required field/incorrectly formed data |
401 Unathorized | Invalid credentials |
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.
If the accept header is set to text/json, then it will be sent as JSON otherwise the delivery report will be in XML.
The delivery report will 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 re-formatted 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 XML delivery report:
An example JSON delivery report:
Delivery 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 | Undeliverable |
10 | Failed to send after 3 attempts |
15 | Invalid originator |
Delivery reports will be attempted a maximum of 3 times, in the event your handler is down.
Message Status Request
Fields
Field | Notes |
batch | The Batch ID returned when the request was submitted |
mobile* | To see a specific message within the batch the mobile can be supplied |
* optional
To check the status of a batch or a specific message in a batch, a 'GET' request can be sent to the following URL:
An example GET request:
Return Values
Example XML response:
Example JSON response:
Example HTML response:
Example CSV response:
Return Codes
HTTP Status Code | Reason/Action |
200 OK | Batch status returned |
400 Bad Request | Missing required field/incorrectly formed data |
401 Unathorized | Invalid credentials |
404 Not Found | Could not find the specified batch (and mobile if provided). |
500 Internal Server Error | The server encountered an error processing the request. |
