Last updated: October 8th 2021

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 .NET Library 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, Fax, Voice and Text-to-Speech messages.

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


Download the Library:

Download and extract the .NET library DLL:   TNZAPI.dll.zip



Install & Reference the Library:

Reference the library in your code:

  1. Expand your References on your project settings


  2. Right click on References and click Add Reference...


  3. Expand Browse from left side menu and click the Browse... button


  4. Find TNZAPI.dll and click the Add button


  5. You are now ready to use .NET Library!


  6. Reference the library in your code
    
using TNZAPI;
using TNZAPI.Messaging;
using TNZAPI.Messaging.Functions;
using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Send;
using TNZAPI.Messaging.Get;

Send Messages using the Library:

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 application with the .NET Library

Find instructions for each Message Type:

Sending Email - Send Email via .NET

 

Send Email (Basic):


using TNZAPI.Messaging.Send;

namespace TNZEmailBasic
{
    class Program
    {
        static void Main(string[] args)
        {
            Email EmailMessage = new Email();

            EmailMessage.Sender = "YOUR_EMAIL_ADDRESS";         // API Username
            EmailMessage.APIKey = "YOUR_API_KEY";               // API Key

            EmailMessage.FromEmail = "from@test.com";           // Optional : Sets From Email Address - leave blank to use your api username as email sender
            EmailMessage.EmailSubject = "Test Email";           // Email Subject
            EmailMessage.MessagePlain = "Test Email Body";      // Email Body
            EmailMessage.AddRecipient("email.one@test.com");    // Recipient 1
            EmailMessage.AddRecipient("email.two@test.com");    // Recipient 2

            EmailMessage.SendMessage();
        }
    }
}
                                                
Copy code

Send Email (Simple):


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Send;

namespace TNZEmailSimple
{
		class Program
		{
				static void Main(string[] args)
				{
						const string sender = "YOUR_EMAIL_ADDRESS";             // API Username
            const string api_key = "YOUR_API_KEY";                  // API Key

            const string from_email = "from@test.com";              // Optional : Sets From Email Address - leave blank to use your api username as email sender

            const string subject = "Test Email";                    // Email Subject
            const string message_plain = "Test Email Body";         // Email Body (Plain Text)

            const string recipient = "email@test.com";              // Recipient

            Email EmailMessage = new Email(sender, api_key);

            EmailMessage.SetEmailFrom(from_email);

						EmailMessage.AddRecipient(recipient);

						MessageResult response = EmailMessage.SendMessage(
								subject,
								message_plain
						);

						if (response.Result == MessageResult.ResultCode.Success)
						{
								Console.WriteLine("Success - " + response.MessageID);
						}
						else
						{
								Console.WriteLine("Error - " + response.ErrorMessage);
						}

						Console.ReadLine();
				}
		}
}
                                                
Copy code

Send Email (Advanced):


using System;
using System.Collections.Generic;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Send;
using TNZAPI.Messaging.Functions;

namespace TNZEmailAdvanced
{
    class Program
    {
        static void Main(string[] args)
        {
            #region Declarations

            const string sender = "sender@example.com";
            const string api_key = "YOUR_API_KEY";
            const string reference = "Test Email - Advanced version";

            const string webhook_callback_url = "https://example.com/webhook";
            const Enums.WebhookCallbackType webhook_callback_format = Enums.WebhookCallbackType.XML;

            const string recipient1 = "emailTo@test.com";
            const string recipient2 = "emailTo@test.com";
            const string recipient3 = "emailTo@test.com";
            const string recipient4 = "emailTo@test.com";

            const string file1 = "c:\\File1.pdf";
            const string file2 = "c:\\File2.pdf";
            const string file3 = "c:\\File3.pdf";
            const string file4 = "c:\\File4.pdf";

            const string smtp_from = "from@test.com";
            const string from_name = "Email From";
            const string from_email = "email@test.com";
            const string reply_to = "email@test.com";

            const string subject = "Test Email 123";
            const string message_plain = "Test Email Body";
            const string message_html = "
This is Test message body. Thank you so much!
";

            #endregion Declarations

            Email EmailMessage = new Email()
            {
                Sender = sender,
                APIKey = api_key,

                WebhookCallbackURL = webhook_callback_url,
                WebhookCallbackFormat = webhook_callback_format
            };

            #region Add Recipients

            //
            // Add Recipient Method 1 - AddRecipient(string recipient);
            //

            EmailMessage.AddRecipient(recipient1);

            //
            // Add Recipient Method 2 - AddRecipient(new Recipient())
            //

            Recipient recipient = new Recipient(recipient2);
            recipient.CompanyName = "Test Company";         // Company Name
            recipient.Attention = "Test Recipient 2";       // Attention
            recipient.Custom1 = "Custom1";                  // Custom1
            recipient.Custom2 = "Custom2";                  // Custom2
            recipient.Custom3 = "Custom3";                  // Custom3
            recipient.Custom4 = "Custom4";                  // Custom4
            recipient.Custom5 = "Custom5";                  // Custom5

            EmailMessage.AddRecipient(recipient);

            //
            // Add Recipient Method 3 - AddRecipients(new List()); using simple destination
            //

            List recipients = new List();

            recipients.Add(new Recipient(recipient3));

            //
            // Add Recipient Method 4 - AddRecipients(new List()) using Recipient objects
            //

            recipients.Add(new Recipient(
                recipient4,							// Recipient
                "Test Company",         // Company Name
                "Test Recipient 3",     // Attention
                "Custom1",              // Custom1
                "Custom2",              // Custom2
                "Custom3",              // Custom3
                "Custom4",              // Custom4
                "Custom5"               // Custom5
            ));

            EmailMessage.AddRecipients(recipients);

            #endregion Add Recipients

            #region Add Attachments

            //
            // Add Attachment Method 1 - AddAttachment(file_location);
            //
            EmailMessage.AddAttachment(file1);

            //
            // Add Attachment Method 2 - AddAttachment(new Attachment());
            //

            Attachment attachment = new Attachment();
            attachment.FileName = FileHandlers.GetFileName(file2);
            attachment.FileContent = FileHandlers.GetFileContents(file2);

            EmailMessage.AddAttachment(attachment);

            //
            // Add Attachment Method 3 - AddAttachments(new List()) using simple file locations
            //
            List attachments = new List();

            attachments.Add(new Attachment(file3));

            //
            // Add Attachment Method 4 - AddAttachments(new List()) using Attachment objects
            //

            attachments.Add(new Attachment(
                FileHandlers.GetFileName(file4),
                FileHandlers.GetFileContents(file4)
                ));

            EmailMessage.AddAttachments(attachments);

            #endregion Add Attachments

            #region Set SMTP Headers

            // Set email sender
            EmailMessage.SetEmailFrom(
                smtp_from,
                from_name,
                from_email,
                reply_to
            );

            #endregion Set SMTP Headers

            MessageResult response = EmailMessage.SendMessage(
                subject,										//Subject
                message_plain,							//MessagePlain
                message_html,								//MessageHTML
                "",													//MessageID
                reference,									//Reference
                new DateTime(),             //SendTime
                "New Zealand",              //Timezone
                "",                         //SubAccount
                "",                         //Department
                ""                          //ChargeCode
            );

            if (response.Result == MessageResult.ResultCode.Success)
            {
                Console.WriteLine("Success - "+response.MessageID);
            }
            else
            {
                Console.WriteLine("Error - " + response.ErrorMessage);
            }

            Console.ReadLine();
        }
    }
}
                                                
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
WebhookCallbackURL https://www.example.com/webhook URL to receive webhooks
WebhookCallbackFormat JSON Format of webhooks (JSON or XML)
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 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)

