The API or Gateway can respond in 2 formats depending if you have set th= e option=3Dxml (recommended) or not.
The API responds in simple =E2=80=98plain text=E2=80=99 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 l= ine>
Example
=20SUCCESS
10
Example
=20FAILED
Error: invalid originator or missing
121
The final line of the response contains the number of credits yo= u have remaining, you get 10 free credits with your account.
Since 23 November 2015, our Simple Bulk SMS API stopped responding to al= l requests with a HTTP 200 response code. While the response content remain= s the same, only accepted requests will have a HTTP 200 response code. Text= Marketer introduced this change to enhance efficiency and make sure user is= aware when a request is not accepted by some reason.
Additionally to the response content, specific HTTP 4xx codes will be re= turned. These are some common usage scenarios:
See below Specific erro= rs table for a detailed list of HTTP codes for each error.
A better way of decoding the response is to use the parameter option, th= is will make the gateway respond in the XML format which gives room for fut= ure proofing and also it=E2=80=99s a better way to interpret / parse the re= sults.
<?xml version=3D"1.0" encoding=3D"ISO-8859-1"?&= gt; <!DOCTYPE response SYSTEM=20 "http://api.textmarketer.co.uk/dtd/api_response.dtd"> <response status=3D"success" id=3D"6187376142" > <credits>120</credits> <credits_used>1</credits_used> </response>=20
<?xml version=3D"1.0" encoding=3D"ISO-8859-1"?&= gt; <!DOCTYPE response SYSTEM=20 "http://api.textmarketer.co.uk/dtd/api_response.dtd"> <response status=3D"failed" id=3D"0" > <credits>121</credits> <reason id=3D"4" >invalid originator or missing</reason&= gt; </response>=20
| XML tag/attribute | Meaning |
|---|---|
| status* | Did the message get sent, success / failed / = queued / scheduled. |
| id | The unique ID of the message sent. You can us= e this ID to fnd the status of the sent message in the delivery report. = |
| credits_used | The number of credits used to send the messag= e. |
| credits | Credits remaining. |
*Status can also be one of the following values:
| Code | Meaning | HTTP Code |
|---|---|---|
| 0 | Refused (bad number or trying international send= ing without a valid account) | 403 |
| 1 | Bad username or password. |
401 |
| 2 | You have zero credits. | 402 |
| 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 me= ssage. |
402 |
| 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 inte= ger. |
400 |
| 11 | The validity value is out of range. | 400 |
| 12 | The custom value is non-alphanumeric or out o= f range. |
400 |
| 13 | The mobile number is in a STOP gro= up. | 403 |
Format the same as success above, the only difference is that the messag= e has been queued, this typically means a 5 minute delay. This status is ve= ry rare.
<!ATTLIST response=20 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)>=20