|
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.
SendMode parameter in your message object to skip message delivery. The message will be accepted and processed with a simulated delivery result displayed. 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 SendMode=[MessageType].SendModeType.Test function of the library 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.
Using the API will require a Sender and APIKey pair to authenticate with the API.
You can generate this using the Web Dashboard under: Users | Outbound Users | Create
The standard REST API uses plain authentication. For OAuth2 authentication, contact your TNZ Representative.
Save hundreds of lines of code and hours of time by dropping the .NET DLL into your project and sending messages via TNZ. Using one DLL and simple code tweaks, your software can send Email, SMS and Text-to-Speech messages.
Using the [MessageType].SendMessage() function, the DLL will connect to TNZ's REST API (in XML format) and submit messages.
Step 1: Download the helper DLL: TNZAPI.dll.zip
Step 2: Extract the DLL to your local machine (the below references "C:\Program Files\TNZ Group\TNZAPI.dll")
Step 3: 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
Step 4: Download sample code and get building! VBA Sample Code
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()
MsgBox "Message ID: " & res.MessageID
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 | 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 | |
| Department | Department01 | Used for reporting, billing and Web Dashboard segmentation | |
| ChargeCode | BillingGroup01 | Cost allocation for billing | |
| 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()
MsgBox "Message ID: " & res.MessageID
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 | 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 | |
| Department | Department01 | Used for reporting, billing and Web Dashboard segmentation | |
| ChargeCode | BillingGroup01 | Cost allocation for billing | |
| 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()
MsgBox "Message ID: " & res.MessageID
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 | 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 | |
| Department | Department01 | Used for reporting, billing and Web Dashboard segmentation | |
| ChargeCode | BillingGroup01 | Cost allocation for billing | |
| 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 | ||
| 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', '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 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" |
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.
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) |
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