Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

 

SEO Metadata
titleAPI Responses

 

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
iconfalse
titleExample

SUCCESS
10

  • FAILED <new line> <reasons><number of credits remaining if available><new line>

 


Info
iconfalse
titleExample

FAILED
Error: invalid originator or missing
121

The final line of the response contains the number of credits you have remaining, you get 10 free credits with your account.

 

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
themeRDark
languagexml
titleExample
linenumberstrue
<?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
themeRDark
languagexml
titleExample
linenumberstrue
<?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/attributeMeaning
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.

Specific errors

Code Meaning
0Refused (bad number or trying international sending without a valid account)
1

Bad username or password.

2You have zero credits.
3

The originator is invalid or too long.

4The originator is invalid or missing.
5

The message is invalid or too long.

6

You have insuffcient credits to send this message.

7The message is invalid or missing.
8

The message contains unsupported characters (these will be listed in the error message).

9The mobile numbers are invalid or too short.
10

The mobile numbers are invalid or not an integer.

11The validity value is out of range.
12

The custom value is non-alphanumeric or out of range.

13The mobile number is in a STOP group.

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
themeRDark
languagexml
titleExample
linenumberstrue
<!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)>