Skip to end of metadata
Go to start of 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>

Example

SUCCESS
10

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

Example

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.

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.

Additionally to the response content, specific HTTP 4xx codes will be returned. These are some common usage scenarios:

  • requests with invalid or missing variables will have a HTTP 400 response code;
  • requests with failed authentication details will have a HTTP 401 response code;
  • requests from an account that is suspended will have a HTTP 403 response code;
  • requests trying to send messages to international numbers while international send is not enabled will have a HTTP 403 response code.

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

Example

Failed send

Example

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 MeaningHTTP Code
0Refused (bad number or trying international sending without a valid account)403
1

Bad username or password.

401
2You have zero credits.402
3

The originator is invalid or too long.

400
4The originator is invalid or missing.400
5

The message is invalid or too long.

400
6

You have insufficient credits to send this message.

402
7The message is invalid or missing.400
8

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

400
9The mobile numbers are invalid or too short.400
10

The mobile numbers are invalid or not an integer.

400
11The validity value is out of range.400
12

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

400
13The 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

Example