eTXT Legacy API Introduction
NOTE: For new customer's we strongly advise using the eTXT REST API for new integrations.
The eTXT Legacy API provides the simplicity that you are looking for when enabling your applications to send SMS messages. Sending a message is as easy as POSTing a web form.
The HTTP API interface contains the following functions:
To use the API simply authenticate your user and POST method parameters to the eTXT server in the same way that a browser would.
To do this method parameters are first HTML form encoded and then submitted in a HTTP POST. This is well supported in most development environments.
Note: The number and order of parameters may vary. The parameter names described in this document will not change, however new parameters may be added from time to time.
Top Tips - useful pointers
Using a REST API is straightforward - no mucking around with XML and a very simple interface. It is best to get familiar with the REST API outside of your code first - so that you can get a feel of how it hangs together without writing stuff and realising there may have been an oversight.
GUI Tools
We can recommend Postman as a way to easily construct the API calls to eTXT - including saving them for later reference.
Command line tools
cURL is an awesome old-school tool for fetching and putting to web URL's from the command line. There is even a Windows version if you don't fancy using a GUI as mentioned above. Because cURL is a command line tool you can build it into scripts such as Bash shell scripts and use those to interact with the eTXT API. Perfect if you don't want to start involving developers.
API Authentication
Before we allow use of our APIs you must first authenticate yourself, so we know who you are. API calls can be authenticated in a few different ways, but all options are underpinned by SSL/TLS encryption for security.
Create your API credentials within the eTXT web portal – Configuration, API Settings Page. Ensure to create ‘Legacy API credentials’
Username and Password via HTTP Basic Auth
It is also possible to authenticate your user using HTTP Basic Auth.
curl --user your-user-name:your-password https://www.etxtservice.co.nz/api/3/sms/out --data "to=6427000001" --data "body=hi"
Username and Password in HTTP POST request
curl https://www.etxtservice.co.nz/api/3/sms/out --data "userId=youruser-name" --data "password=your-password" --data "to=6427000001" --data "body=hi"
Sending Messages
Use secure HTTPS GET or POST (recommended) to send messages to https://www.etxtservice.co.nz/api/3/sms/out
Simple API Example
Here’s a simple GET example:
https://www.etxtservice.co.nz/api/3/sms/out?userId=yourId&password=yourPassword&to=64222222221&body=hello%20world
Don’t forget to use your password and an international-format number for the recipient, in the “to” parameter.
The complete list of URL encoded parameters for sending messages are:
Handling a Response
eTXT will respond to each and every HTTP request with one of the following result codes, and an XML response in the body.
Important
It is important to note that the API may return a 200 Success result but still fail due to invalid contact name or possibly insufficient funds. You should get into the habit of checking the response XML for any issues in particular if sending to multiple recipients.
The body of the response is an XML structure that provides more information about the send attempt.
The following XML response example indicates a fundamental problem with the request which resulted in no messages being sent. In this case due to an authentication problem:
<?xml version="1.0" ?>
<outbound-message-delivery messageId="FebPromo" isError="true" errorCode="401" errorMessage="Unauthorised">
</outbound-message-delivery>
The following response indicates that processing was at least partially successful. The "salestem" error is likely due to a typo in the request, which should've been "salesteam".
<?xml version="1.0"?>
<outbound-message-delivery messageId="FebPromo" isError="false">
<recipient msisdn="64211111111" isError="false"/>
<recipient msisdn="64211111112" isError="false"/>
<recipient msisdn="64222222221" isError="true" errorCode="403" errorMessage="Cannot deliver to 64222222221 (Number in Blocked List)"/>
<recipient msisdn="salestem" isError="true" errorCode="403" errorMessage="Cannot deliver to salestem (Contact not in Address Book)"/>
</outbound-message-delivery>
Receiving Status via Polling
Clients can GET incoming receipts (status updates) from https://www.etxtservice.co.nz/api/1/sms/status
Clients can be advised of incoming receipts (status updates) via HTTPS GET or POST (recommended) calls https://etxtservice.co.nz/api/1/sms/status
Simple API Example
Here’s a simple GET example:
https://www.etxtservice.co.nz/api/1/sms/status?userId=yourId&password=yourPassword
Don’t forget to use your API username and password
There are just two URL encoded parameters for polling messages:
eTXT will respond to each and every HTTP request with one of the following result codes:
Polling Delays
Please note that polling will wait for 30 seconds if there are no unread messages in the hope a new message arrives during that period. This is expected behaviour
Polling will only transmit unread messages within the eTXT platform and mark them as read once transmitted. Remember this when testing.
For 200 codes (success) eTXT will include a form encoded parameter list containing some or all of message information as described below.
Note: The order of the parameters may change so use value/pair matching rather than location mapping.
Receiving Incoming Messages via Polling
You may obtain information about Messages and Statuses via our Polling API. Polling is 'firewall friendly' and often easier to implement (especially if you are working outside an HTTP server), but for the best experience we recommend Callbacks.
Use secure HTTPS GET or POST (recommended) to receive messages via https://www.etxtservice.co.nz/api/1/sms/in
Simple API Example
Here’s a simple GET example:
https://www.etxtservice.co.nz/api/1/sms/in?userId=yourId&password=yourPassword
Don’t forget to use your API username and password
All messages appear in this api – including those that have been notified via callbacks. Each call to this API returns a single unread message and then marks it as read
There are just two URL encoded parameters for polling messages:
eTXT will respond to each and every HTTP request with one of the following result codes:
Polling Delays
Please note that polling will wait for 30 seconds if there are no unread messages in the hope a new message arrives during that period. This is expected behaviour
Polling will only transmit unread messages within the eTXT platform and mark them as read once transmitted. Remember this when testing.
For 200 codes (success) eTXT will include a form encoded parameter list containing some or all of message information as described below.
Note: The order of the parameters may change so use value/pair matching rather than location mapping.
Example GET Request
Substitute your correct eTXT Credentials in this example and if you have any unread incoming messages available then you will download one of them if you access the URL in a browser.
https://www.etxtservice.co.nz/api/1/sms/in?userId=yourUserID&password=yourPassword
Example Mobile Initiated Message Content
This shows the content of the request when the messages is not a reply but is an 'MO messages' message (ie: initiated by the handset).
Note: the to
value is included in the content while the inReplyToId
is not included.
body=Play+the+eagles+long+run&contentType=text%2Fplain&from=6149123456&messageId=3685355&to=4040&messageDate=2017-05-16T01%3A23%3A04.417Z
Example Content for Reply Messages
This shows the content of the request when the messages is a reply to one you sent previously.
Note: the inReplyToId
which will map to the messageId
you set in your original outbound message.
body=I+am+running+late+sorry&contentType=text%2Fplain&from=6421702659&inReplyToId=66071687&messageId=3685355
This is the same message when you do not set the messageId
you set in your original outbound message.
body=I+am+running+late+sorry&contentType=text%2Fplain&from=6421702659&inReplyToId=default&messageId=3685355
Recent Message RSS Feed
You may wish to view your recent messages in an RSS Reader, or your own custom application.
Use secure HTTPS GET or POST to view such messages via https://www.etxtservice.co.nz/api/2/sms/list
in either RSS or ATOM format.
API Feed Parameters
Recognised URL encoded parameters for retrieving messages are:
Your application should parse the resulting XML feed and display or manipulate your recent messages.
Details of your account including account balance, type and currency is included in the feed results. This will allow you to monitor your account status and initiate a payment before your service is restricted.
Feed Example
https://www.etxtservice.co.nz/api/2/sms/list?userId=yourUsername&password=yourPassword&format=ATOM&type=reply&size=20
Using Callbacks in the API
The API allows Callback URLs to be defined individually when each message is sent, which is useful if you don't wish to use a Company default.
These are defined by API parameters callbackUrl and callbackStatusUrl
When defining these URLs they must be URL encoded prior to inclusion in the request. Here's a walkthrough describing how to define a "mailto:" URL:
Step 1: URL Encode your mailto parameters (if used) Replace the newlines (\n below) with %0A and spaces with %20. Any other characters should also be encoded
Subject=Message: {!messageId}&Body={!body}\n\n-- \nIn Reply to {!messageId}\n\n
to get the encoded string below
Subject=Message:%20{!messageId}&Body={!body}%0A%0A--%20%0AIn%20Reply%20to%20{!messageId}%0A%0A
Step 2: Concatenate the mailto string together as below
mailto:notifier@example.com?Subject=Message:%20{!messageId}&Body={!body}%0A%0A--%20%0AIn%20Reply%20to%20{!messageId}%0A%0A
Step 3: Finally URL Encode the entire string, for use as the "callbackUrl" parameter
mailto%3Anotifier@example.com%3FSubject%3DMessage%3A%2520%7B%21messageId%7D%26Body%3D%7B%21body%7D%250A%250A--%2520%250AIn%2520Reply%2520to%2520%7B%21messageId%7D%250A%250A
Note: This does result in 'double' encoding of the mailto parameters if used. This is correct and required.
Given the URL shown in the above example, if the original SMS was "Sign up for our competition", with a messageId of "FebPromo", and the recipient replied with "Yes Please", the email body delivered would be:
Yes Please
– In Reply to FebPromo
Sign up for our competition