Python Library Introduction

Using a single Python library, Python developers can send Email, SMS, Fax, Voice and Text-to-Speech messages using their own software.

Step 1: Register your account

If you don't have an account, you'll need to register one.

Learn more...

Step 2: Create a new API user token

You'll need a new Sender/APIKey combo for your application.

Learn more...

Step 3: Understanding the Python Library basics

This Python library is a helper library which submits messages in JSON format to TNZ REST API.

Learn more...

Step 4: Building your application with the base Python Library

You are required to download tnzapi and reference to your project(s).

Learn more...

Step 5: Adding variables to your MessageType

There are specific variables dedicated to each 'MessageType'. These are specified on a message-by-message basis.

Learn more...

Step 6: Delivery reporting and event tracking (Web Dashboard, Webhooks, Email reports)

Delivery Reports can be provided via a Webhook to your URL, Email, or viewed with the Web Dashboard.

Learn more...

Step 7: Resending and retrying messages

Submitted messages can be retried using the Web Dashboard, or by submitting a new DLL request.

Learn more...

Step 8: Sending messages in test mode

Specify the SendMode parameter in your message object to skip message delivery. The message will be accepted and processed with a simulated delivery result displayed.

Learn more...

Register your account

Head to https://www.tnz.co.nz/Customer/SignUp/ to create a new account.

A test account is possible, however creating a commercial account and using the SendMode=[MessageType].SendModeType.Test function of the library is simpler to use when you’re ready to push your application live.

After completing the sign up form, a sales consultant will manually activate your account. This may take one business day. Once the account has been activated, you will be able to Create a new API user token.

Create a new API user token

Using the API will require a Sender and APIKey pair to authenticate with the API.

You can generate this using the Web Dashboard under: Users | Outbound Users | Create
User Email Address = Sender
User Token = APIKey

Understanding the Python Library basics

Save hundreds of lines of code and hours of time by add the TNZ Python library into your project and sending messages via TNZ. Using one package and simple code tweaks, your software can send Email, SMS, Fax, Voice and Text-to-Speech messages.

Using the [request].SendMessage() function, the package will connect to TNZ's REST API (in JSON format) and submit messages.

Send Messages - build your application with the Python Library

Step 1: Download and 'tnzapi' using pip - pip install tnzapi, alternatively you can download package from tnzapi-1.0.5.1.zip

** You can find more information about TNZAPI Python Package.

Step 2: Reference the library in your code and start building!


from tnzapi import TNZAPI

MessageType=Email - Send Email via TNZ Python Library

Python

Basic Advanced

Send Email (Basic):


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",            # API Username
    APIKey="YOUR_API_KEY",                  # API Key
)

request = client.Send.Email(
    FromEmail = "from@test.com",            # Optional : Sets From Email Address - leave blank to use your api username as email sender
    EmailSubject = "Test Email",            # Email Subject
    MessagePlain = "Test Email Body",       # Email Body
    Recipients = ["email@test.com"]         # Email Recipients
)

response = request.SendMessage()            # Send Email

print(repr(response))                                                Download snippet

Send Email (Advanced):


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",
    APIKey="YOUR_API_KEY",
)

request = client.Send.Email()

request.MessageID   = "ID12345"             # Your custom MessageID
request.Reference   = "Test Email - Advanced version"

request.SMTPFrom    = "email@test.com"      # Sender SMTP From Address
request.From        = "Test Email"          # Sender Email Name
request.FromEmail   = "from@test.com"       # Sender Email Address
request.ReplyTo     = "reply@test.com"      # Set Reply To

request.EmailSubject    = "Test Email"
request.MessagePlain    = "Test Email Body"
request.MessageHTML     = "<html><body><p>This is <b>Test message body</b>. Thank you so much!</p></body></html>"

