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>



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


Error: invalid originator or missing

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


Failed send


Response meanings

XML tag/attributeMeaning

Did the message get sent, success / failed / queued / scheduled.


The unique ID of the message sent. You can use this ID to fnd the status of the sent message in the delivery report.


The number of credits used to send the message.


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

Bad username or password.

2You have zero credits.402

The originator is invalid or too long.

4The originator is invalid or missing.400

The message is invalid or too long.


You have insufficient credits to send this message.

7The message is invalid or missing.400

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

9The mobile numbers are invalid or too short.400

The mobile numbers are invalid or not an integer.

11The validity value is out of range.400

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

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