| SEO Metadata | ||
|---|---|---|
| ||
|
The API or Gateway can respond in 2 formats depending if you have set the option=xml (recommended) or not.
Option Parameter blank or missing
The API responds in simple ‘plain text’ mode.
Once you have made a successful connection (HTTP 200) to our server and sent the request the server will reply in two different ways.
SUCCESS <new line><number of credits remaining><new line>
| Info | ||||
|---|---|---|---|---|
| ||||
SUCCESS |
- FAILED <new line> <reasons><number of credits remaining if available><new line>
| Info | ||||
|---|---|---|---|---|
| ||||
FAILED |
The final line of the response contains the number of credits you have remaining, you get 10 free credits with your account.
HTTP Response Codes to errors
Since 23 November 2015, our Simple Bulk SMS API stopped responding to all requests with a HTTP 200 response code. While the response content remains the same, only accepted requests will have a HTTP 200 response code. TextMarketer introduced this change to enhance efficiency and make sure user is aware when a request is not accepted by some reason.
| Warning |
|---|
Additionally to the response content, specific HTTP 4xx codes will be returned. These are some common usage scenarios:
|
See below Specific errors table for a detailed list of HTTP codes for each error.
Option Parameter set to xml
A better way of decoding the response is to use the parameter option, this will make the gateway respond in the XML format which gives room for future proofing and also it’s a better way to interpret / parse the results.
Successful send
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE response SYSTEM "http://api.textmarketer.co.uk/dtd/api_response.dtd"> <response status="success" id="6187376142" > <credits>120</credits> <credits_used>1</credits_used> </response> |
Failed send
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE response SYSTEM "http://api.textmarketer.co.uk/dtd/api_response.dtd"> <response status="failed" id="0" > <credits>121</credits> <reason id="4" >invalid originator or missing</reason> </response> |
Response meanings
| XML tag/attribute | Meaning |
|---|---|
| status* | Did the message get sent, success / failed / queued / scheduled. |
| id | The unique ID of the message sent. You can use this ID to fnd the status of the sent message in the delivery report. |
| credits_used | The number of credits used to send the message. |
| credits | Credits remaining. |
*Status can also be one of the following values:
- Queued : We weren't able to send immediately.
- Scheduled: You have requested a send date in the future.
| Anchor | ||||
|---|---|---|---|---|
|
| Code | Meaning | HTTP Code |
|---|---|---|
| 0 | Refused (bad number or trying international sending without a valid account) | 403 |
| 1 | Bad username or password. | 401 |
| 2 | You have zero credits. | 403402 |
| 3 | The originator is invalid or too long. | 400 |
| 4 | The originator is invalid or missing. | 400 |
| 5 | The message is invalid or too long. | 400 |
| 6 | You have insufficient credits to send this message. | 403402 |
| 7 | The message is invalid or missing. | 400 |
| 8 | The message contains unsupported characters (these will be listed in the error message). | 400 |
| 9 | The mobile numbers are invalid or too short. | 400 |
| 10 | The mobile numbers are invalid or not an integer. | 400 |
| 11 | The validity value is out of range. | 400 |
| 12 | The custom value is non-alphanumeric or out of range. | 400 |
| 13 | The mobile number is in a STOP group. | 403 |
Queued send
Format the same as success above, the only difference is that the message has been queued, this typically means a 5 minute delay. This status is very rare.
The DTD of the response
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
<!ATTLIST response id CDATA #REQUIRED status CDATA #REQUIRED > <!ATTLIST reason id CDATA #REQUIRED > <!ELEMENT response (credits?,credits_used?,reason*)> <!ELEMENT credits (#PCDATA)> <!ELEMENT credits_used (#PCDATA)> <!ELEMENT reason (#PCDATA)> |