Last updated: September 20th 2021

API Introduction

Using a single DLL library, VBA developers can send Email, SMS and Text-to-Speech messages using MS Office and other Windows based applications. The examples included in this guide uses Microsoft Excel as the reference.

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

You'll need a Sender and APIKey to authenticate with the Library/API.

You can request this from your TNZ Representative or if you have a Dashboard login you can generate one under: Users | Outbound Users | Create

You can use one Sender/APIKey for multiple use-cases - the SubAccount and Department values can be specified for rebilling.


Understanding the basics

Save hundreds of lines of code and hours of time by dropping the .NET DLL into your project. Using one DLL and simple code tweaks, your software can send Email, SMS and Text-to-Speech messages.

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


Download the Helper DLL:

Download the Helper DLL:   TNZAPI.dll.zip



Install the Helper DLL:

Install the DLL:

  1. Extract the DLL to your local machine (the below references "C:\Program Files\TNZ Group\TNZAPI.dll")

  2. Add a Windows Reference by executing the following command using a Command Prompt (CMD) with Administrator privileges: regasm /codebase /tlb "C:\Program Files\TNZ Group\TNZAPI.dll"

    
C:\Windows\Microsoft.NET\Framework\v4.0.30319>regasm /codebase /tlb "C:\Program Files\TNZ Group\TNZAPI.dll"
Microsoft .NET Framework Assembly Registration Utility version 4.8.3752.0
for Microsoft .NET Framework version 4.8.3752.0
Copyright (C) Microsoft Corporation.  All rights reserved.

Types registered successfully

    *Note: You can ignore the "RA0000" error:
      RegAsm : error RA0000 : An error occurred while saving the exported type library: Access is denied. (Exception from HRESULT: 0x80070005 (E_ACCESSDENIED))


    If you need to unregister the DLL, run the unregister command: regasm /unregister "C:\Program Files\TNZ Group\TNZAPI.dll"



Create your excel file, and reference TNZAPI.dll:

In VBA IDE:

  1. Open [Tools] -> [References] from the top menu



  2. If "TNZAPI DLL" is not on your list, click [Browse...] button and find your dll (C:\Program Files\TNZ Group\TNZAPI.dll)



  3. You are now ready to use the DLL!

Send Messages:

Using the [MessageType].SendMessage() function, the DLL will connect to TNZ's REST API (in XML 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 DLL's GET function.

See Status Reporting and Receive Messages.

Send Messages - build your VBA application with the .NET DLL

Find instructions for each Message Type:

Sending Email - VBA using .NET dll

 

Send Email (Basic):


Private Sub cmdSendEmail_Click()
    Dim res As TNZAPI.MessageResult
    
    Dim message As TNZAPI.Email
    Set message = New TNZAPI.Email
    
    message.Sender = "YOUR_EMAIL_ADDRESS"
    message.APIKey = "YOUR_API_KEY"
    
    message.FromEmail = "from@test.com"
    message.EmailSubject = "Test Email"
    message.MessagePlain = "Test Email Body"
    message.Recipient = "email@test.com"
    
    Set res = message.SendMessage()
    
    If res.MessageID <> "" Then
        MsgBox "Message ID: " & res.MessageID
    Else
        MsgBox "Error: " & res.ErrorMessage
    End If
End Sub                                                
Copy code

Required parameters

Parameter Example Value Description
Sender application@domain.com Sender value set up in Create a new API user token
APIKey ta8wr7ymd APIKey value set up in Create a new API user token
EmailSubject Test Email Sets the email subject
MessagePlain Hello,

This is a test message.

Thank you.		 Content used for the message/plain section of the email (overrides 'Template')
Recipient john.doe@example.com Email address to receive the message (for detailed formatting, see the Destinations parameter below)

Optional parameters

