ToucanText SMS APIs

All the code and resources you need to fully integrate SMS into your business applications. Start sending, receiving and tracking text messages today.

Getting started

  1. Sign up for a ToucanText account.
  2. Select how you want to connect to your service.

Select your programming language

We have created a set of libraries to allow you to integrate our API into your code in minutes.

C# Synchronous

Add the API

In C# you should add the following to any .cs files that need to use the API.
using ToucanText.Api.SenderApi;

Run the Code

To use the API create a new instance of the MessageSender(); object. Replace the user name and password with your Toucan API user name and password.
MessageSender messageSender = new MessageSender("userName", "password");

Parameters

userName
String The ToucanText user name as provided
password
String Your password as generated during sign up
sourceAddress
String Either an alphanumeric sender or an inbound number to use as the sender. Numbers should be specified in the format 441234567890 (note: + is not required)
destinationAddress
String The mobile number of the destination for the message. Numbers should be specified in the format 441234567890 (note: + is not required)
message
String The message content

Get the Code

To send a message use the SendMessage(); method. The sender address can be an alphanumeric or numeric (depending on the country).
MessageSender messageSender = new MessageSender("userName", "password");
messageSender.SendMessage("sourceAddress", "destinationAddress", "message");

ToucanText API Requirements

Target Application

The ToucanText .NET API requires a minimum of .NET Framework 4.5 or .NET Core 2.0 to operate.

C# Asynchronous

Add the API

In C# you should add the following to any .cs files that need to use the API.
using ToucanText.Api.SenderApi;

Run the Code

To use the API create a new instance of the MessageSender(); object. Replace the user name and password with your Toucan API user name and password.
MessageSender messageSender = new MessageSender("userName", "password");

Parameters

userName
String The ToucanText user name as provided
password
String Your password as generated during sign up
sourceAddress
String Either an alphanumeric sender or an inbound number to use as the sender. Numbers should be specified in the format 441234567890 (note: + is not required)
destinationAddress
String The mobile number of the destination for the message. Numbers should be specified in the format 441234567890 (note: + is not required)
message
String The message content

Get the Code

To send a message use the SendMessage(); method. The sender address can be an alphanumeric or numeric (depending on the country).
async public void SubmitPage(String c, String message)
{
MessageSender messageSender = new MessageSender("userName", "password");
var result = await messageSender.SendMessageAsync("sourceAddress", "destinationAddress", "message");
}

async private void button1_Click(object sender, EventArgs e)
{
MessageSender messageSender = new MessageSender("userName", "password");
var result = await messageSender.SendMessageAsync("sourceAddress", "destinationAddress","message");
}

ToucanText API Requirements

Target Application

The ToucanText .NET API requires a minimum of .NET Framework 4.5 or .NET Core 2.0 to operate.

HTTP API

The basic construct of our API is as follows.

Parameters

USERNAME
String The ToucanText user name as provided
PASSWORD
String Your password as generated during sign up
SOURCEADDR
String Either an alphanumeric sender or an inbound number to use as the sender. Numbers should be specified in the format 441234 567890 (note: + is not required)
DESTADDR
String The mobile number of the destination for the message. Numbers should be specified in the format 441234 567890 (note: + is not required)
MESSAGE
String The message content

Get the Code

The DESTADDR parameter should be the destination number to send the message to in the format cc = Country code and nnnnnnnnnn is the phone number (with the leading 0 removed if present) i.e. 447123456789
https://api.toucantext.com/bin/send.xml?USERNAME=apiusername&PASSWORD=apipassword&DESTADDR=ccnnnnnnnnnn&MESSAGE=messagecontent

Set the sender in a call

It is also possible to set the sender in a call, to do this you pass the SOURCEADDR in the URL. The SOURCEADDR can either be passed as a correctly formatted number (in the same format as the DESTADDR) or can be specified as alphanumeric text.
Numeric
https://api.toucantext.com/bin/send.xml?USERNAME=apiusername&PASSWORD=apipassword&SOURCEADDR=ccnnnnnnnnnn&DESTADDR=ccnnnnnnnnnn&MESSAGE=messagecontent
Alphanumeric
https://api.toucantext.com/bin/send.xml?USERNAME=apiusername&PASSWORD=apipassword&DESTADDR=alphanumerictext&MESSAGE=messagecontent

PHP SDK

This library requires a minimum PHP version of 5.5

Installation

To install the PHP client to your project, we recommend using Composer.
composer require toucantext/php-sdk

Instantiating the SDK Client

Pass in the configuration to the client:
$config = [
  'username' => '{your_api_username}',
  'password' => '{your_api_password}'
];

$toucan = new \ToucanText\Client($config);

Using the Client

Getting all messages To return a list of all your messages (both inbound and delivery receipts):
// return all your messages
$messages = $toucan->messages->all();
By default, this returns a maximum of 25 messages but does NOT acknowledge them. To override this, pass the following parameters (the first denotes whether to acknowledge messages; the second for the maximum number of messages to return):
// return 15 messages maximum and acknowledge them
$messages = $toucan->messages->all(true, 15);
Getting inbound messages or delivery receipts only To return a list of inbound messages or delivery receipts:
// return only inbound messages
$messages = $toucan->messages->get('messagesOnly');