SendMessage(
    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

Async Functions

Function Usage Description
AddAttachmentAsync() AddAttachmentAsync(string file_location)

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

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

SendMessageAsync(string message_text)

SendMessageAsync(
    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 Task<IMessageResult> object

Sending SMS - Send SMS/TXT via .NET

 

Send SMS (Basic):


using TNZAPI.Messaging.Send;

namespace TNZSMSBasic
{
    class Program
    {
        static void Main(string[] args)
        {
            SMS SMSMessage = new SMS();

            SMSMessage.Sender = "YOUR_EMAIL_ADDRESS";
            SMSMessage.APIKey = "YOUR_API_KEY";
            SMSMessage.MessageText = "Test SMS";
            SMSMessage.AddRecipient("+64211111111");
            SMSMessage.AddRecipient("+64222222222");

            SMSMessage.SendMessage();
        }
    }
}
                                                
Copy code

Send SMS (Simple):


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Send;

namespace TNZSMSSimple
{
    class Program
    {
        static void Main(string[] args)
        {
            SMS SMSMessage = new SMS()
            {
                Sender = "YOUR_EMAIL_ADDRESS",
                APIKey = "YOUR_API_KEY",
                MessageText = "Test SMS",
                Recipient = "+64211111111"
            };

            MessageResult response = SMSMessage.SendMessage();

            if (response.Result == MessageResult.ResultCode.Success)
            {
                Console.WriteLine("Success - " + response.MessageID);
            }
            else
            {
                Console.WriteLine("Error - " + response.ErrorMessage);
            }

            Console.ReadLine();
        }
    }
}
                                                
Copy code

Send SMS (Advanced):


using System;
using System.Collections.Generic;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Send;
using TNZAPI.Messaging.Functions;
using System.Threading.Tasks;

namespace TNZSMSAdvanced
{
    class Program
    {
        static void Main(string[] args)
        {
            #region Declarations

            const string sender = "YOUR_EMAIL_ADDRESS";
            const string api_key = "YOUR_API_KEY";
            const string reference = "Test SMS - Advanced version";

            const string webhook_callback_url = "https://example.com/webhook";
            const Enums.WebhookCallbackType webhook_callback_format = Enums.WebhookCallbackType.XML;

            const string sms_email_reply = "reply@test.com";
            const string force_gsm_chars = "True";

            const string recipient1 = "+64211111111";
            const string recipient2 = "+64212222222";
            const string recipient3 = "+64213333333";
            const string recipient4 = "+64214444444";

            const string file1 = "C:\\file1.pdf";
            const string file2 = "C:\\file2.pdf";
            const string file3 = "C:\\file3.pdf";
            const string file4 = "C:\\file4.pdf";

            const string message_text = "Test SMS Message [[File1]] | [[File2]] | [[File3]] | [[File4]]";

            #endregion Declarations

            SMS SMSMessage = new SMS()
            {
                Sender = sender,
                APIKey = api_key,

                WebhookCallbackURL = webhook_callback_url,
                WebhookCallbackFormat = webhook_callback_format
            };

            #region Add Recipients

            //
            // Add Recipient Method 1 - AddRecipient(string recipient);
            //
            SMSMessage.AddRecipient(recipient1);

            //
            // Add Recipient Method 2 - AddRecipient(new Recipient())
            //

            Recipient recipient = new Recipient(recipient2);
            recipient.CompanyName = "Test Company";         // Company Name
            recipient.Attention = "Test Recipient 2";       // Attention
            recipient.Custom1 = "Custom1";                  // Custom1
            recipient.Custom2 = "Custom2";                  // Custom2
            recipient.Custom3 = "Custom3";                  // Custom3
            recipient.Custom4 = "Custom4";                  // Custom4
            recipient.Custom5 = "Custom5";                  // Custom5

            SMSMessage.AddRecipient(recipient);

            //
            // Add Recipient Method 3 - AddRecipients(new List()); using simple destination
            //

            List recipients = new List();

            recipients.Add(new Recipient(recipient3));

            //
            // Add Recipient Method 4 - AddRecipients(new List()) using Recipient objects
            //

            recipients.Add(new Recipient(
                recipient4,             // Recipient
                "Test Company",         // Company Name
                "Test Recipient 4",     // Attention
                "Custom1",              // Custom1
                "Custom2",              // Custom2
                "Custom3",              // Custom3
                "Custom4",              // Custom4
                "Custom5"               // Custom5
            ));

            SMSMessage.AddRecipients(recipients);

            #endregion Add Recipients

            #region Add Attachments
            /*
             * Please note:
             * 
             * Attachments are only supported with MessageLink - Please ask us to enable MessageLink 
             * 
             * Attachments will get ignored if you have not MessageLink functionality
             */

            //
            // Add Attachment Method 1 - AddAttachment(file_location);
            //
            SMSMessage.AddAttachment(file1);

            //
            // Add Attachment Method 2 - AddAttachment(new Attachment());
            //

            Attachment attachment = new Attachment();
            attachment.FileName = FileHandlers.GetFileName(file2);
            attachment.FileContent = FileHandlers.GetFileContents(file2);

            SMSMessage.AddAttachment(attachment);

            //
            // Add Attachment Method 3 - AddAttachments(new List()) using simple file locations
            //
            List attachments = new List();

            attachments.Add(new Attachment(file3));

            //
            // Add Attachment Method 4 - AddAttachments(new List()) using Attachment objects
            //

            attachments.Add(new Attachment(
                FileHandlers.GetFileName(file4),
                FileHandlers.GetFileContents(file4)
                ));

            SMSMessage.AddAttachments(attachments);

            #endregion Add Attachments

            MessageResult response = SMSMessage.SendMessage(
                "",                     // MessageID - Leave blank to auto-generate
                reference,              // Reference
                new DateTime(),         // SendTime
                "New Zealand",          // Timezone
                "",                     // SubAccount
                "",                     // Department
                "",                     // ChargeCode
                sms_email_reply,        // SMSEmailReply - For email (SMTP) reply receipt notifications
                force_gsm_chars,        // ForceGSMChars
                message_text
            );
            
            if (response.Result == MessageResult.ResultCode.Success)
            {
                Console.WriteLine("Success - " + response.MessageID);
            }
            else
            {
                Console.WriteLine("Error - " + response.ErrorMessage);
            }

            Console.ReadLine();
        }
    }
}
                                                
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
WebhookCallbackURL https://www.example.com/webhook URL to receive webhooks
WebhookCallbackFormat JSON Format of webhooks (JSON or XML)
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 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 message_text)

SendMessage(
    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

Async Functions

Function Usage Description
AddAttachmentAsync() AddAttachmentAsync(string file_location)

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

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

SendMessageAsync(string message_text)

SendMessageAsync(
    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 Task<IMessageResult> object

Sending Faxes - Send Fax via .NET

 

Send Fax (Basic):


using TNZAPI.Messaging.Send;

namespace TNZFaxBasic
{
    class Program
    {
        static void Main(string[] args)
        {
            Fax FaxMessage = new Fax();

            FaxMessage.Sender = "YOUR_EMAIL_ADDRESS";
            FaxMessage.APIKey = "YOUR_API_KEY";
            FaxMessage.AddRecipient("+6491111111");
            FaxMessage.AddRecipient("+6492222222");
            FaxMessage.AddAttachment("C:\\File1.pdf");

            FaxMessage.SendMessage();
        }
    }
}
                                                
Copy code

Send Fax (Simple):


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Send;

namespace TNZFaxSimple
{
    class Program
    {
        static void Main(string[] args)
        {
            const string sender = "YOUR_EMAIL_ADDRESS";
            const string api_key = "YOUR_API_KEY";
            const string recipient = "+6491111111";

            const string file = "C:\\File1.pdf";

            Fax FaxMessage = new Fax(sender, api_key);

            FaxMessage.AddRecipient(recipient);
            FaxMessage.AddAttachment(file);
            
            MessageResult response = FaxMessage.SendMessage();

            if (response.Result == MessageResult.ResultCode.Success)
            {
                Console.WriteLine("Success - " + response.MessageID);
            }
            else
            {
                Console.WriteLine("Error - " + response.ErrorMessage);
            }

            Console.ReadLine();
        }
    }
}
                                                
Copy code

Send Fax (Advanced):


using System;
using System.Collections.Generic;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Send;
using TNZAPI.Messaging.Functions;

namespace TNZFaxAdvanced
{
    class Program
    {
        static void Main(string[] args)
        {
            #region Declarations

            const string sender = "YOUR_EMAIL_ADDRESS";
            const string api_key = "YOUR_API_KEY";
            const string reference = "Test Fax - Advanced version";

            const string webhook_callback_url = "https://example.com/webhook";
            const Enums.WebhookCallbackType webhook_callback_format = Enums.WebhookCallbackType.XML;

            const string recipient1 = "+6491111111";
            const string recipient2 = "+6492222222";
            const string recipient3 = "+6493333333";
            const string recipient4 = "+6494444444";

            const string file1 = "C:\\file1.pdf";
            const string file2 = "C:\\file2.pdf";
            const string file3 = "C:\\file3.pdf";
            const string file4 = "C:\\file4.pdf";

            const string resolution = "High";
            const string csid = "TEST FAX";

            const int retry_attempts = 3;
            const int retry_period = 1;

            #endregion Declarations

            Fax FaxMessage = new Fax()
            {
                Sender = sender,
                APIKey = api_key,

                WebhookCallbackURL = webhook_callback_url,
                WebhookCallbackFormat = webhook_callback_format
            };

            #region Add Recipients

            //
            // Add Recipient Method 1 - AddRecipient(string recipient);
            //

            FaxMessage.AddRecipient(recipient1);

            //
            // Add Recipient Method 2 - AddRecipient(new Recipient())
            //

            Recipient recipient = new Recipient(recipient2);
            recipient.CompanyName = "Test Company";         // Company Name
            recipient.Attention = "Test Recipient 2";       // Attention
            recipient.Custom1 = "Custom1";                  // Custom1
            recipient.Custom2 = "Custom2";                  // Custom2
            recipient.Custom3 = "Custom3";                  // Custom3
            recipient.Custom4 = "Custom4";                  // Custom4
            recipient.Custom5 = "Custom5";                  // Custom5

            FaxMessage.AddRecipient(recipient);

            //
            // Add Recipient Method 3 - AddRecipients(new List()); using simple destination
            //

            List recipients = new List();

            recipients.Add(new Recipient(recipient3));

            //
            // Add Recipient Method 4 - AddRecipients(new List()) using Recipient objects
            //

            recipients.Add(new Recipient(
                recipient4,              // Recipient
                "Test Company",         // Company Name
                "Test Recipient 4",     // Attention
                "Custom1",              // Custom1
                "Custom2",              // Custom2
                "Custom3",              // Custom3
                "Custom4",              // Custom4
                "Custom5"               // Custom5
            ));

            FaxMessage.AddRecipients(recipients);

            #endregion Add Recipients

            #region Add Attachments

            //
            // Add Attachment Method 1 - AddAttachment(file_location);
            //
            FaxMessage.AddAttachment(file1);

            //
            // Add Attachment Method 2 - AddAttachment(new Attachment());
            //

            Attachment attachment = new Attachment();
            attachment.FileName = FileHandlers.GetFileName(file2);
            attachment.FileContent = FileHandlers.GetFileContents(file2);

            FaxMessage.AddAttachment(attachment);

            //
            // Add Attachment Method 3 - AddAttachments(new List()) using simple file locations
            //
            List attachments = new List();

            attachments.Add(new Attachment(file3));

            //
            // Add Attachment Method 4 - AddAttachments(new List()) using Attachment objects
            //

            attachments.Add(new Attachment(
                FileHandlers.GetFileName(file4),
                FileHandlers.GetFileContents(file4)
                ));

            FaxMessage.AddAttachments(attachments);

            #endregion Add Attachments

            MessageResult response = FaxMessage.SendMessage(
                "",                     // MessageID - Leave blank to auto-generate
                reference,              // Reference
                new DateTime(),         // SendTime
                "New Zealand",          // Timezone
                "",                     // SubAccount
                "",                     // Department
                "",                     // ChargeCode
                resolution,             // Resolution - High/Low
                csid,                   // CSID
                "",                     // WaterMarkFolder
                "",                     // WaterMarkFirstPage
                "",                     // WaterMarkAllPages
                retry_attempts,         // RetryAttempts - no of retries
                retry_period            // RetryPeriod - no of minutes between retries
            );

            if (response.Result == MessageResult.ResultCode.Success)
            {
                Console.WriteLine("Success - " + response.MessageID);
            }
            else
            {
                Console.WriteLine("Error - " + response.ErrorMessage);
            }

            Console.ReadLine();
        }
    }
}
                                                
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
Recipient +6495005001 Fax number(s) to receive the message (for detailed formatting, see the Destinations parameter below)
Attachment > Name Sample.pdf Fax document's filename
> Data %%Base-64%% Base-64 encoded value of the document

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
WebhookCallbackURL https://www.example.com/webhook URL to receive webhooks
WebhookCallbackFormat JSON Format of webhooks (JSON or XML)
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)
WatermarkFolder Folder01 Directory/location of Watermark file to use
WatermarkFirstPage Watermark File Name Watermark file to apply to the first page only
WatermarkAllPages Watermark File Name Watermark file to apply to all pages
Resolution High Quality of the fax image. High for better quality, low for lower quality (faster delivery speed)
CSID Station ID Called Subscriber Identification - Maximum 30 characters
RetryAttempts 3 Number of retries (retry_period required)
RetryPeriod 1 Minutes between retries (retry_attempts required)
Recipients > Recipient +6495005000 Recipient of the Fax in E.164 internationalised format (for localized or friendly formatting, contact your account manager)
> Attention John Doe Recipient's 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 message_id,
    string reference,
    DateTime send_time,
    string timezone,
    string subaccount,
    string department,
    string charge_code,
    string resolution,
    string csid
)

SendMessage(
    string message_id,
    string reference,
    DateTime send_time,
    string timezone,
    string subaccount,
    string department,
    string charge_code,
    string resolution,
    string csid,
    string watermark_folder,
    string watermark_firstpage,
    string watermark_allpages,
    int retry_attempts,
    int retry_period
) 		Function to submit messages to TNZ REST API

Returns MessageResult object

Async Functions

Function Usage Description
AddAttachmentAsync() AddAttachmentAsync(string file_location)

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

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

SendMessageAsync(
    string message_id,
    string reference,
    DateTime send_time,
    string timezone,
    string subaccount,
    string department,
    string charge_code,
    string resolution,
    string csid
)

SendMessageAsync(
    string message_id,
    string reference,
    DateTime send_time,
    string timezone,
    string subaccount,
    string department,
    string charge_code,
    string resolution,
    string csid,
    string watermark_folder,
    string watermark_firstpage,
    string watermark_allpages,
    int retry_attempts,
    int retry_period
) 		Function to submit messages to TNZ REST API

Returns Task<IMessageResult> object

Sending Voice (Voicemail) - Send VoiceCast via .NET

 

Send Voice:


using TNZAPI.Messaging.Functions;
using TNZAPI.Messaging.Send;

namespace TNZVoiceBasic
{
    class Program
    {
        static void Main(string[] args)
        {
            Voice VoiceMessage = new Voice();

            VoiceMessage.Sender = "YOUR_EMAIL_ADDRESS";
            VoiceMessage.APIKey = "YOUR_API_KEY";
            VoiceMessage.MessageToPeople = FileHandlers.GetFileContents("C:\\Voice.wav");   // WAV format, 16-bit, 8000hz
            VoiceMessage.AddRecipient("+64211111111");
            VoiceMessage.AddRecipient("+64222222222");

            VoiceMessage.SendMessage();
        }
    }
}
                                                
Copy code

Send Voice:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Send;

namespace TNZVoiceSimple
{
    class Program
    {
        static void Main(string[] args)
        {
            const string sender = "YOUR_EMAIL_ADDRESS";
            const string api_key = "YOUR_API_KEY";
            const string recipient = "+64211111111";

            const string file = "C:\\Voice.wav";

            Voice VoiceMessage = new Voice(sender, api_key);

            VoiceMessage.AddMessageData(Voice.MessageDataType.MessageToPeople, file);
            VoiceMessage.AddRecipient(recipient);

            MessageResult response = VoiceMessage.SendMessage();

            if (response.Result == MessageResult.ResultCode.Success)
            {
                Console.WriteLine("Success - " + response.MessageID);
            }
            else
            {
                Console.WriteLine("Error - " + response.ErrorMessage);
            }

            Console.ReadLine();
        }
    }
}
                                                
Copy code

Send Voice (Advanced):


using System;
using System.Collections.Generic;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Send;

namespace TNZVoiceAdvanced
{
    class Program
    {
        static void Main(string[] args)
        {
            const string sender = "YOUR_EMAIL_ADDRESS";
            const string api_key = "YOUR_API_KEY";
            const string reference = "Test Voice - Advanced version";

            const string webhook_callback_url = "https://example.com/webhook";
            const Enums.WebhookCallbackType webhook_callback_format = Enums.WebhookCallbackType.XML;

            const string caller_id = "+6499999999";
            const string billing_account = "TEST BILLING ACCOUNT";
            const string report_to = "report@example.com";

            const string recipient1 = "+64211111111";
            const string recipient2 = "+64212222222";
            const string recipient3 = "+64213333333";
            const string recipient4 = "+64214444444";

            const string message_to_people = "C:\\Voice1.wav";                  // WAV format, 16-bit, 8000hz
            const string message_to_answerphones = "C:\\Voice2.wav";            // WAV format, 16-bit, 8000hz
            const string call_route_message_to_people = "C:\\Voice3.wav";       // WAV format, 16-bit, 8000hz
            const string call_route_message_to_operators = "C:\\Voice4.wav";    // WAV format, 16-bit, 8000hz
            const string call_route_message_on_wrong_key = "C:\\Voice5.wav";    // WAV format, 16-bit, 8000hz

            const int number_of_operators = 1;
            const int retry_attempts = 2;
            const int retry_period = 5;

            const string keypad1_route = "+6491111111";
            const string keypad2_route = "+6492222222";
            const string keypad3_route = "+6493333333";
            const string keypad4_route = "+6494444444";

            Voice VoiceMessage = new Voice() 
            { 
                Sender = sender,
                APIKey = api_key,

                WebhookCallbackURL = webhook_callback_url,
                WebhookCallbackFormat = webhook_callback_format
            };

            #region Call Options
            VoiceMessage.Reference = reference;
            VoiceMessage.CallerID = caller_id;
            VoiceMessage.SubAccount = billing_account;
            VoiceMessage.ReportTo = report_to;

            VoiceMessage.NumberOfOperators = number_of_operators;
            VoiceMessage.RetryAttempts = retry_attempts;
            VoiceMessage.RetryPeriod = retry_period;
            #endregion Call Options

            #region Submit Audio Files
            //
            // Submit audio files - WAV format, 16-bit, 8000hz
            //
            VoiceMessage.AddMessageData(Voice.MessageDataType.MessageToPeople, message_to_people);
            VoiceMessage.AddMessageData(Voice.MessageDataType.MessageToAnswerPhones, message_to_answerphones);
            VoiceMessage.AddMessageData(Voice.MessageDataType.CallRouteMessageToPeople, call_route_message_to_people);
            VoiceMessage.AddMessageData(Voice.MessageDataType.CallRouteMessageToOperators, call_route_message_to_operators);
            VoiceMessage.AddMessageData(Voice.MessageDataType.CallRouteMessageOnWrongKey, call_route_message_on_wrong_key);
            #endregion Submit Audio Files

            #region Add Keypads
            //
            // Add Keypad Method 1 - VoiceMessage.AddKeypad(int key, string keypad1_route);
            //
            VoiceMessage.AddKeypad(1, keypad1_route);

            //
            // Add Keypad Method 2 - AddKeypad(new Keypad());
            //
            VoiceMessage.AddKeypad(new Keypad(2, keypad2_route));

            //
            // Add Keypad Method 3 - AddKeypad(new List())
            //
            List keypad_list = new List();

            keypad_list.Add(new Keypad(3, keypad3_route));

            //
            // Add Keypad Method 4 - AddKeypad(new List()) using Keypad objects
            //
            Keypad keypad4 = new Keypad();
            keypad4.Tone = 4;
            keypad4.RouteNumber = keypad4_route;

            keypad_list.Add(keypad4);

            //
            // Add Keypad Method 5 - Add Play (Wave Data)
            //
            Keypad keypad5 = new Keypad();
            keypad5.Tone = 5;
            keypad5.PlayFile = "C:\\keypad5.wav";

            keypad_list.Add(keypad5);


            VoiceMessage.AddKeypads(keypad_list);
            #endregion Add Keypads

            #region Add Recipients

            //
            // Add Recipient Method 1 - AddRecipient(string recipient);
            //

            VoiceMessage.AddRecipient(recipient1);

            //
            // Add Recipient Method 2 - AddRecipient(new Recipient())
            //

            Recipient recipient = new Recipient(recipient2);
            recipient.CompanyName = "Test Company";         // Company Name
            recipient.Attention = "Test Recipient 2";       // Attention
            recipient.Custom1 = "Custom1";                  // Custom1
            recipient.Custom2 = "Custom2";                  // Custom2
            recipient.Custom3 = "Custom3";                  // Custom3
            recipient.Custom4 = "Custom4";                  // Custom4
            recipient.Custom5 = "Custom5";                  // Custom5

            //VoiceMessage.AddRecipient(recipient);

            //
            // Add Recipient Method 3 - AddRecipients(new List()); using simple destination
            //

            List recipients = new List();

            recipients.Add(new Recipient(recipient3));

            //
            // Add Recipient Method 4 - AddRecipients(new List()) using Recipient objects
            //

            recipients.Add(new Recipient(
                recipient4,              // Recipient
                "Test Company",         // Company Name
                "Test Recipient 4",     // Attention
                "Custom1",              // Custom1
                "Custom2",              // Custom2
                "Custom3",              // Custom3
                "Custom4",              // Custom4
                "Custom5"               // Custom5
            ));

            VoiceMessage.AddRecipients(recipients);

            #endregion Add Recipients

            MessageResult response = VoiceMessage.SendMessage(
                "",                     // MessageID - Leave blank to auto-generate
                reference,              // Reference
                new DateTime(),         // SendTime
                "New Zealand",          // Timezone
                billing_account,        // Billing Account (Sub Account)
                "",                     // Department
                "",                     // Charge Code
                number_of_operators,    // No of Operators - Limits the maximum simultaneous calls
                caller_id,              // Caller ID
                ""                      // Options
            );

            if (response.Result == MessageResult.ResultCode.Success)
            {
                Console.WriteLine("Success - " + response.MessageID);
            }
            else
            {
                Console.WriteLine("Error - " + response.ErrorMessage);
            }

            Console.ReadLine();
        }
    }
}
                                                
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 [Base64encoded data] The audio data played if the call is answered by a human (WAV format, 16-bit, 8000hz)
Recipient +6495005001 Telephone number(s) 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.
WebhookCallbackURL https://www.example.com/webhook URL to receive webhooks
WebhookCallbackFormat JSON Format of webhooks (JSON or XML)
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)
ReportTo report@example.com For email (SMTP) message delivery report notifications.
MessageToAnswerphones [Base64encoded data] The audio data played when the call is answered by an answering machine/voicemail service (WAV format, 16-bit, 8000hz)
Keypads > Tone 1 Keypad for call connection (supports buttons 1-9)
> RouteNumber +64800123123 Telephone number for call routing in dialling format
> PlayFile C:\Message.wav Audio file played to B-Party when a keypad option is pressed (WAV format, 16-bit, 8000hz), eg "Thank you. You have pressed keypad 1."
CallRouteMessageToPeople [Base64encoded data] Audio data played when a keypad option is pressed (WAV format, 16-bit, 8000hz), eg "Connecting you now."
CallRouteMessageToOperators [Base64encoded data] Audio data played to the call centre representative answering the connected call (WAV format, 16-bit, 8000hz), eg "Incoming Text To Speech call."
CallRouteMessageOnWrongKey [Base64encoded data] Audio data played when an unregistered keypad button is pressed (WAV format, 16-bit, 8000hz), eg "Sorry, you have pressed an invalid key. Please try again"
NumberOfOperators 5 Limits the maximum simultaneous calls (where multiple 'Destinations' are listed)
RetryAttempts 3 Number of retry attempts if the recipients line is busy or unavailable
RetryPeriod 1 Minutes apart when performing retries
CallerID +6495005000 Sets the Caller ID used on the call (must be E.164 format)
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.
Recipients > 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 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 keypad options (init tone=keypad button, route_number=number to divert the call to)
AddMessageData() AddMessageData(MessageDataType message_data_type, string file_location) Function to add a WAV audio file to the message (the .NET library will grab the file contents from the specified file location)
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,
    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,
    string options
) 		Function to submit messages to TNZ REST API

