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 & Export Your API Auth Token

To use the API, an Auth Token is required in the Authorization HTTP header.

To export your Auth Token:

1. Login to the TNZ Dashboard
2. Navigate to 'Users'
3. Create a new user or select an existing one
4. Enable API access (if it's not already enabled)
5. Click on the 'API' tab
6. Enable 'Auth Token' and create a new Auth Token
7. Click the ' Copy' button to copy it to your clipboard
8. Paste the Auth Token into the Authorization Header in your application or code

At any time, you can refresh your Auth Token by clicking the button and exporting your new Auth Token. This action will invalidate any apps using your old Auth Token.

Auth Tokens can be used for multiple use-cases, with SubAccount and Department values helping in tracking reporting and billing.

API v2.04 utilizes JWT token Authentication. For OAuth2 authentication options, contact your TNZ representative.

Understanding the API basics

This 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]

https://api.tnz.co.nz/api/v2.04/send/sms

• [Version] is the API Version ('v2.04')
• [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 -

You can find your Auth Token in the TNZ Dashboard.

An API Send Example

An example for sending an outbound SMS using Raw JSON -

URL: https://api.tnz.co.nz/api/v2.04/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": "Success",
  "MessageID": "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD""
}
• Status - 'Success' or 'Failed' indicates the outcome of your API POST (accepted or rejected by our server), not the delivery status of your message. For delivery tracking, refer to 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, 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.04/set/resubmit/[MessageID]

HTTP Method:    PATCH

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

HTTP Method:    PATCH

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

HTTP Method:    PATCH

API URL:        https://api.tnz.co.nz/api/v2.04/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"
                X-Timestamp="2024-05-01T03:51:42.000Z"
                X-Sender="application@domain.com"
                Authorization="ta8wr7ymd"

{
  "Version": "2.04",
  "Sender": "application@domain.com",
  "APIKey": "ta8wr7ymd",
  "Type": "SMS",
  "Destination": "+6421000001",
  "ContactID": "7000000a-f002-4007-b00a-d00000000001",
  "ReceivedID": "",
  "MessageID": "1000000a-f002-4007-b00a-d00000000002",
  "SubAccount": "SubAccount01",
  "Department": "Department01",
  "JobNumber": "10C7B9A0",
  "SentTimeLocal": "2024-05-01 15:51:42",
  "SentTimeUTC": "2024-05-01 03:51:42",
  "SentTimeUTC_RFC3339": "2024-05-01T03:51:42.000Z",  
  "Status": "SUCCESS",
  "Result": "delivered",
  "Message": "",
  "Price": "0.10",
  "Detail": "SMSParts:1",
  "URL": "https://www.example.com/webhook"
}          
Copy code

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

HTTP Method:    POST

HTTP Headers:   Content-Type="text/xml"
                X-Timestamp="2024-05-01T03:51:42.000Z"
                X-Sender="application@domain.com"
                Authorization="ta8wr7ymd"

<?xml version='1.0' encoding='UTF-8'?>
<root>
  <Version>2.04</Version>
  <Sender>application@domain.com</Sender>
  <APIKey>ta8wr7ymd</APIKey>
  <Type>SMS</Type>
  <Destination>+6421000001</Destination>
  <ContactID>7000000a-f002-4007-b00a-d00000000001</ContactID>
  <ReceivedID></ReceivedID>
  <MessageID>1000000a-f002-4007-b00a-d00000000002</MessageID>
  <SubAccount>SubAccount01</SubAccount>
  <Department>Department01</Department>
  <JobNumber>10C7B9A0</JobNumber>
  <SentTimeLocal>2024-05-01 15:51:42</SentTimeLocal>
  <SentTimeUTC>2024-05-01 03:51:42</SentTimeUTC>
  <SentTimeUTC_RFC3339>2024-05-01T03:51:42.000Z</SentTimeUTC_RFC3339>
  <Status>SUCCESS</Status>
  <Result>delivered</Result>
  <Message></Message>
  <Price>0.10</Price>
  <Detail>SMSParts:1</Detail>
  <URL>https://www.example.com/webhook</URL>
</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.04/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"
                X-Timestamp="2024-05-01T03:51:42.000Z"
                X-Sender="application@domain.com"
                Authorization="ta8wr7ymd"