request.Recipients      = [
    {
        "Recipient": "email1@test.com",     # Recipient Email Address
        "Company": "Test Company",          # Company Name
        "Attention": "Test Recipient",      # Attention
        "Custom1": "Custom1",               # Custom Field
        "Custom2": "Custom2",
        "Custom3": "Custom3",
        "Custom4": "Custom4",
        "Custom5": "Custom5"
    },
    {
        "Recipient": "email2@test.com",     # Recipient Email Address
        "Company": "Test Company 2",        # Company Name
        "Attention": "Test Recipient 2",    # Attention
        "Custom1": "Custom1",               # Custom Field
        "Custom2": "Custom2",
        "Custom3": "Custom3",
        "Custom4": "Custom4",
        "Custom5": "Custom5"
    }
]

request.AddAttachment("C:\\File1.pdf")      # Add Attachment
request.AddAttachment("C:\\File2.pdf")      # Add Attachment

response = request.SendMessage()

print(repr(response))                                                Download snippet

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')
Recipients	recipient.two@example.com	Email address to receive the message (for detailed formatting, see the Destinations parameter below)

Optional Parameters

Parameter		Example Value	Description
MessageID		ID12345	Tracking ID or message description. Leave black if you want us to generate one.
Reference		Test1	Reference of your message
SendTime		new DateTime()	Delay sending until the specified date/time (YYYY-MM-DD HH:mm in your local timezone, specified by your Sender setting or overridden using the TimeZone command)
Timezone		New Zealand	Timezone specified using Windows timezone value (default set using Web Dashboard can be overridden here) See Microsoft Timezones (use the Country value)
SubAccount		SubAccount01	Used for reporting, billing and Web Dashboard segmentation
Department		Department01	Used for reporting, billing and Web Dashboard segmentation
ChargeCode		BillingGroup01	Cost allocation for billing
SMTPFrom		noreply@example.com	Sets the email Sender/Return-Path at the SMTP level (this address receives bounce-back emails and is used for SPF/DKIM type authentication; 'FromEmail' is used if not specified)
From		noreply	Sets the email sender's Friendly Name (seen by the email recipient)
FromEmail		noreply@example.com	Sets the email sender's Email Address (seen by the email recipient; API 'Sender' is used if not specified)
ReplyTo		reply@example.com	Sets the email sender's Reply-To Address (if the recipient replies, the Reply To will receive the reply)
MessageHTML		<html>Hello,<br /><br />This is a test message.<br /><br />Thank you.</html>	Content used for the message/html section of the email (overrides 'Template' and 'MessagePlain')
Recipients	> Recipient	recipient.one@example.com	Recipient of the email
	> Attention	Recipient One	Recipient's friendly name
	> Company	Example Corp	Recipient's company
	> Custom1	Recipient One	Customisable field
	> Custom2	Recipient One	Customisable field
Attachments	> Name	Sample.pdf	Attachment's filename
Attachments	> 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
AddAttachment()	AddAttachment(string file_location) AddAttachment(Attachment attachment)	Function to add a single attachment to the message (the Python library will grab the file contents from the specified file location)
SendMessage()	SendMessage()	Function to submit messages to TNZ REST API Returns MessageResult object

MessageType=SMS - Send SMS/TXT via Python

Python

Basic Advanced

Send SMS (Basic):


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Send.SMS(
    Reference = "Test",               # Optional
    MessageText = "Test SMS",         # SMS Message
    Recipients = ["+64211231234"]     # Recipient
)

response = request.SendMessage()      # Send SMS

print(repr(response))                                                Download snippet

Send SMS (Advanced):


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",                        # API Username
    APIKey="YOUR_API_KEY",                              # API Key
)

request = client.Send.SMS()

request.MessageID = "ID12345"                           # MessageID - Leave blank to auto-generate
request.Reference = "Test SMS - Advanced version"       # Reference
request.SMSEmailReply = "REPLY_EMAIL_ADDRESS"           # Email address to receive reply back

request.ForceGSMChars = True                            #  Convert multi-byte characters into normalised GSM character 
request.MessageText = "Test SMS Message for [[Attention]] at [[Company]]. Click [[File1]] | [[File2]] to download files."

