![]() |
Using a single Python library, Python developers can send Email, SMS, Fax, Voice and Text-to-Speech messages using their own software.
SendMode
parameter in your message object to skip message delivery. The message will be accepted and processed with a simulated delivery result displayed. Head to https://www.tnz.co.nz/Customer/SignUp/ to create a new account.
A test account is possible, however creating a commercial account and using the SendMode=[MessageType].SendModeType.Test function of the library is simpler to use when you’re ready to push your application live.
After completing the sign up form, a sales consultant will manually activate your account. This may take one business day. Once the account has been activated, you will be able to Create a new API user token.
Using the API will require a Sender and APIKey pair to authenticate with the API.
You can generate this using the Web Dashboard under: Users | Outbound Users | Create
User Email Address = Sender
User Token = APIKey
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.
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
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))
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))
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) |
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 |
> Data | %%Base-64%% | Base-64 encoded value of the attached file |
Function | Usage | Description | |
---|---|---|---|
AddRecipient() |
AddRecipient(string recipient) AddRecipient(Recipient recipient) |
Function to add a single message recipient | |
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 |
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))
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))
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) |
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 |
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 |
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))
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))
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 |
> Data | %%Base-64%% | Base-64 encoded value of the document |
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 |
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 |
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))
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))
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) |
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 |
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 |
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))
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))
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) |
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 |
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 |
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"
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.
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.
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))
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))
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 |
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) |
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.
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))
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))
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) |
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) |
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.
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))
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))
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 |
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) |
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.
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))
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))
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 |
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) |
Delivery Reports advise whether delivery was successful. If not, it will describe why.
Each delivery report type is optional and multiple delivery report types can be used.
You will be supplied with a Web Dashboard login at registration. The Dashboard can be used to set up new sender/token pairs, as well as track sent and replied messages. You can drill into specific messages to view individual events, such as delivery attempts, retries, replies, results, clicks, etc.
Delivery reports are emailed as an HTML email for viewing by an end-user. Your sales representative can enable this for you.
Whitelabelling of SMTP Email reports is available.
The email address to receive SMS Reply reports can be specified on the original message submission using the SMSEmailReply
parameter.
To receive Delivery Reports via Webhook, please advise the URL to submit to.
Webhooks are 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" |
API users are able to poll for the status of a message via the GET Status API.
Reference : TNZAPI.Messaging.Get
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))
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))
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 |
Currently, tracking SMS Received is supported.
Tracking of faxes and voicemail received is scheduled for a future release. Let your account manager know if this interests you.
You will be supplied with a Web Dashboard login at registration. The Dashboard can be used to set up new sender/token pairs, as well as track sent and replied messages. You can drill into specific messages to view individual events, such as delivery attempts, retries, replies, results, clicks, etc.
Delivery reports are emailed as an HTML email for viewing by an end-user. Your sales representative can enable this for you.
Whitelabelling of SMTP Email reports is available.
When submitting SMS messages, specify the SMSEmailReply
parameter.
If you are set up to receive Status webhooks, you will also be receiving SMS Received webhooks.
To receive SMS replies via Webhook, please advise the URL to submit to.
Webhooks are 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) |
API users are able to poll for all received SMS messages in a given time-frame.
Reference : TNZAPI.Messaging.Get
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))
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))
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 |
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) |
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 |
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
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))
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))
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 |
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) |
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 |
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 |
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