Using a single NodeJS library, NodeJS developers can send Email, SMS, Fax, Voice and Text-to-Speech messages using their own software.

Register your account

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

Create an API user

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

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 NodeJS Library basics

Save hundreds of lines of code and hours of time by add the TNZ NodeJS library into your project. Using one package and simple code tweaks, your software can send Email, SMS, Fax, Voice and Text-to-Speech messages.

For a brief overview of the API, see the TNZ API Structure guide.

Download the Library:

Download and install the 'tnzapi' using npm: npm i tnzapi

TNZAPI npm Package

Alternatively you can download source code from GitHub

Reference the Library:

Reference the library in your code: const tnzapi = require('tnzapi');

Send Messages using the Library:

Using the [request].SendMessage(callback_function); function, the package will connect to TNZ's REST API (in JSON format) and send messages.

Capture Status & Replies using the Library:

Message Status and Received Messages can be captured using a Webhook (a POST to your nominated URL), or can be Polled for using the Library's [request].Poll(callback_function); function.

See Status Reporting and Receive Messages.

Send Messages - build your application with the NodeJS Library

Find instructions for each Message Type:

Sending messages in test mode

Under request object you can specify an additional Mode=Test parameter.

Mode=Test means any messages will be handled by the API, instantly called a SUCCESS and the success report will be delivered to you. This is a useful way to end-to-end test without sending a live message.

# Test mode
request.Mode = "Test"
                                              

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.

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Actions.Resubmit.SendRequest({
    MessageID: "ID123456",                   // MessageID generated from system OR your message ID if specified
}).then(callback);                                          
Copy code

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Actions.Resubmit.SendRequest({
    MessageID: "ID123456",                   // MessageID generated from system OR your message ID if specified
    SendTime: "2023-09-01T12:30"
}).then(callback);                                          
Copy code

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Actions.Reschedule.SendRequest({
    MessageID: "ID123456",                  // MessageID generated from system OR your message ID if specified
    SendTime: "2023-09-01T00:00"            // New Date/Time
}).then(callback);                                          
Copy code

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Actions.Reschedule.SendRequest({
    MessageID: "ID123456",                  // MessageID generated from system OR your message ID if specified
    SendTime: "2023-09-01T00:00"            // New Date/Time
}).then(callback);
                                          
Copy code

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Actions.Abort.SendRequest({
    MessageID: "ID123456"                     // MessageID generated from system OR your message ID if specified
}).then(callback);
                                          
Copy code

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Actions.Abort.SendRequest({
    MessageID: "ID123456"                     // MessageID generated from system OR your message ID if specified
}).then(callback);
                                          
Copy code

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Actions.Pacing.SendRequest({
    MessageID: "ID123456",                    // MessageID generated from system OR your message ID if specified
    NumberOfOperators: 1                      // No of operators
}).then(callback);                                          
Copy code

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Actions.Pacing.SendRequest({
    MessageID: "ID123456",                    // MessageID generated from system OR your message ID if specified
    NumberOfOperators: 1                      // No of operators
}).then(callback);                                          
Copy code

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.

The email address to receive SMS Reply reports can be specified on the original message submission using the SMSEmailReply parameter.

Webhook - Message statuses delivered via a webhook

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

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).
Webhook failures are retried every five minutes for a maximum of 24 hours.

Supplied parameters are:

GET Status Poll - Track message statuses using a GET poll

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

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

Reference : TNZAPI.Messaging.Get

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Reports.Status.Poll({
    MessageID: "ID123456",                    // MessageID generated from system OR your message ID if specified
}).then(callback);
                                          
Copy code

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Reports.Status.Poll({
    MessageID: "ID123456",                    // MessageID generated from system OR your message ID if specified
    RecordsPerPage: 10,                       // x number of records
    Page: 1                                   // Current location
}).then(callback);
                                          
Copy code

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

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.

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).
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.

Supplied parameters are:

GET SMS Received Poll - Track SMS Received using a GET poll

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

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

Reference : TNZAPI.Messaging.Get

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Reports.SMSReceived.Poll({
    TimePeriod: 1440                          // Return results from the last x minutes
    RecordsPerPage: 10,
    Page: 1
}).then(callback);                                          
Copy code

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Reports.SMSReceived.Poll({
    DateFrom: "2023-06-01T00:00:00",          // Return results from the date/time
    DateTo: "2023-06-30T23:59:59",            // Return results to the date/time
    RecordsPerPage: 10,                       // x numbers of records to return per request
    Page: 1                                   // current location
}).then(callback);                                          
Copy code

GET SMS Reply Poll - Track SMS replies using a GET poll

You are able to poll for replies to a specific SMS message, tracked using the MessageID on the outbound message.

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

Reference : TNZAPI.Messaging.Get

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

request.Poll(callback);

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Reports.SMSReply.Poll({
    MessageID: "ID123456",                    // MessageID generated from system OR your message ID if specified
    Page: 1                                   // Current location
}).then(callback);                                          
Copy code

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Reports.SMSReply.Poll({
    MessageID: "ID123456",                    // MessageID generated from system OR your message ID if specified
    RecordsPerPage: 10,                       // x number of records per page
    Page: 1                                   // Current location
}).then(callback);
                                          
Copy code

As new versions of the APIs are released, this API reference guide will be updated to reflect the latest version and features supported:
API Version ChangeLog