Use just one API to send Email, SMS, Fax and Voice Calls -

Register your account

If you don't have an account, head to https://www.tnz.co.nz/Customer/SignUp/ and register.

Create an API user

To access the API, you'll need a User with API access:

1. Log into the TNZ Dashboard
2. Select Users from the menu, then click Create to create a new user, or select an existing user from the list.
3. Under the API Options tab, if API access isn't set up, toggle Enable API, then create an "API Key" (you can click the Generate button to auto-create one), then click Update to save your changes.
4. Under the API Options tab, next to "Auth Token" click Copy button. This will copy your Auth Token to your clipboard.

The API v2.03 uses JWT token Authentication. Contact your TNZ Representative for OAuth2 authentication.

You can use one Auth Token for multiple use-cases, using the SubAccount and Department values to track reporting and billing.

Understanding the API basics

This flexible API allows you to send multiple message types. For a brief overview of the API, see the TNZ API Structure guide.

The API URL:

https://api.tnz.co.nz/api/[Version]/[Action]/[MessageType]

• [Version] is the API Version ('v2.03')
• [Action] defines the module ('send' a message or 'get' a status)
• [MessageType] is the type of message ('email', 'sms', 'fax', etc.)

The API HTTP Headers:

The HTTP Headers define the API call's formatting -

An API Send Example

An example for sending an outbound SMS using Raw JSON -

URL:

- https://api.tnz.co.nz/api/v2.03/send/sms


Headers:

- Content-Type="application/json; encoding='utf-8'"

- Accept="application/json; encoding='utf-8'"

- Authorization="Basic eyJ0eXA....436k0-E4"    



Data:

{
"MessageData" : {
   "Message": "Hello, this is a test.",
   "Destinations" : [ { "Recipient": "+6421000001" } ]
   }
}

Possible HTTP status values are:

• 200 OK - Message Accepted
• 400 BAD REQUEST - Invalid Variables
• 401 Unauthorized - Invalid Auth Token
• 500 Internal Server Error - API Server Fault

An example JSON response value:

• {
  "Result": "%STATUS%",
  "MessageID": "%MESSAGEID%"
}
• Status - 'Success' or 'Failed' refers to your API POST result (explains whether your POST was accepted by our server). This is not your message's delivery result - to track message delivery, see API - Status Reporting.
• MessageID - A message tracking identifier (maximum 40 characters, alphanumeric). If you do not supply this field in your submitted MessageData, the API will return one for you in the response body (UUID v4 of 36 characters).
• Note - The API will verify that required fields are supplied, however it will not validate data. See TNZ API Errors for error descriptions.

API - Send Messages

Find instructions for each Message Type:

API - Edit Messages - Edit a submitted message

Once a message has been sent, you can retry a failed message, reschedule a delayed message, abort a delayed message and edit the NumberOfOperators value on Voice/TTS messages.

API URL:        https://api.tnz.co.nz/api/v2.03/set/resubmit/[MessageID]

HTTP Method:    PATCH

API URL:        https://api.tnz.co.nz/api/v2.03/set/reschedule/[MessageID]

HTTP Method:    PATCH

API URL:        https://api.tnz.co.nz/api/v2.03/set/abort/[MessageID]

HTTP Method:    PATCH

API URL:        https://api.tnz.co.nz/api/v2.03/set/pacing/[MessageID]

HTTP Method:    PATCH

API - Status Reporting - Reporting and event tracking

Delivery Reports advise whether delivery was successful. If not, it will describe why.

Each delivery report type is optional and multiple delivery report types can be used.

Web Dashboard - Tracking message statuses via the online dashboard

You will be supplied with a Web Dashboard login at registration. The Dashboard can be used to set up new sender/token pairs, as well as track sent and replied messages. You can drill into specific messages to view individual events, such as delivery attempts, retries, replies, results, clicks, etc.

SMTP Email - Receive message statuses via email

Delivery reports are emailed as an HTML email for viewing by an end-user. Your sales representative can enable this for you.

Whitelabelling of SMTP Email reports is available.

Webhook - Message statuses delivered via a webhook

To receive Delivery Reports via Webhook, please advise the URL to submit to.

Webhooks are delivered as an HTTP POST in either XML or JSON format (your preference; defined by the WebhookCallbackFormat in your outbound message).

Webhook failures are retried every five minutes for a maximum of 24 hours.

API URL:        https://www.example.com/webhook

HTTP Method:    POST

HTTP Headers:   Content-Type="application/json"

{
  "Sender": "application@domain.com",
  "APIKey": "ta8wr7ymd",
  "Type": "SMS",
  "Destination": "+6421000001",
  "MessageID": "js82hn8n",
  "SubAccount": "SubAccount01",
  "Department": "Department01",
  "JobNumber": "10C7B9A0",
  "SentTime": "16/10/2019 13:43 p.m.",
  "Status": "SUCCESS",
  "Result": "delivered",
  "Price": "0.10",
  "Detail": "SMSParts:1",
  "URL": "https://www.example.com/webhook",
  "RESPONSEMODE": "JSON"
}          
Copy code