{
  "Version": "2.04",
  "Sender": "application@domain.com",
  "APIKey": "ta8wr7ymd",
  "Type": "SMSReply",
  "Destination": "+6421000001",
  "ContactID": "7000000a-f002-4007-b00a-d00000000001",
  "ReceivedID": "5000000a-f002-4007-b00a-d00000000001",
  "MessageID": "1000000a-f002-4007-b00a-d00000000002",
  "SubAccount": "SubAccount01",
  "Department": "Department01",
  "JobNumber": "10C7B9A0",
  "SentTimeLocal": "2024-05-01 15:51:42",
  "SentTimeUTC": "2024-05-01 03:51:42",
  "SentTimeUTC_RFC3339": "2024-05-01T03:51:42.000Z",  
  "Status": "RECEIVED",
  "Result": "RECEIVED",
  "Message": "This is a reply.",
  "Price": "",
  "Detail": "InputToNumber:021-000 001",
  "URL": "https://www.example.com/webhook"
}          
Copy code

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

HTTP Method:    POST

HTTP Headers:   Content-Type="application/json"
                X-Timestamp="2024-05-01T03:51:42.000Z"
                X-Sender="application@domain.com"
                Authorization="ta8wr7ymd"

{
  "Version": "2.04",
  "Sender": "application@domain.com",
  "APIKey": "ta8wr7ymd",
  "Type": "SMSReply",
  "Destination": "+6421000001",
  "ContactID": "7000000a-f002-4007-b00a-d00000000001",
  "ReceivedID": "5000000a-f002-4007-b00a-d00000000001",
  "MessageID": "1000000a-f002-4007-b00a-d00000000002",
  "SubAccount": "SubAccount01",
  "Department": "Department01",
  "JobNumber": "10C7B9A0",
  "SentTimeLocal": "2024-05-01 15:51:42",
  "SentTimeUTC": "2024-05-01 03:51:42",
  "SentTimeUTC_RFC3339": "2024-05-01T03:51:42.000Z",  
  "Status": "RECEIVED",
  "Result": "RECEIVED",
  "Message": "This is a reply.",
  "Price": "",
  "Detail": "InputToNumber:021-000 001",
  "URL": "https://www.example.com/webhook"
}          
Copy code

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

HTTP Method:    POST

HTTP Headers:   Content-Type="text/xml"
                X-Timestamp="2024-05-01T03:51:42.000Z"
                X-Sender="application@domain.com"
                Authorization="ta8wr7ymd"

<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <Version>2.04@domain.com</Version>
  <Sender>application@domain.com</Sender>
  <APIKey>ta8wr7ymd</APIKey>
  <Type>SMSReply</Type>
  <Destination>+6421000001</Destination>
  <ContactID>7000000a-f002-4007-b00a-d00000000001</ContactID>
  <ReceivedID>5000000a-f002-4007-b00a-d00000000001</ReceivedID>
  <MessageID>1000000a-f002-4007-b00a-d00000000002</MessageID>
  <SubAccount>SubAccount01</SubAccount>
  <Department>Department01</Department>
  <JobNumber>10C7B9A0</JobNumber>
  <SentTimeLocal>2024-05-01 15:51:42</SentTimeLocal>
  <SentTimeUTC>2024-05-01 03:51:42</SentTimeUTC>
  <SentTimeUTC_RFC3339>2024-05-01T03:51:42.000Z</SentTimeUTC_RFC3339>
  <Status>RECEIVED</Status>
  <Result>RECEIVED</Result>
  <Message>This is a reply.</Message>
  <Price></Price>
  <Detail>InputToNumber:021-000 001</Detail>
  <URL>https://www.example.com/webhook</URL>
</root>          
Copy code

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

HTTP Method:    POST

HTTP Headers:   Content-Type="text/xml"
                X-Timestamp="2024-05-01T03:51:42.000Z"
                X-Sender="application@domain.com"
                Authorization="ta8wr7ymd"

<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <Version>2.04@domain.com</Version>
  <Sender>application@domain.com</Sender>
  <APIKey>ta8wr7ymd</APIKey>
  <Type>SMSReply</Type>
  <Destination>+6421000001</Destination>
  <ContactID>7000000a-f002-4007-b00a-d00000000001</ContactID>
  <ReceivedID>5000000a-f002-4007-b00a-d00000000001</ReceivedID>
  <MessageID>1000000a-f002-4007-b00a-d00000000002</MessageID>
  <SubAccount>SubAccount01</SubAccount>
  <Department>Department01</Department>
  <JobNumber>10C7B9A0</JobNumber>
  <SentTimeLocal>2024-05-01 15:51:42</SentTimeLocal>
  <SentTimeUTC>2024-05-01 03:51:42</SentTimeUTC>
  <SentTimeUTC_RFC3339>2024-05-01T03:51:42.000Z</SentTimeUTC_RFC3339>
  <Status>RECEIVED</Status>
  <Result>RECEIVED</Result>
  <Message>This is a reply.</Message>
  <Price></Price>
  <Detail>InputToNumber:021-000 001</Detail>
  <URL>https://www.example.com/webhook</URL>
</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.04/get/sms/received?timePeriod=[minutes]

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

HTTP Method:    GET