Parameter Example Value Description
MessageID ID12345 Tracking ID or message description. Leave black if you want us to generate one.
Reference Test1 Reference of your message
SendTime new DateTime() Delay sending until the specified date/time (dd/mm/yyyy HH:mm in your local timezone, specified by your Sender setting or overridden using the TimeZone command)
Timezone New Zealand User's local timezone (see Setting Timezones)
SubAccount SubAccount01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
Department Department01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
ChargeCode BillingGroup01 Bespoke app cost allocation code (for invoice segmentation)
SMTPFrom noreply@example.com Sets the email Sender/Return-Path at the SMTP level (this address receives bounce-back emails and is used for SPF/DKIM type authentication; 'FromEmail' is used if not specified)
From noreply Sets the email sender's Friendly Name (seen by the email recipient)
FromEmail noreply@example.com Sets the email sender's Email Address (seen by the email recipient; API 'Sender' is used if not specified)
ReplyTo reply@example.com Sets the email sender's Reply-To Address (if the recipient replies, the Reply To will receive the reply)
MessageHTML <html>Hello,<br /><br />This is a test message.<br /><br />Thank you.</html> Content used for the message/html section of the email (overrides 'Template' and 'MessagePlain')
Recipients > Recipient john.doe@example.com Recipient of the email
> Attention John Doe Recipient's friendly name
> Company Example Corp Recipient's company
> Custom1 Customisable field
> Custom2 Customisable field
Attachments > Name Sample.pdf Attachment's filename
> Data %%Base-64%% Base-64 encoded value of the attached file

Functions

Function Usage Description
AddRecipient() AddRecipient(string recipient)

AddRecipient(Recipient recipient) 		Function to add a single message recipient
AddRecipients() AddRecipients(List<string> recipients)

AddRecipients(List<Recipient> recipients) 		Function to add a list of message recipients
AddAttachment() AddAttachment(string file_location)

AddAttachment(Attachment attachment) 		Function to add a single attachment to the message (the .NET library will grab the file contents from the specified file location)
AddAttachments() AddAttachments(List<string> file_locations)

AddAttachments(List<Attachment> attachments) 		Function to add multiple attachment to the message (the .NET library will grab the file contents from the specified file location)
SetEmailFrom() SetEmailFrom(string from_email)

SetEmailFrom(string from_name, string from_email)

SetEmailFrom(string from_name, string from_email, string reply_to)

SetEmailFrom(string smtp_from, string from_name, string from_email, string reply_to) 		Function to set the SMTP From headers (domains require SPF and other security features enabled - contact your Sales Representative for details)
SendMessage() SendMessage()

SendMessage(string message_text)

SendMessageSendMessage(string message_id, string reference, DateTime send_time, string timezone, string subaccount, string department, string charge_code, string sms_email_reply, string force_gsm_chars, string message_text) 		Function to submit messages to TNZ REST API

Returns MessageResult object

Sending SMS - VBA using .NET dll

 

Send SMS (Basic):


Private Sub cmdSendSMS_Click()
    Dim res As TNZAPI.MessageResult
    
    Dim message As TNZAPI.SMS
    Set message = New TNZAPI.SMS
    
    message.Sender = "YOUR_EMAIL_ADDRESS"
    message.APIKey = "YOUR_API_KEY"
    message.MessageText = "Test SMS"
    message.Recipient = "+64211231234"
    
    Set res = message.SendMessage()
    
    If res.MessageID <> "" Then
        MsgBox "Message ID: " & res.MessageID
    Else
        MsgBox "Error: " & res.ErrorMessage
    End If
End Sub                                                
Copy code

Required parameters

Parameter Example Value Description
Sender application@domain.com Sender value set up in Create a new API user token
APIKey ta8wr7ymd APIKey value set up in Create a new API user token
MessageText Hello, this is a test message from Department01. Thank you. Plain or UTF-8 formatted SMS message
Recipient +6421000002 Mobile number to receive the message (for detailed formatting, see the Destinations parameter below)