API URL:        https://www.example.com/webhook

HTTP Method:    POST

HTTP Headers:   Content-Type="text/xml"

<?xml version='1.0' encoding='UTF-8'?>
<root>
  <Sender>application@domain.com</Sender>
  <APIKey>ta8wr7ymd</APIKey>
  <Type>SMS</Type>
  <Destination>+6421000001</Destination>
  <MessageID>js82hn8n</MessageID>
  <SubAccount>SubAccount01</SubAccount>
  <Department>Department01</Department>
  <JobNumber>10C7B9A0</JobNumber>
  <SentTime>2019-10-16 14:52 p.m.</SentTime>
  <Status>SUCCESS</Status>
  <Result>delivered</Result>
  <Price>0.10</Price>
  <Detail>SMSParts:1</Detail>
  <URL>https://www.example.com/webhook</URL>
  <RESPONSEMODE>XML</RESPONSEMODE>
</root>          
Copy code

GET Status Poll - Track message statuses using a GET poll

API users are able to poll for the status of a message via the GET Status API.

The GET Poll should be configured to timeout after 48 hours with no result.

API URL:        https://api.tnz.co.nz/api/v2.03/get/status/[MessageID]

HTTP Method:    GET

API - Receive Messages - Track messages received

Currently, tracking SMS Received is supported.

Tracking of faxes and voicemail received is scheduled for a future release. Let your account manager know if this interests you.

Web Dashboard - Tracking messages received via the online dashboard

You will be supplied with a Web Dashboard login at registration. The Dashboard can be used to set up new sender/token pairs, as well as track sent and replied messages. You can drill into specific messages to view individual events, such as delivery attempts, retries, replies, results, clicks, etc.

SMTP Email - Track messages received via email

Reply message reports are emailed as an HTML email for viewing by an end-user.
Whitelabelling of SMTP Email reports is available.

When submitting SMS messages, specify the SMSEmailReply parameter.

Webhook - Messages received data delivered via a webhook

If you are set up to receive Status webhooks, you will also be receiving SMS Received webhooks.

To receive SMS replies via Webhook, please advise the URL to submit to.

Webhooks are delivered as an HTTP POST in either XML or JSON format (your preference; defined by the WebhookCallbackFormat in your outbound message).

Webhook failures are retried every five minutes for a maximum of 24 hours.

The mobile has 7 days to reply to a message. Any replies received after the 7 day window will be treated as a new message.

API URL:        https://www.example.com/webhook

HTTP Method:    POST

HTTP Headers:   Content-Type="application/json"

{
  "Sender": "application@domain.com",
  "APIKey": "ta8wr7ymd",
  "Type": "SMSReply",
  "Destination": "+6421000001",
  "MessageID": "js82hn8n",
  "SubAccount": "SubAccount01",
  "Department": "Department01",
  "JobNumber": "10C7B9A0",
  "SentTime": "2019-10-16 13:43:00",
  "Status": "RECEIVED",
  "Result": "RECEIVED",
  "Message": "This is a reply.",
  "Price": "",
  "Detail": "",
  "URL": "https://www.example.com/webhook",
  "RESPONSEMODE": "JSON"
}          
Copy code

API URL:        https://www.example.com/webhook

HTTP Method:    POST

HTTP Headers:   Content-Type="text/xml"

<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <Sender>application@domain.com</Sender>
  <APIKey>ta8wr7ymd</APIKey>
  <Type>SMSReply</Type>
  <Destination>+6421000001</Destination>
  <MessageID>js82hn8n</MessageID>
  <SubAccount>SubAccount01</SubAccount>
  <Department>Department01</Department>
  <JobNumber>10C7B9A0</JobNumber>
  <SentTime>2019-10-16 13:43</SentTime>
  <Status>RECEIVED</Status>
  <Result>RECEIVED</Result>
  <Message>This is a reply.</Message>
  <Price></Price>
  <Detail></Detail>
  <URL>https://www.example.com/webhook</URL>
  <RESPONSEMODE>XML</RESPONSEMODE>
</root>          
Copy code

GET SMS Received Poll - View all Inbound SMS using a GET poll

API users are able to poll for all received SMS messages in a given time-frame.

API URL:        https://api.tnz.co.nz/api/v2.03/get/sms/received?timePeriod=[minutes]

URL Parameters: timePeriod=[minuts] //optional
                dateFrom=[From Date] //optional
                dateTo=[To Date] //optional
                page=[Page Number] //optional
                recordsPerPage=[No. of Records Per Page] //optional

HTTP Method:    GET