Returns MessageResult object

Async Functions

Function Usage Description
AddMessageDataAsync() AddMessageDataAsync(Voice.MessageDataType message_data_type, string file_location) Function to add a WAV audio file to the message (the .NET library will grab the file contents from the specified file location)
SendMessageAsync() SendMessageAsync()

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

SendMessageAsync(
    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,
    string options
) 		Function to submit messages to TNZ REST API

Returns Task<IMessageResult> object

Sending Voice Text To Speech - Send TTS via .NET

 

Send TextToSpeech (Basic):


using TNZAPI.Messaging.Send;

namespace TNZTTSBasic
{
    class Program
    {
        static void Main(string[] args)
        {
            TTS TTSMessage = new TTS();

            TTSMessage.Sender = "YOUR_EMAIL_ADDRESS";
            TTSMessage.APIKey = "YOUR_API_KEY";
            TTSMessage.MessageToPeople = "Hello, this is a call from test. This is relevant information.";
            TTSMessage.AddRecipient("+64211111111");
            TTSMessage.AddRecipient("+64222222222");
            TTSMessage.TTSVoice = TTS.TTSVoiceType.Emma;

            TTSMessage.SendMessage();
        }
    }
}
                                                
Copy code

Send TextToSpeech (Simple):


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Send;

namespace TNZTTSSimple
{
    class Program
    {
        static void Main(string[] args)
        {
            const string sender = "YOUR_EMAIL_ADDRESS";
            const string api_key = "YOUR_API_KEY";
            const string recipient = "+64211111111";

            const string message_to_people = "Hello, this is a call from test. This is relevant information.";

            TTS TTSMessage = new TTS(sender, api_key);

            TTSMessage.AddMessageData(TTS.MessageDataType.MessageToPeople, message_to_people);
            TTSMessage.AddRecipient(recipient);

            MessageResult response = TTSMessage.SendMessage();

            if( response.Result == MessageResult.ResultCode.Success )
            {
                Console.WriteLine("Success - " + response.MessageID);
            }
            else
            {
                Console.WriteLine("Error - " + response.ErrorMessage);
            }

            Console.ReadLine();
        }
    }
}
                                                
