This API is designed to be an ultra simple HTTP integration specifically for SMS.

Register your account

Head to https://www.tnz.co.nz/Customer/SignUp/ to create a new account.

A test account is possible, however creating a commercial account and using the Mode=Test function of the API is simpler to use when you’re ready to push your application live.

After completing the sign up form, a sales consultant will manually activate your account. This may take one business day. Once the account has been activated, you will be able to Create a new API user token.

Create a new API user token

Using the API will require a Sender and Token pair to authenticate with the API.

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 'Sender/APIKey' and create a new APIKey
7. Click the ' Copy' button to copy the API Key to your clipboard
8. Paste the Sender and APIKey into the relevant section in your application or code

Sender = Sender
APIKey = Token

Understanding the API basics

When submitting a message via HTTP, the server will respond:
  200 OK, OK Thanks
  400 BAD REQUEST, %ERROR REASON%
  500 Internal Server Error

Once the message delivery completes, a status report can be dispatched to your software. Reply messages can also be captured.

Send SMS/TXT via HTTP

"POST" Request:

API URL:        https://api.tnz.co.nz/api/v2.04/HttpApi/SMS

HTTP Method:    POST

HTTP Headers:    Content-Type="application/x-www-form-urlencoded"

HTTP Form:


    

        
Sender
        
application@domain.com
    
    

        
Token
        
ta8wr7ymd
    
    

        
Number
        
021000001
    
    

        
Message
        
Hello, this is a test message from Department01. Thank you.
    

												

Resources:

• Sample: php example
• Sample: C# example

"GET" Request:

API URL:        https://api.tnz.co.nz/api/v2.04/HttpApi/SMS?Sender=application%40domain.com&Token=ta8wr7ymd&Number=021000001&Message=Hello%2C%20this%20is%20a%20test%20message%20from%20Department01.%20Thank%20you.

HTTP Method:    GET

HTTP Headers:    ""

HTTP Body:    ""

Response:

SUCCESS Response

HTTP: 200 OK

{
    "Result": "Success",
    "MessageID": "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE"
}
													

Note:
The API will respond with a Message ID in JSON format. The Message ID is used for tracking delivery reports and replies through the API and Dashboard.

A "Success" response indicates that the API has accepted your parameters, not that the message has been delivered.

FAILED Response

HTTP: 401 Unauthorized

{
    "Result": "Failed",
    "ErrorMessage": "Missing or empty sender"
}
													

Note:
"Missing or empty sender" may mean your 'Sender' parameter is not specified, or it may mean the API cannot read your parameters (your request body is malformed or using the incorrect form type).

For a list of error messages, see TNZ API Errors.

Required parameters

Parameter		Example Value	Description
Sender		application@domain.com	Sender value set up in Create a new API user token
Token		ta8wr7ymd	Token value set up in Create a new API user token
Number		021000001	Destination mobile number in dialling format (02, 0064, +64)
Message		Hello, this is a test message from Department01. Thank you.	Plain or UTF-8 formatted SMS message

Optional parameters

Parameter		Example Value	Description
MessageID		ID123456	A message tracking identifier (maximum 40 characters, alphanumeric)
SMSEmailReply		person.one@domain.com	For email (SMTP) reply receipt notifications

Resending and retrying messages

To resend or retry sending a message via the REST API, this will need to be submitted as a new, unique message.
To resend or retry sending a message via the Web Dashboard, once logged in and viewing an individual message, you will see Resubmit and Forward buttons.

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

To receive Delivery Reports via Webhook, please advise the URL to submit to.
Webhooks are provided as an HTTP POST in either XML or JSON format (your preference).

The Webhook options are described in the REST API guide:

API Name	Description
SMS Status Webhook	Hook containing the delivery status of an outbound message (tracked using the MessageID)
SMS Received Webhook	Hook containing a new received SMS message (tracked using the MessageID if it's a reply SMS)

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, as well as capture any SMS replies received.

The GET Poll options are described in the REST API guide:

API Name	Description
GET Status Poll	Poll for the delivery status of an outbound message (tracked using the MessageID)
GET Inbound SMS Poll	Poll for a list of all SMS received in a given time-frame
GET Received Poll	Poll for replies to a specific outbound SMS message (tracked using the MessageID)