request.Recipients      = [
    {
        "Recipient": "+64211231234",                    # Recipient Mobile Number
        "Company": "Test Company",                      # Company Name
        "Attention": "Test Recipient",                  # Attention
        "Custom1": "Custom1",                           # Custom Field
        "Custom2": "Custom2",
        "Custom3": "Custom3",
        "Custom4": "Custom4",
        "Custom5": "Custom5"
    },
    {
        "Recipient": "+64271231234",                    # Recipient Mobile Number
        "Company": "Test Company 2",                    # Company Name
        "Attention": "Test Recipient 2",                # Attention
        "Custom1": "Custom1",                           # Custom Field
        "Custom2": "Custom2",
        "Custom3": "Custom3",
        "Custom4": "Custom4",
        "Custom5": "Custom5"
    }
]

request.AddAttachment("C:\\File1.pdf")
request.AddAttachment("C:\\File2.pdf")

response = request.SendMessage()

print(repr(response))                                                Download snippet

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
Recipients	+6421000002	Mobile number to receive the message (for detailed formatting, see the Destinations parameter below)

Optional parameters

Parameter		Example Value	Description
MessageID		ID12345	Tracking ID or message description. Leave black if you want us to generate one.
Reference		Test1	Tracking ID or message description
SendTime		new DateTime()	Delay sending until the specified date/time (YYYY-MM-DD HH:mm in your local timezone, specified by your Sender setting or overridden using the TimeZone command)
TimeZone		New Zealand	Timezone specified using Windows timezone value (default set using Web Dashboard can be overridden here) See Microsoft Timezones (use the Country value)
SubAccount		SubAccount01	Used for reporting, billing and Web Dashboard segmentation
Department		Department01	Used for reporting, billing and Web Dashboard segmentation
ChargeCode		BillingGroup01	Cost allocation for billing
FromNumber		+6421000001	Setting SMS origination number, short code(s) will override in New Zealand - Not for New Zealand.
SMSEmailReply		person.one@domain.com	For email (SMTP) reply receipt notifications
ForceGSMChars		True	Convert multi-byte characters into normalised GSM character format. ie. © to (C)
Recipients	> Recipient	+6421000001	Recipient of the SMS in E.164 internationalised format (for localized or friendly formatting, contact your account manager)
	> Attention	Recipient One	Recipient's friendly name
	> Company	Example Corp	Recipient's company
	> Custom1	Recipient One	Customisable field
	> Custom2	Recipient One	Customisable field

Functions

Function	Usage	Description
AddRecipient()	AddRecipient(string recipient) AddRecipient(Recipient recipient)	Function to add a single message recipient
AddAttachment()	AddAttachment(string file_location) AddAttachment(Attachment attachment)	Function to add a single attachment to the message (the Python library will grab the file contents from the specified file location)
SendMessage()	SendMessage()	Function to submit messages to TNZ REST API Returns MessageResult object

MessageType=Fax - Send Fax via Python

Python

Basic Advanced

Send Fax (Basic):


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Send.Fax(
    Reference = "Test"                # Optional
    Recipients = ["+6491231234"],     # Fax Numbers
    Attachments = ["C:\\File1.pdf"]   # Fax Documents
)

response = request.SendMessage()      # Send Fax
  
print(repr(response))                                                Download snippet

Send Fax (Advanced):