Copy code

Send TextToSpeech (Advanced):


using System;
using System.Collections.Generic;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Send;

namespace TNZTTSAdvanced
{
    class Program
    {
        static void Main(string[] args)
        {
            const string sender = "YOUR_EMAIL_ADDRESS";
            const string api_key = "YOUR_API_KEY";
            const string reference = "Test TTS - Advanced version";

            const string webhook_callback_url = "https://example.com/webhook";
            const Enums.WebhookCallbackType webhook_callback_format = Enums.WebhookCallbackType.XML;

            const string caller_id = "+6499999999";
            const string billing_account = "TEST BILLING ACCOUNT";
            const string report_to = "report@example.com";

            const string recipient1 = "+64211111111";
            const string recipient2 = "+64212222222";
            const string recipient3 = "+64213333333";
            const string recipient4 = "+64214444444";

            const string message_to_people = "Hello, this is a call from Department01. This is relevant information. Press one to be connected to our call centre.";
            const string message_to_answerphones = "Hello, sorry we missed you. This is a call from Department 01. Please contact us on 0800 123123.";
            const string call_route_message_to_people = "Connecting you now.";
            const string call_route_message_to_operators = "Incoming Text To Speech call.";
            const string call_route_message_on_wrong_key = "Sorry, you have pressed an invalid key. Please try again.";

            const int number_of_operators = 1;
            const int retry_attempts = 3;
            const int retry_period = 1;

            const TTS.TTSVoiceType tts_voice = TTS.TTSVoiceType.Female1;

            const string keypad1_route = "+6491111111";
            const string keypad2_route = "+6492222222";
            const string keypad3_play = "Hello, you have pressed 3.";
            const string keypad4_route = "+6493333333";
            const string keypad5_route = "+6494444444";
            const string keypad6_play = "Hello, you have pressed 5.";
            const string keypad7_route = "+6497777777";
            const string keypad7_play = "Hello, you have pressed 6.";

            TTS TTSMessage = new TTS()
            {
                Sender = sender,
                APIKey = api_key,

                WebhookCallbackURL = webhook_callback_url,
                WebhookCallbackFormat = webhook_callback_format
            };


            #region Call Options
            TTSMessage.Reference = reference;
            TTSMessage.CallerID = caller_id;
            TTSMessage.SubAccount = billing_account;
            TTSMessage.ReportTo = report_to;

            TTSMessage.NumberOfOperators = number_of_operators;
            TTSMessage.RetryAttempts = retry_attempts;
            TTSMessage.RetryPeriod = retry_period;
            #endregion Call Options


            #region Submit TextToSpeech Messagess
            //
            // Submit TextToSpeech Messagess (Text format only)
            //
            TTSMessage.AddMessageData(TTS.MessageDataType.MessageToPeople, message_to_people);
            TTSMessage.AddMessageData(TTS.MessageDataType.MessageToAnswerPhones, message_to_answerphones);
            TTSMessage.AddMessageData(TTS.MessageDataType.CallRouteMessageToPeople, call_route_message_to_people);
            TTSMessage.AddMessageData(TTS.MessageDataType.CallRouteMessageToOperators, call_route_message_to_operators);
            TTSMessage.AddMessageData(TTS.MessageDataType.CallRouteMessageOnWrongKey, call_route_message_on_wrong_key);
            #endregion Submit Audio Files


            #region Add Keypads
            //
            // Add Keypad Method 1 - VoiceMessage.AddKeypad(int key, string keypad1_route);
            //
            TTSMessage.AddKeypad(1, keypad1_route);

            //
            // Add Keypad Method 2 - AddKeypad(new Keypad());
            //
            TTSMessage.AddKeypad(new Keypad(2, keypad2_route));

            //
            // Add Keypad Method 3 - AddKeypad with Play data
            //
            TTSMessage.AddKeypad(3, Keypad.KeypadType.Play, keypad3_play);

            //
            // Add Keypad Method 4 - AddKeypad(new List())
            //
            List keypad_list = new List();

            keypad_list.Add(new Keypad(4, keypad4_route));

            //
            // Add Keypad Method 5 - AddKeypad(new List()) using Keypad objects
            //
            Keypad keypad5 = new Keypad();
            keypad5.Tone = 5;
            keypad5.RouteNumber = keypad5_route;

            keypad_list.Add(keypad5);

            //
            // Add Keypad Method 6 - AddKeypad(new List()) with Play using Keypad objects
            //
            Keypad keypad6 = new Keypad();
            keypad6.Tone = 6;
            keypad6.Play = keypad6_play;

            keypad_list.Add(keypad6);

            //
            // Add Keypad Method 7 - AddKeypad(new List()) with RouteNumber and Play using Keypad objects
            //
            Keypad keypad7 = new Keypad();
            keypad7.Tone = 7;
            keypad7.Play = keypad7_play;
            keypad7.RouteNumber = keypad7_route;

            keypad_list.Add(keypad7);

            TTSMessage.AddKeypads(keypad_list);
            #endregion Add Keypads


            #region Add Recipients

            //
            // Add Recipient Method 1 - AddRecipient(string recipient);
            //

            TTSMessage.AddRecipient(recipient1);

            //
            // Add Recipient Method 2 - AddRecipient(new Recipient())
            //

            Recipient recipient = new Recipient(recipient2);
            recipient.CompanyName = "Test Company";         // Company Name
            recipient.Attention = "Test Recipient 2";       // Attention
            recipient.Custom1 = "Custom1";                  // Custom1
            recipient.Custom2 = "Custom2";                  // Custom2
            recipient.Custom3 = "Custom3";                  // Custom3
            recipient.Custom4 = "Custom4";                  // Custom4
            recipient.Custom5 = "Custom5";                  // Custom5

            TTSMessage.AddRecipient(recipient);

            //
            // Add Recipient Method 3 - AddRecipients(new List()); using simple destination
            //

            List recipients = new List();

            recipients.Add(new Recipient(recipient3));

            //
            // Add Recipient Method 4 - AddRecipients(new List()) using Recipient objects
            //

            recipients.Add(new Recipient(
                recipient4,              // Recipient
                "Test Company",         // Company Name
                "Test Recipient 4",     // Attention
                "Custom1",              // Custom1
                "Custom2",              // Custom2
                "Custom3",              // Custom3
                "Custom4",              // Custom4
                "Custom5"               // Custom5
            ));

            TTSMessage.AddRecipients(recipients);

            #endregion Add Recipients

            MessageResult response = TTSMessage.SendMessage(
                "",                     // MessageID - Leave blank to auto-generate
                reference,              // Reference
                new DateTime(),         // SendTime
                "New Zealand",          // Timezone
                billing_account,        // Billing Account (SubAccount)
                "",                     // Department
                "",                     // ChargeCode
                number_of_operators,    // No of Operators - Limits the maximum simultaneous calls
                caller_id,              // Caller ID
                tts_voice,              // Text-to-Speech voice to use (Male1, Female1, Female2, Female3, Female4)
                ""                      // Options
            );

            if (response.Result == MessageResult.ResultCode.Success)
            {
                Console.WriteLine("Success - " + response.MessageID);
            }
            else
            {
                Console.WriteLine("Error - " + response.ErrorMessage);
            }

            Console.ReadLine();
        }
    }
}
                                                
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(s) 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
WebhookCallbackURL https://www.example.com/webhook URL to receive webhooks
WebhookCallbackFormat JSON Format of webhooks (JSON or XML)
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)
ReportTo report@example.com For email (SMTP) message delivery report notifications.
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
> Play You pressed Keypad 1 Message played to B-Party when a keypad option is pressed
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)
RetryAttempts 3 Number of retry attempts if the recipients line is busy or unavailable
RetryPeriod 1 Minutes apart when performing retries
CallerID 6495005000 Sets the Caller ID used on the call (must be E.164 format)
TTSVoice TTSVoiceType.Female1 Text-to-Speech voice to use (Male1, Female1, Nicole, Russell, Amy, Brian, Emma)
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 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,
    TTS.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,
    TTS.TTSVoiceType tts_voice,
    string options
) 		Function to submit messages to TNZ REST API

