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.
If you don't have an account, head to https://www.tnz.co.nz/Customer/SignUp/ and fill in the form.
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.
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: TNZAPI.dll.zip
Install the 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
Troubleshooting Errors:
- RA0000 Error
You can ignore this error and proceed as normal:
RegAsm : error RA0000 : An error occurred while saving the exported type library: Access is denied. (Exception from HRESULT: 0x80070005 (E_ACCESSDENIED))
- 'regasm' is not recognized
If you receive this error, you may need to use the full path to the regasm application:
c:\Windows\Microsoft.NET\Framework\v4.0.30319\regasm.exe /codebase /tlb "C:\Program Files\TNZ Group\TNZAPI.dll"
- Unregister DLL
If you need to unregister the DLL, run the unregister command:
regasm /unregister "C:\Program Files\TNZ Group\TNZAPI.dll"
In VBA IDE:
Using the [MessageType].SendMessage()
function, the DLL will connect to TNZ's REST API (in XML format) and send messages.
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.
Find instructions for each Message Type:
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
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) |
Parameter | Example Value | Description | |
---|---|---|---|
MessageID | ID12345 | A Message Identifier helps you keep track of each message (maximum 40 characters, alphanumeric). Use a unique MessageID for each request. If you leave this field blank, the API will generate a 36-character UUID (v4) for you and include it in the response body. | |
Reference | Test1 | Human readable message description (free format field, maximum 80 characters). | |
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 |
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 |
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
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) |
Parameter | Example Value | Description | |
---|---|---|---|
MessageID | ID12345 | A Message Identifier helps you keep track of each message (maximum 40 characters, alphanumeric). Use a unique MessageID for each request. If you leave this field blank, the API will generate a 36-character UUID (v4) for you and include it in the response body. | |
Reference | Test1 | Human readable message description (free format field, maximum 80 characters). | |
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 |
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 |
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
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) |
Parameter | Example Value | Description | |
---|---|---|---|
MessageID | ID12345 | A Message Identifier helps you keep track of each message (maximum 40 characters, alphanumeric). Use a unique MessageID for each request. If you leave this field blank, the API will generate a 36-character UUID (v4) for you and include it in the response body. | |
Reference | Test1 | Human readable message description (free format field, maximum 80 characters). | |
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 |
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 |
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.
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
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.
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.
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.
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' or 'TextToSpeech') |
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 | Field will be blank; it is used by the Receive Messages webhook only | |
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 |
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.
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.
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.
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', 'SMSInbound' or 'SMSReply') |
Destination | +6421000001 | Mobile number sending the SMS message (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. | The received SMS message (if 'Type=SMSInbound' or '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 |
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