from tnzapi import TNZAPI client = TNZAPI( Sender="YOUR_EMAIL_ADDRESS", # API Username APIKey="YOUR_API_KEY", # API Key ) request = client.Send.Fax() request.MessageID = "ID12345" # MessageID - Leave blank to auto-generate request.Reference = "Test Fax - Advanced version" # Reference request.Resolution = "High" # Resolution - High/Low request.CSID = "TEST FAX" # CSID request.RetryAttempts = 3 # RetryAttempts - no of retries request.RetryPeriod = 1 # RetryPeriod - no of minutes between retries request.Recipients = [ { "Recipient": "+6491231234", # Fax number "Company": "Test Company", # Company Name "Attention": "Test Recipient", # Attention "Custom1": "Custom1", # Custom Field "Custom2": "Custom2", "Custom3": "Custom3", "Custom4": "Custom4", "Custom5": "Custom5" }, { "Recipient": "+6471231234", # Fax number "Company": "Test Company 2", # Company Name "Attention": "Test Recipient", # Attention "Custom1": "Custom1", # Custom Field "Custom2": "Custom2", "Custom3": "Custom3", "Custom4": "Custom4", "Custom5": "Custom5" } ] request.AddAttachment("C:\\File1.pdf") # Add Fax Document request.AddAttachment("C:\\File2.pdf") response = request.SendMessage() # Send Fax print(repr(response))

Download snippet

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
Recipients		+6495005001	Fax number(s) to receive the message (for detailed formatting, see the Destinations parameter below)
Attachments	> Name	Sample.pdf	Fax document's filename
Attachments	> 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
SendTime		new DateTime()	Delay sending until the specified date/time (YYYY-MM-DD HH:mm in your local timezone, specified by your Sender setting or overridden using the TimeZone command)
Timezone		New Zealand	Timezone specified using Windows timezone value (default set using Web Dashboard can be overridden here) See Microsoft Timezones (use the Country value)
SubAccount		SubAccount01	Used for reporting, billing and Web Dashboard segmentation
Department		Department01	Used for reporting, billing and Web Dashboard segmentation
ChargeCode		BillingGroup01	Cost allocation for billing
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	Recipient One	Recipient's friendly name
	> Company	Example Corp	Recipient's company
	> Custom1	Recipient One	Customisable field
	> Custom2	Recipient One	Customisable field

Functions

Function	Usage	Description
AddRecipient()	AddRecipient(string recipient) AddRecipient(Recipient recipient)	Function to add a single message recipient
AddAttachment()	AddAttachment(string file_location) AddAttachment(Attachment attachment)	Function to add a single attachment to the message (the Python library will grab the file contents from the specified file location)
SendMessage()	SendMessage()	Function to submit messages to TNZ REST API Returns MessageResult object

MessageType=Voice - Send Voice via Python

C#

Basic Advanced

Send Voice (Basic):


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Send.Voice(
    Recipients = ["+6491231234"],     # Phone numbers to call
)

""" Message to play - WAV format, 16-bit, 8000hz recommended """
request.AddMessageData("MessageToPeople","D:\\voice.wav")

response = request.SendMessage()      # Send Voice Call

print(repr(response))                                                Download snippet

Send Voice (Advanced):

from tnzapi import TNZAPI client = TNZAPI( Sender="YOUR_EMAIL_ADDRESS", # API Username APIKey="YOUR_API_KEY", # API Key ) request = client.Send.Voice() request.MessageID = "ID12345" # MessageID - Leave blank to auto-generate request.Reference = "Test Voice - Advanced version" # Reference request.CallerID = "+6499999999" # Caller ID request.BillingAccount = "TEST BILLING ACCOUNT" # Billing Account (Sub Account) request.ReportTo = "report@example.com" # Email address to receive reports request.NumberOfOperators = 5 # No of Operators - Limits the maximum simultaneous calls request.RetryAttempts = 3 # No of retries request.RetryPeriod = 1 # Period between retries (minutes) # # Message to play when call answered - WAV format, 16-bit, 8000hz recommended # request.AddMessageData("MessageToPeople","C:\\message-to-people.wav") # # Message to play when answerphone detected - WAV format, 16-bit, 8000hz recommended # request.AddMessageData("MessageToAnswerPhones","C:\\message-to-answerphones.wav") # # Message to play when a keypad option is pressed - WAV format, 16-bit, 8000hz recommended # request.AddMessageData("CallRouteMessageToPeople","C:\\call-route-message-to-people.wav") # # Message to play when a all centre representative answering the connected call - WAV format, 16-bit, 8000hz recommended # request.AddMessageData("CallRouteMessageToOperators","C:\\call-route-message-to-operators.wav") # # Message to play when an unregistered keypad button is pressed - WAV format, 16-bit, 8000hz recommended # request.AddMessageData("CallRouteMessageOnWrongKey","C:\\call-route-message-on-wrong-key.wav") # # Adding Keypad options - WAV format, 16-bit, 8000hz recommended # request.AddKeypad(Tone=1,RouteNumber="+6491111111",PlayFile="C:\\key1-play-message.wav") request.AddKeypad(Tone=2,PlayFile="C:\\key2-play-message.wav") request.Recipients = [ { "Recipient": "+64211111111", # Recipient Phone Number "Custom1": "Custom1", # Custom Field "Custom2": "Custom2", "Custom3": "Custom3", "Custom4": "Custom4" }, { "Recipient": "+64212222222", # Recipient Phone Number "Custom1": "Custom1", # Custom Field "Custom2": "Custom2", "Custom3": "Custom3", "Custom4": "Custom4" } ] response = request.SendMessage() print(repr(response))

Download snippet

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.
Reference		Test1	Reference of your message
SendTime		new DateTime()	Delay sending until the specified date/time (YYYY-MM-DD HH:mm in your local timezone, specified by your Sender setting or overridden using the TimeZone command)
Timezone		New Zealand	Timezone specified using Windows timezone value (default set using Web Dashboard can be overridden here) See Microsoft Timezones (use the Country value)
BillingAccount		BillingAccount01	Used for reporting, billing and Web Dashboard segmentation (SubAccount)
Department		Department01	Used for reporting, billing and Web Dashboard segmentation
ChargeCode		BillingGroup01	Cost allocation for billing
ReportTo		report@example.com	Email address to receive reports when the job finished.
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
Recipients	> Recipient	+6495005000	Recipient of the call in E.164 internationalised format (for localized or friendly formatting, contact your account manager)
	> Custom1	Recipient One	Customisable field
	> Custom2	Recipient One	Customisable field
	> Custom3	Recipient One	Customisable field
	> Custom4	Recipient One	Customisable field

Functions

Function	Usage	Description
AddRecipient()	AddRecipient("+642711112222") AddRecipient(["+642711112222","+642133334444"])	Function to add a single message recipient
AddKeypad()	AddKeypad(Tone=1,PlayFile="C:\\1.wav", RouteNumber="+6495556666") AddKeypad(Tone=2,PlayFile="C:\\2.wav")	Function to add a keypad option (init tone=keypad button, route_number=number to divert the call to)
AddMessageData()	AddMessageData("MessageToPeople", "C:\\message.wav")	Function to add a WAV audio file to the message (the Python library will grab the file contents from the specified file location)
SendMessage()	SendMessage()	Function to submit messages to TNZ REST API Returns MessageResult object

MessageType=TTS - Send Text-To-Speech Calls via Python

Python

Basic Advanced

Send TextToSpeech (Basic):


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Send.TTS(
    Recipients = ["+6491231234"],     # Phone numbers to call
    MessageToPeople = "Hi there!"     # Message to play
)

response = request.SendMessage()      # Send Voice Call

print(repr(response))                                                Download snippet

Send TextToSpeech (Advanced):

from tnzapi import TNZAPI client = TNZAPI( Sender="YOUR_EMAIL_ADDRESS", # API Username APIKey="YOUR_API_KEY", # API Key ) request = client.Send.TTS() request.MessageID = "ID12345" # MessageID - Leave blank to auto-generate request.Reference = "Test TTS - Advanced version" # Reference request.CallerID = "+6499999999" # Caller ID request.BillingAccount = "TEST BILLING ACCOUNT" # Billing Account (Sub Account) request.ReportTo = "report@example.com" # Email address to receive reports request.NumberOfOperators = 10 # No of Operators - Limits the maximum simultaneous calls request.RetryAttempts = 3 # No of retries request.RetryPeriod = 1 # Period between retries (minutes) request.TTSVoiceType = "Female1" # TTS Voice Engine # # Message to play when call answered # request.MessageToPeople = "Hello, this is a call from Department01. This is relevant information. Press one to be connected to our call centre." # # Message to play when answerphone detected # request.MessageToAnswerPhones = "Hello, sorry we missed you. This is a call from Department 01. Please contact us on 0800 123123." # # Message to play when a keypad option is pressed # request.CallRouteMessageToPeople = "Connecting you now." # # Message to play when a all centre representative answering the connected call # request.CallRouteMessageToOperators = "Incoming Text To Speech call." # # Message to play when an unregistered keypad button is pressed # request.CallRouteMessageOnWrongKey = "Sorry, you have pressed an invalid key. Please try again." # # Adding Keypad options # request.AddKeypad(Tone=1,RouteNumber="+6491111111") request.AddKeypad(Tone=2,RouteNumber="+6492222222",Play="You pressed 1") request.Recipients = [ { "Recipient": "+64211111111", # Recipient Phone Number "Company": "Company 1", # Company "Attention": "Person 1", # Attention "Custom1": "Custom1", # Custom Field "Custom2": "Custom2", "Custom3": "Custom3", "Custom4": "Custom4" }, { "Recipient": "+64212222222", # Recipient Phone Number "Company": "Company 2", # Company "Attention": "Person 2", # Attention "Custom1": "Custom1", # Custom Field "Custom2": "Custom2", "Custom3": "Custom3", "Custom4": "Custom4" } ] response = request.SendMessage() print(repr(response))

Download snippet

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

Parameter		Example Value	Description
MessageID		ID12345	Tracking ID or message description. Leave black if you want us to generate one.
Reference		Test1	Reference of your message
SendTime		new DateTime()	Delay sending until the specified date/time (YYYY-MM-DD HH:mm in your local timezone, specified by your Sender setting or overridden using the TimeZone command)
Timezone		New Zealand	Timezone specified using Windows timezone value (default set using Web Dashboard can be overridden here) See Microsoft Timezones (use the Country value)
SubAccount		SubAccount01	Used for reporting, billing and Web Dashboard segmentation
Department		Department01	Used for reporting, billing and Web Dashboard segmentation
ChargeCode		BillingGroup01	Cost allocation for billing
ReportTo		report@example.com	Email address to receive reports when the job finished.
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 'Recipients' 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)
TTSVoiceType		Female1	Text-to-Speech voice to use (Male1, Female1, Nicole, Russell, Amy, Brian, Emma)
Options			Customisable field
Recipients	> Recipient	+6495005000	Recipient of the call in E.164 internationalised format (for localized or friendly formatting, contact your account manager)
	> Attention	Recipient One	Recipient's friendly name
	> Company	Example Corp	Recipient's company
	> Custom1	Recipient One	Customisable field
	> Custom2	Recipient One	Customisable field

Functions

Function	Usage	Description
AddRecipient()	AddRecipient("+642711112222") AddRecipient(["+642711112222","+642133334444"])	Function to add a single message recipient
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)
SendMessage()	SendMessage()	Function to submit messages to TNZ REST API Returns MessageResult object

Sending messages in test mode

Under request 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.


# Test mode
request.SendMode = "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.

Python

Set Resubmit:


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Set.Resubmit(
    MessageID="ID123456"              # MessageID generated from system OR your message ID if specified
)

response = request.SendRequest()

print(repr(response))
                                          Download snippet

Set Resubmit:


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Set.Resubmit(
    MessageID="ID123456"              # MessageID generated from system OR your message ID if specified
)

response = request.SendRequest()

print(repr(response))
                                          Download snippet

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	Example Value	Description
Result	Success	Result of your API call (not the result of the message)
Status	Transmit	Current Status of your message
JobNum	ABCD1234	Your Job Number
Action	Resubmit	What action (Resubmit) was requested
ErrorMessage	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.

Python

Set Reschedule:


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Set.Reschedule(
    MessageID="ID123456"              # MessageID generated from system OR your message ID if specified
    SendTime="2020-05-12 12:00:00"    # New Date/Time
)

response = request.SendRequest()

print(repr(response))
                                          Download snippet

Set Reschedule:


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Set.Reschedule(
    MessageID="ID123456"              # MessageID generated from system OR your message ID if specified
    SendTime="2020-05-12 12:00:00"    # New Date/Time
)

response = request.SendRequest()

print(repr(response))
                                          Download snippet

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 (YYYY-MM-DD HH:mm in your Account/Sender's default timezone setting)

RescheduleRequestResult object parameters

Parameter	Example Value	Description
Result	Success	Result of your API call (not the result of the message)
Status	Delayed	Current Status of your message
JobNum	ABCD1234	Your Job Number
Action	Reschedule	What action (Reschedule) was requested
ErrorMessage	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.

Python

Set Abort:


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Set.Abort(
    MessageID="ID123456",             # MessageID generated from system OR your message ID if specified
)

response = request.SendRequest()      # Abort Job

print(repr(response))                                          Download snippet

Set Abort:


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Set.Abort(
    MessageID="ID123456",             # MessageID generated from system OR your message ID if specified
)

response = request.SendRequest()      # Abort Job

print(repr(response))                                          Download snippet

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	Example Value	Description
Result	Success	Result of your API call (not the result of the message)
Status	Pending	Current Status of your message
JobNum	ABCD1234	Your Job Number
Action	Abort	What action (Abort) was requested
ErrorMessage	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.

Python

Change NumberOfOperators:


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Set.Pacing(
    MessageID="ID123456",             # MessageID generated from system OR your message ID if specified
    NumberOfOperators=1               # No of operators
)

response = request.SendRequest()      # Abort Job

print(repr(response))                                          Download snippet

Change NumberOfOperators:


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Set.Pacing(
    MessageID="ID123456",             # MessageID generated from system OR your message ID if specified
    NumberOfOperators=1               # No of operators
)

response = request.SendRequest()      # Abort Job

print(repr(response))                                          Download snippet

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	Example Value	Description
Result	Success	Result of your API call (not the result of the message)
Status	Pending	Current Status of your message
JobNum	ABCD1234	Your Job Number
Action	Pacing	What action (Pacing) was requested
ErrorMessage	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 provided as an HTTP POST in either XML or JSON format (your preference).

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
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 'YYYY-MM-DD 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"

GET Status Poll - Track message statuses using a GET poll

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

Reference : TNZAPI.Messaging.Get

Python

Get Status:


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Get.Status(
    MessageID="ID12345"               # MessageID generated from system OR your message ID if specified
)

response = request.Poll()

print(repr(response))
                                          Download snippet

Get Status:


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Get.Status(
    MessageID="ID12345"               # MessageID generated from system OR your message ID if specified
)

response = request.Poll()

print(repr(response))
                                          Download snippet

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 provided as an HTTP POST in either XML or JSON format (your preference).

Supplied parameters are:

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

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

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

Reference : TNZAPI.Messaging.Get

Python

Get Inbound SMS:


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Get.InboundSMS(
    TimePeriod = 1440                 # Return results from the last x minutes
)

response = request.Poll()

print(repr(response))
                                          Download snippet

Get SMS Received:


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Get.InboundSMS(
    TimePeriod = 1440                 # Return results from the last x minutes
)

response = request.Poll()

print(repr(response))
                                          Download snippet

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

InboundSMSResult object parameters

Parameter	Example Value	Description
Result	Success	Result of your API call (not the result of the message)
ReceivedMessages	InboundSMSMessage	List of SMS messages received
ErrorMessage	Missing Sender	Reason for the API call failure (see a list of possible values: TNZ API Errors)

InboundSMSMessage object parameters

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

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

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

Reference : TNZAPI.Messaging.Get

Python

Get SMS Received:


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Get.SMSReceived(
    MessageID="ID12345"               # MessageID generated from system OR your message ID if specified
)

response = request.Poll()

print(repr(response))
                                          Download snippet

Get SMS Received:


from tnzapi import TNZAPI

client = TNZAPI(
    Sender="YOUR_EMAIL_ADDRESS",      # API Username
    APIKey="YOUR_API_KEY",            # API Key
)

request = client.Get.SMSReceived(
    MessageID="ID12345"               # MessageID generated from system OR your message ID if specified
)

response = request.Poll()

print(repr(response))
                                          Download snippet

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

SMSReceivedResult object parameters

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

SMSSentMessage object parameters

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

SMSReceivedMessage object parameters

Parameter	Example Value	Description
Date	2019-12-01 14:02:03	Date/Time SMS was received (yyyy-mm-dd HH:mm:ss)
From	+6421000001	Sender of the SMS in E.164 internationalised format
MessageText	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.