Returns MessageResult object

Async Functions

Function Usage Description
SendMessageAsync() SendMessageAsync()

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

SendMessageAsync(
    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,
    TTS.TTSVoiceType tts_voice,
    string options
) 		Function to submit messages to TNZ REST API

Returns Task<IMessageResult> object

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. 


// For Email
EmailMessage.SendMode = Enums.SendModeType.Test;

// For SMS
SMSMessage.SendMode = Enums.SendModeType.Test;

// For Fax
FaxMessage.SendMode = Enums.SendModeType.Test;

// For Voice
VoiceMessage.SendMode = Enums.SendModeType.Test;

// For TTS
TTSMessage.SendMode = Enums.SendModeType.Test;

Edit Messages - Edit a submitted message

Once a message has been sent, you can retry a failed message, reschedule a delayed message, abort a delayed message and edit the NumberOfOperators value on Voice/TTS messages.


Retry Sending - Resubmit a failed message

If your message is 'Failed' (sending completed and was unsuccessful), you can use this API module to retry sending.

The Retry is applied to a specific MessageID. If you use common MessageID values across multiple messages, it will apply to the most recent message and only if the Status was Failed.


Set Resubmit:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Set;

namespace TNZSetResubmit
{
    class Program
    {
        static void Main(string[] args)
        {
            ResubmitRequest request = new ResubmitRequest();

            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";

            ResubmitRequestResult response = request.Submit();

            if (response.Result == ResubmitRequestResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + response.MessageID + "':");
                Console.WriteLine(" => Status: '" + response.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + response.JobNum + "'");
                Console.WriteLine(" => Action: '" + response.Action + "'");
            }
            else
            {
                Console.WriteLine("Cannot find MessageID '" + request.MessageID + "' : '" + response.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

Set Resubmit:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Set;

namespace TNZSetResubmit
{
    class Program
    {
        static void Main(string[] args)
        {
            ResubmitRequest request = new ResubmitRequest();

            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";

            ResubmitRequestResult response = request.Submit();

            if (response.Result == ResubmitRequestResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + response.MessageID + "':");
                Console.WriteLine(" => Status: '" + response.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + response.JobNum + "'");
                Console.WriteLine(" => Action: '" + response.Action + "'");
            }
            else
            {
                Console.WriteLine("Cannot find MessageID '" + request.MessageID + "' : '" + response.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

Set Resubmit:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Set;

namespace TNZSetResubmit
{
    class Program
    {
        static void Main(string[] args)
        {
            ResubmitRequest request = new ResubmitRequest();

            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";

            ResubmitRequestResult response = request.Submit();

            if (response.Result == ResubmitRequestResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + response.MessageID + "':");
                Console.WriteLine(" => Status: '" + response.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + response.JobNum + "'");
                Console.WriteLine(" => Action: '" + response.Action + "'");
            }
            else
            {
                Console.WriteLine("Cannot find MessageID '" + request.MessageID + "' : '" + response.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

ResubmitRequest 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
MessageID ID123456 MessageID the Action should apply to

ResubmitRequestResult object parameters

Parameter Type Example Value Description
ResultCode enum Success Types of ResultCode
Result ResultCode ResultCode.Success Result of your API call (not the result of the message)
StatusCode enum Transmit Types of StatusCode
Status Status Status.Transmit Current Status of your message
JobNum String ABCD1234 Your Job Number
Action String Resubmit What action (Resubmit) was requested
ErrorMessage String Missing Sender Reason for the API call failure (see a list of possible values: TNZ API Errors)



Reschedule Sending - Adjust the Delayed Sending Date/Time

If you have an existing Delayed message (scheduled for sending at a future date/time), you can use this API module to adjust the sending date/time.

The adjustment is applied to a specific MessageID. If you use common MessageID values across multiple messages, it will apply to the most recent message.


Set Reschedule:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Set;

namespace TNZSetReschedule
{
    class Program
    {
        static void Main(string[] args)
        {
            RescheduleRequest request = new RescheduleRequest();

            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";
            request.SendTime = DateTime.Parse("2021-12-31 12:00:00");

            RescheduleRequestResult result = request.Submit();

            if (result.Result == RescheduleRequestResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + result.MessageID + "':");
                Console.WriteLine(" => Status: '" + result.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + result.JobNum + "'");
                Console.WriteLine(" => Action: '" + result.Action + "'");
            }
            else
            {
                Console.WriteLine("Error occurred while processing MessageID '" + request.MessageID + "' : '" + result.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

Set Reschedule:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Set;

namespace TNZSetReschedule
{
    class Program
    {
        static void Main(string[] args)
        {
            RescheduleRequest request = new RescheduleRequest();

            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";
            request.SendTime = DateTime.Parse("2021-12-31 12:00:00");

            RescheduleRequestResult result = request.Submit();

            if (result.Result == RescheduleRequestResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + result.MessageID + "':");
                Console.WriteLine(" => Status: '" + result.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + result.JobNum + "'");
                Console.WriteLine(" => Action: '" + result.Action + "'");
            }
            else
            {
                Console.WriteLine("Error occurred while processing MessageID '" + request.MessageID + "' : '" + result.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

Set Reschedule:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Set;

namespace TNZSetReschedule
{
    class Program
    {
        static void Main(string[] args)
        {
            RescheduleRequest request = new RescheduleRequest();

            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";
            request.SendTime = DateTime.Parse("2021-12-31 12:00:00");

            RescheduleRequestResult result = request.Submit();

            if (result.Result == RescheduleRequestResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + result.MessageID + "':");
                Console.WriteLine(" => Status: '" + result.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + result.JobNum + "'");
                Console.WriteLine(" => Action: '" + result.Action + "'");
            }
            else
            {
                Console.WriteLine("Error occurred while processing MessageID '" + request.MessageID + "' : '" + result.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

RescheduleRequest 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
MessageID ID123456 MessageID the Action should apply to
SendTime 2020-05-12 14:05:00 Reschedule sending for the specified date/time (dd/mm/yyyy HH:mm in your Account/Sender's default timezone setting)

RescheduleRequestResult object parameters

Parameter Type Example Value Description
ResultCode enum Success Types of ResultCode
Result ResultCode ResultCode.Success Result of your API call (not the result of the message)
StatusCode enum Delayed Types of StatusCode
Status Status Status.Delayed Current Status of your message
JobNum String ABCD1234 Your Job Number
Action String Reschedule What action (Reschedule) was requested
ErrorMessage String Missing Sender Reason for the API call failure (see a list of possible values: TNZ API Errors)



Abort Sending - Cancel/Delete a Message from the Queue

If you have an existing Delayed message (scheduled for sending at a future date/time) you can use this API module to Cancel sending of the message.

The cancellation is applied to a specific MessageID. If you use common MessageID values across multiple messages, it will apply to the most recent message.


Set Abort:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Set;

namespace TNZSetAbort
{
    class Program
    {
        static void Main(string[] args)
        {     
            AbortRequest request = new AbortRequest();

            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";

            AbortRequestResult result = request.Submit();

            if (result.Result == AbortRequestResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + result.MessageID + "':");
                Console.WriteLine(" => Status: '" + result.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + result.JobNum + "'");
                Console.WriteLine(" => Action: '" + result.Action + "'");
            }
            else
            {
                Console.WriteLine("Error occurred while processing MessageID '" + request.MessageID + "' : '" + result.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

Set Abort:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Set;

namespace TNZSetAbort
{
    class Program
    {
        static void Main(string[] args)
        {     
            AbortRequest request = new AbortRequest();

            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";

            AbortRequestResult result = request.Submit();

            if (result.Result == AbortRequestResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + result.MessageID + "':");
                Console.WriteLine(" => Status: '" + result.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + result.JobNum + "'");
                Console.WriteLine(" => Action: '" + result.Action + "'");
            }
            else
            {
                Console.WriteLine("Error occurred while processing MessageID '" + request.MessageID + "' : '" + result.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

Set Abort:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Set;

namespace TNZSetAbort
{
    class Program
    {
        static void Main(string[] args)
        {     
            AbortRequest request = new AbortRequest();

            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";

            AbortRequestResult result = request.Submit();

            if (result.Result == AbortRequestResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + result.MessageID + "':");
                Console.WriteLine(" => Status: '" + result.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + result.JobNum + "'");
                Console.WriteLine(" => Action: '" + result.Action + "'");
            }
            else
            {
                Console.WriteLine("Error occurred while processing MessageID '" + request.MessageID + "' : '" + result.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

AbortRequest 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
MessageID ID123456 MessageID the Action should apply to

AbortRequestResult object parameters

Parameter Type Example Value Description
ResultCode enum Success Types of ResultCode
Result ResultCode ResultCode.Success Result of your API call (not the result of the message)
StatusCode enum Pending Types of StatusCode
Status Status Status.Pending Current Status of your message
JobNum String ABCD1234 Your Job Number
Action String Abort What action (Abort) was requested
ErrorMessage String Missing Sender Reason for the API call failure (see a list of possible values: TNZ API Errors)



Adjust NumberOfOperators - Change the Voice/Text-to-Speech NumberOfOperators Value

When sending a Voice/Text-to-Speech message, you may specify the NumberOfOperators value (limits the quantity of simultaneous/concurrent calls). You can use this API module to adjust the NumberOfOperators value in real-time.

The cancellation is applied to a specific MessageID. If you use common MessageID values across multiple messages, it will apply to the most recent message.


Change NumberOfOperators:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Set;

namespace TNZSetPacing
{
    class Program
    {
        static void Main(string[] args)
        {
            PacingRequest request = new PacingRequest();

            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";
            request.NumberOfOperators = 1;

            PacingRequestResult result = request.Submit();

            if (result.Result == PacingRequestResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + result.MessageID + "':");
                Console.WriteLine(" => Status: '" + result.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + result.JobNum + "'");
                Console.WriteLine(" => Action: '" + result.Action + "'");
            }
            else
            {
                Console.WriteLine("Error occurred while processing MessageID '" + request.MessageID + "' : '" + result.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

Change NumberOfOperators:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Set;

namespace TNZSetPacing
{
    class Program
    {
        static void Main(string[] args)
        {
            PacingRequest request = new PacingRequest();

            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";
            request.NumberOfOperators = 1;

            PacingRequestResult result = request.Submit();

            if (result.Result == PacingRequestResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + result.MessageID + "':");
                Console.WriteLine(" => Status: '" + result.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + result.JobNum + "'");
                Console.WriteLine(" => Action: '" + result.Action + "'");
            }
            else
            {
                Console.WriteLine("Error occurred while processing MessageID '" + request.MessageID + "' : '" + result.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

Change NumberOfOperators:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Set;

namespace TNZSetPacing
{
    class Program
    {
        static void Main(string[] args)
        {
            PacingRequest request = new PacingRequest();

            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";
            request.NumberOfOperators = 1;

            PacingRequestResult result = request.Submit();

            if (result.Result == PacingRequestResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + result.MessageID + "':");
                Console.WriteLine(" => Status: '" + result.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + result.JobNum + "'");
                Console.WriteLine(" => Action: '" + result.Action + "'");
            }
            else
            {
                Console.WriteLine("Error occurred while processing MessageID '" + request.MessageID + "' : '" + result.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

PacingRequest 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
MessageID ID123456 MessageID the Action should apply to
NumberOfOperators 4 NumberOfOperators value to apply

PacingRequestResult object parameters

Parameter Type Example Value Description
ResultCode enum Success Types of ResultCode
Result ResultCode ResultCode.Success Result of your API call (not the result of the message)
StatusCode enum Pending Types of StatusCode
Status Status Status.Pending Current Status of your message
JobNum String ABCD1234 Your Job Number
Action String Pacing What action (Pacing) was requested
ErrorMessage String Missing Sender Reason for the API call failure (see a list of possible values: TNZ API Errors)

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', '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
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.
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, Fax, Voice, 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", "FaxPages", "VoiceMinutes", "Size", "Prompts"
URL https://www.example.com/webhook The URL this webhook is sent to
RESPONSEMODE JSON This webhook's format


GET Status Poll - Track message statuses using a GET poll

You are able to poll for the status of a message via the GET Status API.

The Poll should be configured to timeout after 48 hours with no result.

Reference : TNZAPI.Messaging.Get

Get Status:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Get;

namespace TNZGetStatus
{
    class Program
    {
        static void Main(string[] args)
        {
            StatusRequest request = new StatusRequest();
            
            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";

            StatusRequestResult response = request.Poll();

            if (response.Result == StatusRequestResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + response.MessageID + "':");
                Console.WriteLine(" => Status: '" + response.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + response.JobNum + "'");
                Console.WriteLine(" => Account: '" + response.Account + "'");
                Console.WriteLine(" => SubAccount: '" + response.SubAccount + "'");
                Console.WriteLine(" => Department: '" + response.Department + "'");
                Console.WriteLine(" => Count: " + response.Count.ToString());
                Console.WriteLine(" => Complete: " + response.Complete.ToString());
                Console.WriteLine(" => Success: " + response.Success.ToString());
                Console.WriteLine(" => Failed: " + response.Failed.ToString());
            }
            else
            {
                Console.WriteLine("Cannot find MessageID '" + request.MessageID + "' : '" + response.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

Get Status:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Get;

namespace TNZGetStatus
{
    class Program
    {
        static void Main(string[] args)
        {
            StatusRequest request = new StatusRequest();
            
            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";

            StatusRequestResult response = request.Poll();

            if (response.Result == StatusRequestResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + response.MessageID + "':");
                Console.WriteLine(" => Status: '" + response.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + response.JobNum + "'");
                Console.WriteLine(" => Account: '" + response.Account + "'");
                Console.WriteLine(" => SubAccount: '" + response.SubAccount + "'");
                Console.WriteLine(" => Department: '" + response.Department + "'");
                Console.WriteLine(" => Count: " + response.Count.ToString());
                Console.WriteLine(" => Complete: " + response.Complete.ToString());
                Console.WriteLine(" => Success: " + response.Success.ToString());
                Console.WriteLine(" => Failed: " + response.Failed.ToString());
            }
            else
            {
                Console.WriteLine("Cannot find MessageID '" + request.MessageID + "' : '" + response.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

Get Status:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Get;

namespace TNZGetStatus
{
    class Program
    {
        static void Main(string[] args)
        {
            StatusRequest request = new StatusRequest();
            
            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";

            StatusRequestResult response = request.Poll();

            if (response.Result == StatusRequestResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + response.MessageID + "':");
                Console.WriteLine(" => Status: '" + response.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + response.JobNum + "'");
                Console.WriteLine(" => Account: '" + response.Account + "'");
                Console.WriteLine(" => SubAccount: '" + response.SubAccount + "'");
                Console.WriteLine(" => Department: '" + response.Department + "'");
                Console.WriteLine(" => Count: " + response.Count.ToString());
                Console.WriteLine(" => Complete: " + response.Complete.ToString());
                Console.WriteLine(" => Success: " + response.Success.ToString());
                Console.WriteLine(" => Failed: " + response.Failed.ToString());
            }
            else
            {
                Console.WriteLine("Cannot find MessageID '" + request.MessageID + "' : '" + response.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
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
MessageID ID123456 Your provided Message ID or TNZ Group generated Message ID

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


GET SMS Received Poll - Track SMS Received using a GET poll

You are able to poll for all received SMS messages in a given time-frame.

The Poll should be configured to timeout after 48 hours with no result.

Reference : TNZAPI.Messaging.Get

Get SMS Received:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Get;

namespace TNZ_Get_SMS_Received
{
    class Program
    {
        static void Main(string[] args)
        {
            SMSReceivedRequest sms_received = new SMSReceivedRequest();

            sms_received.Sender = "application@domain.com";
            sms_received.APIKey = "ta8wr7ymd";
            sms_received.TimePeriod = 1440;

            SMSReceivedResult sms_received_result = sms_received.Poll();

            if (sms_received_result.Result == SMSReceivedResult.ResultCode.Success)
            {
                Console.WriteLine("Inbound SMS Messages for the Time Period '" + sms_received.TimePeriod.ToString() + "':");

                foreach (SMSReceivedMessage received in sms_received_result.ReceivedMessages)
                {
                    Console.WriteLine("======================================");
                    Console.WriteLine(" => MessageReceived");
                    Console.WriteLine("    -> Date: '" + received.Date.ToString("yyyy-MM-dd hh:mm:ss") + "'");
                    Console.WriteLine("    -> From: '" + received.From + "'");
                    Console.WriteLine("    -> MessageText: '" + received.MessageText.Replace("'","\'") + "'");
                }

            }
            else
            {
                Console.WriteLine("Could not find any inbound sms messages for the time period '" + sms_received.TimePeriod.ToString() + "' : '" + sms_received_result.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

Get SMS Received:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Get;

namespace TNZ_Get_SMS_Received
{
    class Program
    {
        static void Main(string[] args)
        {
            SMSReceivedRequest sms_received = new SMSReceivedRequest();

            sms_received.Sender = "application@domain.com";
            sms_received.APIKey = "ta8wr7ymd";
            sms_received.TimePeriod = 1440;

            SMSReceivedResult sms_received_result = sms_received.Poll();

            if (sms_received_result.Result == SMSReceivedResult.ResultCode.Success)
            {
                Console.WriteLine("Inbound SMS Messages for the Time Period '" + sms_received.TimePeriod.ToString() + "':");

                foreach (SMSReceivedMessage received in sms_received_result.ReceivedMessages)
                {
                    Console.WriteLine("======================================");
                    Console.WriteLine(" => MessageReceived");
                    Console.WriteLine("    -> Date: '" + received.Date.ToString("yyyy-MM-dd hh:mm:ss") + "'");
                    Console.WriteLine("    -> From: '" + received.From + "'");
                    Console.WriteLine("    -> MessageText: '" + received.MessageText.Replace("'","\'") + "'");
                }

            }
            else
            {
                Console.WriteLine("Could not find any inbound sms messages for the time period '" + sms_received.TimePeriod.ToString() + "' : '" + sms_received_result.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

Get SMS Received:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Get;

namespace TNZ_Get_SMS_Received
{
    class Program
    {
        static void Main(string[] args)
        {
            SMSReceivedRequest sms_received = new SMSReceivedRequest();

            sms_received.Sender = "application@domain.com";
            sms_received.APIKey = "ta8wr7ymd";
            sms_received.TimePeriod = 1440;

            SMSReceivedResult sms_received_result = sms_received.Poll();

            if (sms_received_result.Result == SMSReceivedResult.ResultCode.Success)
            {
                Console.WriteLine("Inbound SMS Messages for the Time Period '" + sms_received.TimePeriod.ToString() + "':");

                foreach (SMSReceivedMessage received in sms_received_result.ReceivedMessages)
                {
                    Console.WriteLine("======================================");
                    Console.WriteLine(" => MessageReceived");
                    Console.WriteLine("    -> Date: '" + received.Date.ToString("yyyy-MM-dd hh:mm:ss") + "'");
                    Console.WriteLine("    -> From: '" + received.From + "'");
                    Console.WriteLine("    -> MessageText: '" + received.MessageText.Replace("'","\'") + "'");
                }

            }
            else
            {
                Console.WriteLine("Could not find any inbound sms messages for the time period '" + sms_received.TimePeriod.ToString() + "' : '" + sms_received_result.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
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
TimePeriod 1440 Return results from the last x minutes

SMSReceivedResult object parameters

Parameter Type Example Value Description
ResultCode enum Success Types of ResultCode
Result ResultCode ResultCode.Success Result of your API call (not the result of the message)
ReceivedMessages List<SMSReceivedMessage> SMSReceivedMessage List of SMS messages received
ErrorMessage String Missing Sender Reason for the API call failure (see a list of possible values: TNZ API Errors)

SMSReceivedMessage object parameters

Parameter Type Example Value Description
Date DateTime 2019-12-01 14:02:03 Date/Time SMS was received (yyyy-mm-dd HH:mm:ss)
From String +6421000001 Sender of the SMS in E.164 internationalised format
MessageText String This is a reply back from the mobile phone. The SMS message received


GET SMS Reply Poll - Track SMS replies using a GET poll

You are able to poll for replies to a specific SMS message, tracked using the MessageID on the outbound message.

The Poll should be configured to timeout after 48 hours with no result.

Reference : TNZAPI.Messaging.Get

Get SMS Reply:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Get;

namespace TNZGetSMSReply
{
    class Program
    {
        static void Main(string[] args)
        {
            SMSReplyRequest request = new SMSReplyRequest();

            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";

            SMSReplyResult response = request.Poll();

            if (response.Result == SMSReplyResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + response.MessageID + "':");
                Console.WriteLine(" => Status: '" + response.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + response.JobNum + "'");
                Console.WriteLine(" => Account: '" + response.Account + "'");
                Console.WriteLine(" => SubAccount: '" + response.SubAccount + "'");
                Console.WriteLine(" => Department: '" + response.Department + "'");
                Console.WriteLine("======================================");
                Console.WriteLine(" => MessageSent");
                Console.WriteLine("    -> Date: '" + response.SentMessage.Date.ToString("yyyy-MM-dd hh:mm:ss") + "'");
                Console.WriteLine("    -> Destination: '" + response.SentMessage.Destination + "'");
                Console.WriteLine("    -> MessageText: '" + response.SentMessage.MessageText + "'");

                foreach (SMSReceivedMessage received in response.ReceivedMessages)
                {
                    Console.WriteLine("======================================");
                    Console.WriteLine(" => MessageReceived");
                    Console.WriteLine("    -> Date: '" + received.Date.ToString("yyyy-MM-dd hh:mm:ss") + "'");
                    Console.WriteLine("    -> From: '" + received.From + "'");
                    Console.WriteLine("    -> MessageText: '" + received.MessageText + "'");
                }

            }
            else
            {
                Console.WriteLine("Cannot find MessageID '" + request.MessageID + "' : '" + response.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

Get SMS Reply:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Get;

namespace TNZGetSMSReply
{
    class Program
    {
        static void Main(string[] args)
        {
            SMSReplyRequest request = new SMSReplyRequest();

            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";

            SMSReplyResult response = request.Poll();

            if (response.Result == SMSReplyResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + response.MessageID + "':");
                Console.WriteLine(" => Status: '" + response.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + response.JobNum + "'");
                Console.WriteLine(" => Account: '" + response.Account + "'");
                Console.WriteLine(" => SubAccount: '" + response.SubAccount + "'");
                Console.WriteLine(" => Department: '" + response.Department + "'");
                Console.WriteLine("======================================");
                Console.WriteLine(" => MessageSent");
                Console.WriteLine("    -> Date: '" + response.SentMessage.Date.ToString("yyyy-MM-dd hh:mm:ss") + "'");
                Console.WriteLine("    -> Destination: '" + response.SentMessage.Destination + "'");
                Console.WriteLine("    -> MessageText: '" + response.SentMessage.MessageText + "'");

                foreach (SMSReceivedMessage received in response.ReceivedMessages)
                {
                    Console.WriteLine("======================================");
                    Console.WriteLine(" => MessageReceived");
                    Console.WriteLine("    -> Date: '" + received.Date.ToString("yyyy-MM-dd hh:mm:ss") + "'");
                    Console.WriteLine("    -> From: '" + received.From + "'");
                    Console.WriteLine("    -> MessageText: '" + received.MessageText + "'");
                }

            }
            else
            {
                Console.WriteLine("Cannot find MessageID '" + request.MessageID + "' : '" + response.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
Copy code

Get SMS Reply:


using System;

using TNZAPI.Messaging.Objects;
using TNZAPI.Messaging.Get;

namespace TNZGetSMSReply
{
    class Program
    {
        static void Main(string[] args)
        {
            SMSReplyRequest request = new SMSReplyRequest();

            request.Sender = "application@domain.com";
            request.APIKey = "ta8wr7ymd";
            request.MessageID = "ID123456";

            SMSReplyResult response = request.Poll();

            if (response.Result == SMSReplyResult.ResultCode.Success)
            {
                Console.WriteLine("Status of MessageID '" + response.MessageID + "':");
                Console.WriteLine(" => Status: '" + response.GetStatusString() + "'");
                Console.WriteLine(" => JobNum: '" + response.JobNum + "'");
                Console.WriteLine(" => Account: '" + response.Account + "'");
                Console.WriteLine(" => SubAccount: '" + response.SubAccount + "'");
                Console.WriteLine(" => Department: '" + response.Department + "'");
                Console.WriteLine("======================================");
                Console.WriteLine(" => MessageSent");
                Console.WriteLine("    -> Date: '" + response.SentMessage.Date.ToString("yyyy-MM-dd hh:mm:ss") + "'");
                Console.WriteLine("    -> Destination: '" + response.SentMessage.Destination + "'");
                Console.WriteLine("    -> MessageText: '" + response.SentMessage.MessageText + "'");

                foreach (SMSReceivedMessage received in response.ReceivedMessages)
                {
                    Console.WriteLine("======================================");
                    Console.WriteLine(" => MessageReceived");
                    Console.WriteLine("    -> Date: '" + received.Date.ToString("yyyy-MM-dd hh:mm:ss") + "'");
                    Console.WriteLine("    -> From: '" + received.From + "'");
                    Console.WriteLine("    -> MessageText: '" + received.MessageText + "'");
                }

            }
            else
            {
                Console.WriteLine("Cannot find MessageID '" + request.MessageID + "' : '" + response.ErrorMessage + "'");
            }

            Console.ReadLine();
        }
    }
}
                                          
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
MessageID ID123456 Your provided Message ID or TNZ Group generated Message ID

SMSReplyResult object parameters

Parameter Type Example Value Description
ResultCode enum Success Types of ResultCode
StatusCode enum Success Types of StatusCode
Result ResultCode ResultCode.Success Result of your API call (not the result of the message)
Status StatusCode StatusCode.Received Status of your job
MessageID String AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD Your provided Message ID or TNZ Group generated Message ID
JobNum String 10AB20CE Eight digit alphanumeric tracking number (our internal Job Number)
Account String 102030 Your TNZ Account
SubAccount String Your supplied TNZ SubAccount
Department String Your supplied TNZ Department
SentMessage SMSSentMessage SMSSentMessage Object Details of your sent message
ReplyMessages List<SMSReplyMessage> SMSReplyMessage Objects Details of your received message(s)
ErrorMessage String Missing Sender Reason for the API call failure (see a list of possible values: TNZ API Errors)

SMSSentMessage object parameters

Parameter Type Example Value Description
Date DateTime 2019-12-01 14:02:03 Date/Time SMS was received (yyyy-mm-dd HH:mm:ss)
Destination String 6421000001 Recipient of the SMS in E.164 internationalised format
MessageText String This is an outbound message sent via API. Plain or UTF-8 formatted SMS message sent

SMSReceivedMessage object parameters

Parameter Type Example Value Description
Date DateTime 2019-12-01 14:02:03 Date/Time SMS was received (yyyy-mm-dd HH:mm:ss)
From Text +6421000001 Sender of the SMS in E.164 internationalised format
MessageText Text This is a reply back from the mobile phone. The SMS message received

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.

What filetypes are supported for MessageType=Fax?

You can send a wide range of file types, including Microsoft Office® documents (doc, docx, ppt, pptx, xls, xlsx, etc), Openoffice/Libreoffice documents (odt, ods, etc), Adobe® documents (pdf, etc), image file types (jpg, gif, tif, bmp, etc) and more (txt, html, etc).

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.