HTTP API: How To Send A Message

Use HTTP to Send a Text Message

Texts can be sent either as a POST or a GET. We recommend that you use a POST if possible, as conventionally GETs just retrieve information, and do not invoke actions such as sending a text message. However, GETs are supported to aid debugging if required.

All strings sent when calling the API should be sent in UTF-8 format, and should be URL encoded.

Destination URL

The POST should be submitted to the following URL:
http://www.totext.net/selfcare/com/zipzaptext/selfcare/SendMessagesApi.action

Mandatory Parameters

The following parameters are required in all submissions to the API, and please note that they are all case-sensitive:

message: The message that will be sent. This will be truncated if it exceeds that maximum length specified in your account settings.
destination: Comma separated list of mobile phone numbers. Include the country dial code if sending abroad.
username: API username for your account. Note that this is not the same as the one used to log into the management pages.
password: API password for the account. Note that this is not the same as the one used to log into the management pages.

Optional Parameters

The following optional parameters help you exert a fine grained level of control over how messages are sent. Please note that all parameters are case-sensitive.

emailAddress: If present, replies and delivery reports will be routed to this email address.
successPage: If the text message is sent successfully, toText.net will issue a 302 server redirect to this page.
failurePage: If the text message could not be sent for any reason, toText.net will issue a 302 server redirect to this page.
reference: Your reference for this message. When a reply or delivery report is received, this reference will be included in the HTTP POST that we send you.
referenceLabel: Allows a label to be specified that defines the name of the reference parameter. If this is not specified, the parameter that is sent in the HTTP Post for replies and delivery reports will be called 'reference'.
testMode: See the 'Test Mode' section below.
senderLabel: Sets the Sender ID of the text message to the specified value. This can be a mix of letters or digits up to 11 characters long.

Test Mode

Test mode is invoked by setting the textMode parameter to 1 when the API is called. The system will perform all the usual validation checks, but will not actually send the message or deduct any credits from your account.

An example of the response that is returned if the test mode is set is as follows:
822,1
where the first number represents the number of credits in your account, and the second number indicates the number of credits that would have been required to send the message.

Success Response

If the message was submitted successfully, then the following HTML will be returned to the caller:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Message Sent</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
</head>
<body>
Message submitted. <br>
[COST:1] <br>
</body>
</html>

The [COST: 1] value indicates the number of credits that were required to send the message.

Failure Response

If an error occurs when the message is submitted, then the following HTML will be returned to the caller. Naturally the particular error message will change to indicate the cause of the problem.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Invalid login</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">

</head>
<body>
Unknown username/password combination for the API.<br>
</body>
</html>

Having Problems?

We're very keen that your integration should be straightforward and easy, so if you're having any trouble at all, then please don't hesitate to get in touch.