Optional parameters

Parameter Example Value Description
MessageID ID12345 Tracking ID or message description. Leave black if you want us to generate one.
Reference Test1 Tracking ID or message description
SendTime new DateTime() Delay sending until the specified date/time (dd/mm/yyyy HH:mm in your local timezone, specified by your Sender setting or overridden using the TimeZone command)
TimeZone New Zealand User's local timezone (see Setting Timezones)
SubAccount SubAccount01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
Department Department01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
ChargeCode BillingGroup01 Bespoke app cost allocation code (for invoice segmentation)
FromNumber +6421000001 Setting SMS origination number, short code(s) will override in New Zealand - Not for New Zealand.
SMSEmailReply person.one@domain.com For email (SMTP) reply receipt notifications
ForceGSMChars true Convert multi-byte characters into normalised GSM character format. ie. © to (C)
Message Hello, view the link at [[Link:https://www.example.com/path/to/page.html]] or view the file at [[File1]] or reply at [[REPLY]] or OptOut at [[STOP]] An example Message that uses the URL Shortener, File Link, Reply Link and Unsubscribe functions
Recipients > MobileNumber +6421000001 Recipient of the SMS in E.164 internationalised format (for localized or friendly formatting, contact your account manager)
> Attention John Doe Recipient's friendly name
> Company Example Corp Recipient's company
> Custom1 Customisable field
> Custom2 Customisable field

Functions

Function Usage Description
AddRecipient() AddRecipient(string recipient)

AddRecipient(Recipient recipient) 		Function to add a single message recipient
AddRecipients() AddRecipients(List<string> recipients)
AddRecipients(List<Recipient> recipients) 		Function to add a list of message recipients
AddAttachment() AddAttachment(string file_location)

AddAttachment(Attachment attachment) 		Function to add a single attachment to the message (the .NET library will grab the file contents from the specified file location)
AddAttachments() AddAttachments(List<string> file_locations)

AddAttachments(List<Attachment> attachments) 		Function to add multiple attachments to the message (the .NET library will grab the file contents from the specified file location)
SendMessage() SendMessage()

SendMessage(string email_subject, string message_plain)

SendMessage(string email_subject, string message_plain, string message_html)

SendMessage(string email_subject, string message_plain, string message_html, string message_id, string reference, DateTime send_time, string timezone, string subaccount, string department, string charge_code)

SendMessage(string email_subject, string message_plain, string message_html, string message_id, string reference, DateTime send_time, string timezone, string subaccount, string department, string charge_code, string smtp_from, string from_name, string from_email, string reply_to ) 		Function to submit messages to TNZ REST API

Returns MessageResult object

Sending Voice Text To Speech - VBA using .NET dll

 

Send TextToSpeech (Basic):


Private Sub cmdSendTTS_Click()
    Dim res As TNZAPI.MessageResult
    
    Dim message As TNZAPI.TTS
    Set message = New TNZAPI.TTS
    
    message.Sender = "YOUR_EMAIL_ADDRESS"
    message.APIKey = "YOUR_API_KEY"
    message.MessageToPeople = "Test Message 2"
    message.Recipient = "+6495005001"
    
    Set res = message.SendMessage()
    
    If res.MessageID <> "" Then
        MsgBox "Message ID: " & res.MessageID
    Else
        MsgBox "Error: " & res.ErrorMessage
    End If
End Sub                                                
Copy code

Required parameters

Parameter Example Value Description
Sender application@domain.com Sender value set up in Create a new API user token
APIKey ta8wr7ymd APIKey value set up in Create a new API user token
MessageToPeople Hello, this is a call from Department01. This is relevant information. Press one to be connected to our call centre. The text-to-speech message played if the call is answered by a human (may optionally include SSML commands)
Destinations +6495005001 Telephone number to receive the message (for detailed formatting, see the Destinations parameter below)

Optional parameters

Parameter Example Value Description
MessageID ID12345 Tracking ID or message description. Leave black if you want us to generate one.
Reference Test1 Reference of your message
SendTime new DateTime() Delay sending until the specified date/time (dd/mm/yyyy HH:mm in your local timezone, specified by your Sender setting or overridden using the TimeZone command)
Timezone New Zealand User's local timezone (see Setting Timezones)
SubAccount SubAccount01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
Department Department01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
ChargeCode BillingGroup01 Bespoke app cost allocation code (for invoice segmentation)
MessageToAnswerphones Hello, sorry we missed you. This is a call from Department 01. Please contact us on 0800 123123. The text-to-speech message played when the call is answered by an answering machine/voicemail service (may optionally include SSML commands)
Keypads > Tone 1 Keypad for call connection (supports buttons 1-9)
> RouteNumber +64800123123 Telephone number for call routing in dialling format
CallRouteMessageToPeople Connecting you now. Text-to-speech message played when a keypad option is pressed
CallRouteMessageToOperators Incoming Text To Speech call. Text-to-speech message played to the call centre representative answering the connected call
CallRouteMessageOnWrongKey Sorry, you have pressed an invalid key. Please try again. Text-to-speech message played when an unregistered keypad button is pressed
NumberOfOperators 5 Limits the maximum simultaneous calls (where multiple 'Destinations' are listed)
CallerID 6495005000 Sets the Caller ID used on the call (must be E.164 format)
TTSVoice TTSVoiceType.Female2 Text-to-Speech voice to use (Male1, Female1, Female2, Female3, Female4)
Options Customisable field that allows advanced voice options including recording survey responses, recording phone numbers, playing IVR options, capturing DTMF tones for account numbers or credit card numbers, etc.
Destinations > PhoneNumber +6495005000 Recipient of the call in E.164 internationalised format (for localized or friendly formatting, contact your account manager)
> Attention John Doe Recipient's friendly name
> Company Example Corp Recipient's company
> Custom1 Customisable field
> Custom2 Customisable field

Functions

Function Usage Description
AddRecipient() AddRecipient(string recipient)

AddRecipient(Recipient recipient) 		Function to add a single message recipient
AddRecipients() AddRecipients(List<string> recipients)

AddRecipients(List<Recipient> recipients) 		Function to add a list of message recipients
AddKeypad() AddKeypad(int tone, string route_number)

AddKeypad(Keypad keypad) 		Function to add a keypad option (init tone=keypad button, route_number=number to divert the call to)
AddKeypads() AddKeypads(List<Keypad> keypads) Function to add a list of keypads option (init tone=keypad button, route_number=number to divert the call to)
AddMessageData() AddMessageData(MessageDataType message_data_type, string tts_message) Function to add Text-To-Speech content into message (text will be converted to speech)
SendMessage() SendMessage()

SendMessage(string message_id, string reference, DateTime send_time, string timezone, string subaccount, string department, string charge_code, int number_of_operators, string caller_id, TTSVoiceType tts_voice, string options)

SendMessage(string message_id, string reference, DateTime send_time, string timezone, string subaccount, string department, string charge_code, string message_to_people, string message_to_answerphones, string call_route_message_to_people, string call_route_message_to_operators, string call_route_message_on_wrong_key, int number_of_operators, string caller_id, TTSVoiceType tts_voice, string options) 		Function to submit messages to TNZ REST API

Returns MessageResult object

Resending and retrying messages

To resend or retry sending a message via 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.


Sending messages in test mode

Under Message object you can specify an additional SendMode=Test parameter.

SendMode=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. 


// Send with Test mode
message.SendMode = TNZAPI.SendModeType.SendModeType_Test

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 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:



Parameter Example Value Description
Sender application@domain.com Webhook sender authentication (can configure a unique Sender if required)
APIKey ta8wr7ymd Webhook token authentication (can configure a unique APIKey if required)
Type SMS Type of Message ('Email', 'SMS', 'TextToSpeech', or 'SMSReply')
Destination +6421000001 Destination that the webhook is for (alphanumeric field, where telephone/mobile numbers are supplied in E.164 internationalised format)
MessageID js82hn8n MessageID parameter supplied when sending your original API call
SubAccount SubAccount01 Used for reporting, billing and Web Dashboard segmentation
Department Department01 Used for reporting, billing and Web Dashboard segmentation
JobNumber 10C7B9A0 Eight digit alphanumeric tracking number (our internal Job Number)
SentTime 16/10/2018 13:43 p.m. Time message was completed (Sender's local time time in 'dd/MM/yyyy HH:mm tt' format)
Status SUCCESS For submission results, values are SUCCESS, FAILED, PENDING
For reply reports, this will be RECEIVED
For additional analytics, this will be UPDATED
Result Sent OK Final delivery result and/or the cause for a message delivery failure
For a list of possible values, see SMS and TextToSpeech
Email result codes are defined by the receiving email server
For reply reports, this will be RECEIVED
For additional analytics, this will be the event description
Message This is a reply. This field will only contain data if 'Type=SMSReply'
Price 0.20 Your cost for this transaction, charged by us to you
Detail SMSParts:2 Additional billing detail: "SMSParts", "VoiceMinutes", "Size", "Prompts"
URL https://www.example.com/webhook The URL this webhook is sent to
RESPONSEMODE JSON This webhook's format

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:


Parameter Example Value Description
Sender application@domain.com Webhook sender authentication (can configure a unique Sender if required)
APIKey ta8wr7ymd Webhook token authentication (can configure a unique APIKey if required)
Type SMSReply Type of Message ('Email', 'SMS', 'Fax', 'Voice', 'TextToSpeech', or 'SMSReply')
Destination +6421000001 Destination that the webhook is for (alphanumeric field, where telephone/mobile numbers are supplied in E.164 internationalised format)
MessageID js82hn8n MessageID parameter supplied when sending your original API call
JobNumber 10C7B9A0 Eight digit alphanumeric tracking number (our internal Job Number)
SentTime 16/10/2018 13:43 p.m. Time reply message was received
Status RECEIVED For submission results, values are SUCCESS, FAILED, PENDING
For reply reports, this will be RECEIVED
For additional analytics, this will be UPDATED
Result RECEIVED Final delivery result and/or the cause for a message delivery failure
For reply reports, this will be RECEIVED
For additional analytics, this will be the event description
Message This is a reply. This field will only contain data if 'Type=SMSReply'
Price 0.20 Your cost for the outbound message sent, charged by us to you (no cost for the reply received)
Detail SMSParts:2 Additional billing detail: "SMSParts", "FaxPages", "VoiceMinutes", "Size", "Prompts" on the outbound message sent (not the SMS Received)
URL https://www.example.com/webhook The URL this webhook is sent to
RESPONSEMODE JSON This webhook's format

Versioning

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


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.

How many Destinations can I specify in one request?

There is no limit to the number of Destinations (in either format), provided you do not breach the maximum request size.

How many Files can I specify in one request?

There is a limit of 10 files specified in a single request. There is no file size limitation, provided you do not breach the maximum request size.

Do you support SPF, DKIM, DMARC, etc, for MessageType=Email?

Yes, we support email security measures. Contact us for further information on setting up your own security measures for whitelabeled messages delivered with the API.

When I send MessageType=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 via HTTPS. SSL/TLS is also supported for outbound email messages provided the receiving email server supports this.

Can I set the Caller ID on SMS, Fax, Voice and TextToSpeech messages?

Some networks support customised SMS Caller IDs. This can be configured using your Web Dashboard.
Your Fax Caller ID can be configured using your Web Dashboard.
Your Voice and TextToSpeech Caller ID is specified on a per-message basis using the 'CallerID' parameter.