// return only delivery receipts
$receipts = $toucan->messages->get('dlrsOnly');
By default, this returns a maximum of 25 inbound messages or delivery receipts but does NOT acknowledge them. To override this, pass the following parameters (the second denotes whether to acknowledge messages; the third for the maximum number of messages to return):
// return 15 inbound messages maximum and acknowledge them
$messages = $toucan->messages->get('messagesOnly', true, 15);

// return 15 delivery receipts maximum and acknowledge them
$receipts = $toucan->messages->get('dlrsOnly', true, 15);
Sending a message To send a message you, can call the following:
// send a message
$message = [
  'destinationAddress' => '{the_destination_address}',
  'message' => '{your_message}'
];

$toucan->messages->send($message);
You can also set a source address and request a delivery receipt:
// send a message with source address and request delivery receipt
$message = [
  'sourceAddress' => '{your_source_address}',
  'destinationAddress' => '{the_destination_address}',
  'message' => '{your_message}'
  'deliveryReceipt' => true
];

$toucan->messages->send($message);
Acknowledging delivery receipts and messages When you retrieve your inbound messages or delivery receipts, there is a MbStorageId element within the response of the query. This ID can be used to acknowledge messages and delivery receipts individually. To acknowledge a message or delivery receipt create an array with the ID's to acknowledge and then call the following:
// array of message ID's to acknowledge
$messages = [
  245, 4564, 456
];

$toucan->messages->acknowledge($messages);

Handling Exceptions

Aside from errors that may occur due to the call, there may be other Exceptions thrown. To handle them, wrap your call in a try catch block:
try {
$messages = $toucan->messages->all();
}  catch (\Exception $e) {
// do something with $e
}

VB.net Synchronous

Add the API

In VB.net you should add the following to any .cs files that need to use the API.

Imports ToucanText.Api.SenderApi

Run the Code

To use the API create a new instance of the MessageSender(); object. Replace the user name and password with your Toucan API user name and password.

Dim messageSender As MessageSender = new MessageSender("userName", "password")

Parameters

userName
String

The Toucan Text user name as provided

password
String

Your password as generated during sign up

sourceAddress
String

Either an alphanumeric sender or an inbound number to use as the sender. Numbers should be specified in the format 441234567890 (note: + is not required)

destinationAddress
String

The mobile number of the destination for the message. Numbers should be specified in the format 441234567890 (note: + is not required)

message
String

The message content

Get the Code

To send a message use the SendMessage(); method. The sender address can be an alphanumeric or numeric (depending on the country).

Dim messageSender As MessageSender = new MessageSender("userName", "password")
messageSender.SendMessage("sourceAddress", "destinationAddress", "message")

ToucanText API Requirements

Target Application

The ToucanText .NET API requires a minimum of .NET Framework 4.5 or .NET Core 2.0 to operate.

VB.net Asynchronous

Add the API

In VB.net you should add the following to any .cs files that need to use the API.
Imports ToucanText.Api.SenderApi

Run the Code

To use the API create a new instance of the MessageSender(); object. Replace the user name and password with your Toucan API user name and password.
Dim messageSender As MessageSender = new MessageSender("userName", "password")

Parameters

userName
String The ToucanText user name as provided
password
String Your password as generated during sign up
sourceAddress
String Either an alphanumeric sender or an inbound number to use as the sender. Numbers should be specified in the format 441234567890 (note: + is not required)
destinationAddress
String The mobile number of the destination for the message. Numbers should be specified in the format 441234567890 (note: + is not required)
message
String The message content

Get the Code

To send a message use the SendMessage(); method. The sender address can be an alphanumeric or numeric (depending on the country).
async public void SubmitPage(String c, String message)
{
MessageSender messageSender = new MessageSender("userName", "password")
var result = await messageSender.SendMessageAsync("sourceAddress", "destinationAddress", "message")
}

Async Sub button1_Click(sender As Object, e As EventArgs)
{
Dim messageSender As MessageSender = new MessageSender("userName", "password")
Response result = Await messageSender.SendMessageAsync("sourceAddress", "destinationAddress","message")
}

ToucanText API Requirements

Target Application

The ToucanText .NET API requires a minimum of .NET Framework 4.5 or .NET Core 2.0 to operate.

Premium SMS service for first-class developers

ToucanText provides a high-level of service that you should expect from an experienced, global provider.

Worldwide Reach

Our global network enables you to connect to over 7 billion people across 195 countries via 1600 direct-to-carrier and Tier 1 connections. ToucanText adheres to local rules using a global compliance engine.

2FA and Flash SMS

Provide two-factor authentication (2FA) via Flash SMS. Add a 2nd layer of security for remote access or login procedures – a One Time Password or SMS token, can easily be sent to mobiles via SMS.

Two-way SMS

Send SMS with low latency and high delivery rates. Benefit from inbound virtual numbers to allow customers to reply to messages, thus improving customer engagement and communication.

Why should you be using ToucanText?

With a wealth of expereince in a multitude of industries, a premium network service and a global outreach, ToucanText was established to help you reach your audience immediately.

About us