HTTP/S API v2.04 Jul 2024

API Introduction

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

Key facts:

  1. Uses minimal authentication (a simple in-body Sender and Token).
  2. Supports POST (form data) and GET (URL query parameters).
  3. Great for integrating into simple HTTP POST tools where a full REST API is cumbersome.
  4. Supports SMS only.
  5. Lacks features offered by our REST API.

Authentication

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. Log in 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

Send SMS/TXT via HTTP

Choose one request method:

The request parameter reference lists the required and optional fields.

POST Parameters in the request body

Set the request method to POST. Send the form fields below in the HTTP request body.

Request setup

API URL
https://api.tnz.co.nz/api/v2.04/HttpApi/SMS
HTTP Method
POST
HTTP Header
Content-Type: application/x-www-form-urlencoded
Query Parameters
Empty
Request Body ⓘ
Form containing Sender, Token, Number, Message

POST code samples

Replace the example values with your own before running a sample.

cURL
curl 'https://api.tnz.co.nz/api/v2.04/HttpApi/SMS' \
  --data-urlencode 'Sender=youruser@yourdomain.com' \
  --data-urlencode 'Token=YourToken' \
  --data-urlencode 'Number=0210220330' \
  --data-urlencode 'Message=Your SMS Message'
PHP
<?php
// Delivery of Message to Send to SMS HTTPS API
$post_vars = array();
$post_vars[] = "Sender=".urlencode("youruser@yourdomain.com");
$post_vars[] = "Token=".urlencode("YourToken");
$post_vars[] = "Number=".urlencode("TheMobileRecipient");
$post_vars[] = "Message=".urlencode("Your SMS Message");
$post_vars[] = "MessageID=".urlencode("YourInternalMessageID");

$url = "https://api.tnz.co.nz/api/v2.04/HttpApi/SMS";
$request = implode('&',$post_vars);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT,30);

if( !$postResult = curl_exec($ch) )
{
    $result = "Error - Could not connect to {$url}";

    curl_close($ch);
}
else
{
    if (curl_errno($ch))
    {
        curl_close($ch);

        $result = "Error - No response back from {$url}";
    }
    else
    {
        $result = $postResult;

        curl_close($ch);
    }
}

echo $result;
?>

Download the original PHP example

C#
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        //
        // Delivery of Message to Send to SMS HTTPS API (.Net 6 version)
        //

        var postVars = new List<string>();
        postVars.Add("Sender=" + Uri.EscapeDataString("youruser@yourdomain.com"));
        postVars.Add("Token=" + Uri.EscapeDataString("YourToken"));
        postVars.Add("Number=" + Uri.EscapeDataString("TheMobileRecipient"));
        postVars.Add("Message=" + Uri.EscapeDataString("Your SMS Message"));
        postVars.Add("MessageID=" + Uri.EscapeDataString("YourInternalMessageID"));

        var url = "https://api.tnz.co.nz/api/v2.04/HttpApi/SMS";
        var request = string.Join("&", postVars);

        using (var client = new HttpClient())
        {
            var content = new StringContent(request, Encoding.UTF8, "application/x-www-form-urlencoded");
            var response = await client.PostAsync(url, content);
            response.EnsureSuccessStatusCode();
            var responseContent = await response.Content.ReadAsStringAsync();
            Console.WriteLine(responseContent);
        }
    }
}

Download the original C# example

GET Parameters in the URL

Request setup

API URL
https://api.tnz.co.nz/api/v2.04/HttpApi/SMS
HTTP Method
GET
HTTP Header
Empty (Auth is in the Query Parameters)
Query Parameters ⓘ
Sender, Token, Number, Message
Request Body
Empty

Example GET request 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.

Because the query parameters form part of the URL, their values must be URL-encoded. Bold text shows parameter names. Yellow text shows example values: %40 represents @, %20 represents a space and %2C represents a comma.

Responses for POST and GET

SUCCESS Response

HTTP: 200 OK

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

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

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.

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.

Request parameters for POST and GET

Use these field names when building your POST form body or GET query string.

Parameter Example Value Description
Sender Required application@domain.com Sender value set up in Create a new API user token
Token Required ta8wr7ymd Token value set up in Create a new API user token
Number Required 021000001 Destination mobile number in dialling format (02, 0064, +64)
Message Required Hello, this is a test message from Department01. Thank you. Plain or UTF-8 formatted SMS message
MessageID Optional ID123456 A message tracking identifier (maximum 40 characters, alphanumeric)
SMSEmailReply Optional person.one@domain.com For email (SMTP) reply receipt notifications

Status Reporting

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

Frequently Asked Questions

Can messages be sent internationally?

Yes, full international delivery is supported.

Is there a maximum request size?

The maximum request size supported is 20MB. This is our server side limitation. Your client side limitation may be smaller.

When I send SMS messages, the text is cut off at 160 characters. Why?

SMS messages are sent and charged in blocks of characters. One text message is 160 characters. By default, we will limit your message to three-message-parts in length (459 characters using the GSM character set, or 210 characters using Unicode/UCS-2). This can be increased on request. See the SMS Message Parts and Concatenated SMS guide for further information.

In addition to the Delivery Report methods listed above, am I able to receive a daily or monthly summary?

Yes, we can provide a daily or monthly email report (as an attached CSV file) containing data on messages sent. This can be used for billing (contains costs) or for reporting (doesn’t contain costs).

Is HTTPS, SSL, or TLS supported?

Yes, encrypted submissions are accepted across the API via HTTPS. SSL/TLS is also supported for outbound email messages provided the receiving email server supports this.