SMS Gateway

Reach any phone worldwide using our simple online SMS gateway platform.

Matrix SMS Gateway for group messaging provides your business a hosted messaging platform to add SMS capability to any system, application or website.
We deliver the direct capability to send SMS, Voice and Text-to-Speech messages from any application.

How our SMS Gateway can help you:

Our gateway delivers SMS, Voice and Text-to-Speech to more than 200 countries worldwide.
Integration with various front-end and legacy systems is achieved via a set of simple and easy to use APIs (Application Programming Interface) interfaces.
Our APIs offer you a choice of connection options (HTTP, HTTPS, SMTP) that are flexible and easy to implement and that will fit to pretty much any kind of usage.
Very easy to access and user-friendly web based GUI provides users with functionality to do reporting, make online payments, add sub-users and more.
On top of the SMS delivery, Matrix gateway also provides Voice and Text-to-Speech messaging functionality.
Your application will be able to communicate with the outside world using all media known to humanity, and through one, consistent API.
Source code scripts that show how to use gateway's API are available from our website, and they cover several most popular programming languages.
API specification documentation is also available.
Take a look at the complete list of SMS Matrix API functions.
Text messages in unicode (utf-8) are supported, as long as wireless carrier and phone receiver support given language.
When unicode is used, most of Asian languages are supported, including Chinese.
Technical Support for the SMS Gateway is available at this email address: support@smsmatrix.com

So far, access to Matrix SMS Gateway has been successfully implemented and tested with the following programming languages:
Node.js, JavaScript, PHP, Perl, Java, C#, Python, C, C++, VB, .Net, etc..
If in doubt, please refer to Perl examples, as they are the most complete and were the most thoroughly tested.

The following Gateway API functions are provided:

Send SMS message
Send TTS (Text-to-Speech) message
Send Voice message (with voice file data)
Send Voice message (with voice file url)
Query message's status
Lookup cellular carrier for given cell phone number
Query account's balance
Query message rate (fee)
SMTP gateway for SMS/VOICE/TTS delivery

SMTP/Email Gateway functionality:

Send SMS message
Send TTS (Text-to-Speech) message
Send Voice message (with voice file url)

PDF Version - Matrix SMS Gateway Developer's Guide

September 2014 update:

We have a new JSON based API under development.
Existing API described below will be still supported, however all new developers are encouraged to use new JSON based one.

SMS Gateway API - JSON

Technical Information:

Each message sent through our system will have unique ID assigned.
This ID is returned to the caller when new message is submitted, and later, a query can be submitted with this ID to check on the status of this message.
Unicode message format for non-English languages is supported for SMS delivery.
Text-to-Speech - list of supported languages available at the end of this page.
Both: HTTP and HTTPS protocols are supported for all communication with SMS Matrix servers.

Capturing Recipient's Response

It is possible to send voice or text-to-speech message, that would ask the recipient to make a choice by pressing a number on the dial.
For instance, a dentist would like to send a message - appointment reminder:

"Hello, this is dentist Adam Smith. Press 1 to confirm your appointment tomorrow at 9am,
or press 2 to cancel the appointment.
Press 9 to repeat this message."

Or a car serviceman wants to ask if his customers are happy:

"Hello, this is your Citroen Service in Cleveland.
You visited us last week. We would like to know if were happy with the service we provided.
Press 1 if you were happy, or press 2 if you were not.
Press 9 to repeat this message."

The recipient would listen to the message, and then press 1, or 2, or 9.
The number pressed, will later show up in the message status, so it will be easy for the sender to see recipient's response.

If 'response' field is set to 1, the system will deliver voice or TTS message, and it will wait and capture recipient's response.
If 'response' field is not set, no response will be expected nor captured.

'9' is always reserved for the 'repeat this message', so do not use it for other purposes.

When sender checks the status of the message in the 'History', the status of the message will include the information what key (digit) was pressed by the recipient.
Example of the message status:

"Voice call answered, duration 18 seconds. R = 1"

It means that recipient pressed '1' in a response to the message (e.g. appointment was confirmed).

Examples of the usage of SMS Gateway API, in several programming languages:

SMS Gateway - Send SMS - HTTP Post : Perl Example

##################################################
## Example of using SMS Matrix HTTP API in Perl

use LWP::UserAgent;
use HTTP::Request::Common;

my $TXT = 'This is a test, pls ignore';

my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
 POST 'http://www.smsmatrix.com/matrix',
 Content_Type  => 'application/x-www-form-urlencoded',
 Content       => [ 'username' => 'user888@yahoo.ca',
                    'password' => 'pass7782',
                    'callerid' => '12501231233', # optional (for 2-way sms)
                    'phone' => '12506063167',
                    'tts' => 1, # optional for TTS fallback
                    'txt' => $TXT ]
);

if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response: " . $res->content . "\n\n";

SMS Gateway - Send SMS to a group: Perl Example

use LWP::UserAgent;
use HTTP::Request::Common;

my $TXT = 'This is a test, pls ignore';

my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
 POST 'http://www.smsmatrix.com/matrix',
 Content_Type  => 'application/x-www-form-urlencoded',
 Content       => [ 'username' => 'user888@yahoo.ca',
                    'password' => 'pass7782',
                    'callerid' => '12501231233', # optional (for 2-way sms)
                    'group' => 'Test_Group',
                    'txt' => $TXT ]
);

if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response: " . $res->content . "\n\n";

SMS Gateway - Check Message Status (HTTP) : Perl Example

use LWP::UserAgent;
use HTTP::Request::Common;

my $URL = 'http://www.smsmatrix.com/matrix_status';
my $USERNAME = 'user@hotmail.com';
my $PASSWORD = 'pass72727';
my $MSGID = 'a876f1267536589be789effa879';

my $q = "username=$USERNAME&password=$PASSWORD&id=$MSGID";

my $ua = new LWP::UserAgent;
my $req = new HTTP::Request 'POST', $URL;
$req->content_type ('application/x-www-form-urlencoded');
$req->content ($q);
my $res = $ua->request ($req);

if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response: " . $res->content . "\n\n";

SMS Gateway - Send Text-To-Speech message: Perl Example

use LWP::UserAgent;
use HTTP::Request::Common;

my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
 POST 'http://www.smsmatrix.com/matrix_tts',
 Content_Type  => 'application/x-www-form-urlencoded',
 Content       => [ 'username' => 'user@hotmail.com',
                    'password' => 'password',
                    'phone' => '12506063167',
                    'repeat'   => 1,          ## Optional (default is 0)
                    'gender' => 'male',       ## Optional, 'female' is default
                    'language' => 'us',       ## Optional ('us' is default, see list of languages at the end of this page)
                    'response'  => 0,         ## Optional, set to 1 if recipient's response needed
                    'txt' => 'Adam, web server is down' ]
);

if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response: " . $res->content . "\n\n";

SMS Gateway - Send Text-To-Speech message in non-ASCI language: Perl Example

use LWP::UserAgent;
use HTTP::Request::Common;

my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
 POST 'http://www.smsmatrix.com/matrix_tts',
 Content_Type  => 'application/x-www-form-urlencoded',
 Content       => [ 'username' => 'user@hotmail.com',
                    'password' => 'password',
                    'phone' => '12506063167',
                    'repeat'   => 1,          ## Optional (default is 0)
                    'gender' => 'male',       ## Optional, 'female' is default
                    'language' => 'ch',       ## Mandarin
                    'response'  => 0,         ## Optional, set to 1 if recipient's response needed
                    'txt' => '濞变箰鏃跺皻銆佷骇涓氳祫璁€佸疄' ]
);

if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response: " . $res->content . "\n\n";

SMS Gateway - Query Message Rate : Perl Example

use LWP::UserAgent;
use HTTP::Request::Common;

my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
 POST 'http://www.smsmatrix.com/sms_rate',
 Content_Type  => 'application/x-www-form-urlencoded',
 Content       => [ 'phone' => '12506058145' ]
);

if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response: " . $res->content . "\n\n";

SMS Gateway - Send SMS - HTTP Post : PHP Example

<?php
$URL = 'http://www.smsmatrix.com/matrix';
$PHONE = '12506063167'; // comma separated list of phone numbers
// $PHONE = '12506063167,12508763211';
$USERNAME = urlencode ('user@hotmail.com');
$PASSWORD = urlencode ('pass72727');
$TXT = urlencode ('This is a test, pls ignore');

$Q = "$URL?username=$USERNAME&password=$PASSWORD&phone=$PHONE&txt=$TXT";

$res = implode ('', file ($Q));
echo "Matrix API Response :\n$res\n";
?>

SMS Gateway - Send SMS - HTTP Post : Java Example

try
{
 String MATRIXURL = "http://www.smsmatrix.com/matrix";
 String PHONE = "12506063167";
 String USERNAME = "user@hotmail.com";
 String PASSWORD = "pass72727";
 String TXT = "This is a test, pls ignore";

 String q = "username=" + URLEncoder.encode (USERNAME, "UTF-8");
 q += "&" + "password=" + URLEncoder.encode (PASSWORD, "UTF-8");
 q += "&" + "phone=" + PHONE;
 q += "&" + "txt=" + URLEncoder.encode (TXT, "UTF-8");

 URL url = new URL (MATRIXURL);
 URLConnection conn = url.openConnection();
 conn.setDoOutput (true);
 OutputStreamWriter wr = new OutputStreamWriter (conn.getOutputStream());
 wr.write (q);
 wr.flush();
    
 BufferedReader rd = new BufferedReader (new InputStreamReader (conn.getInputStream()));
 String line;
 System.out.println ("Matrix API Response :");
 while ((line = rd.readLine()) != null) { System.out.println (line); }
 wr.close();
 rd.close();
} catch (Exception e) { }

SMS Gateway - Send SMS - HTTP Post : C# Example

string MATRIXURL = "http://www.smsmatrix.com/matrix";
string PHONE = "12506063167";
string USERNAME = Server.UrlEncode ("user@hotmail.com");
string PASSWORD = Server.UrlEncode ("pass72727");
string TXT = Server.UrlEncode ("This is a test, pls ignore");

string q = "username=" + USERNAME +
 "&password=" + PASSWORD +
 "&phone=" + PHONE +
 "&txt=" + TXT;

HttpWebRequest req = (HttpWebRequest)WebRequest.Create (MATRIXURL);
req.Method = "POST";
req.ContentType = "application/x-www-form-urlencoded";
req.ContentLength = q.Length;

StreamWriter streamOut = new StreamWriter(req.GetRequestStream(), System.Text.Encoding.ASCII);
streamOut.Write (q);
streamOut.Close();

StreamReader streamIn = new StreamReader(req.GetResponse().GetResponseStream());
string res = streamIn.ReadToEnd();
Console.WriteLine ("Matrix API Response:\n" + res);
streamIn.Close();

SMS Gateway - Carrier Lookup : Perl Example

List of cellular carriers supported by Lookup function

use LWP::UserAgent;
use HTTP::Request::Common;

my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
 POST 'http://www.smsmatrix.com/carrier',
 Content_Type  => 'application/x-www-form-urlencoded',
 Content       => [ 'username' => 'user@yahoo.ca',
                    'password' => 'password9999',
                    'phone' => '12506063167']
);

if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response: " . $res->content . "\n\n";

SMS Gateway - Get Account's Balance : Perl Example

use LWP::UserAgent;
use HTTP::Request::Common;

my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
 POST 'http://www.smsmatrix.com/balance',
 Content_Type  => 'application/x-www-form-urlencoded',
 Content       => [ 'username' => 'user@yahoo.ca',
                    'password' => 'password' ]
);

if ($res->is_error) { die "HTTP Error\n"; }

print "Matrix API Response: " . $res->content . "\n\n";

SMTP gateway for SMS/TTS/VOICE delivery

For users (developers) that don't have a need or possibility to integrate their software with our SMS Gateway directly, SMS Matrix provides easy to use option: SMS, Voice and TTS message delivery via SMTP.
If text (not HTML) email is sent to gateway@smsmatrix.com email address, it will be further processed by our SMS Gateway, and premium SMS, Voice or TTS (Text-to-Speech) message will be delivered as a result.
Note: content-type MUST be set like this: "Content-Type: text/plain"

SMS Message via SMTP:

username:user78@hotmail.com
password:mypass883
phone:12501238585
callerid:13451238585
sms:Hello Adam, this is a test, please ignore.

TTS Message via SMTP:

username:user78@hotmail.com
password:mypass883
phone:16301238534
callerid:13451238585
language:us
gender:male
tts:Hello John, This is Adam, please call me back.

TTS Message via SMTP:

username:user78@hotmail.com
password:mypass883
phone:16301238534
callerid:13451238585
gender:female
language:uk
response:1
tts:Hello, this is your dentist Joan Smith. You have appointment scheduled for Tuesday at 9am.
Press 1 confirm it, or press 2 cancel it. Press 9 to replay this message.

VOICE Message via SMTP:

username:user78@hotmail.com
password:mypass883
phone:16301238534
voiceurl:http://www.myweb.ca/sounds/welcome.wav

Keywords (username,password,phone,sms,tts) in these emails ARE CASE SENSITIVE, and must be typed in lowercase - just like in the examples above.
Optionally, 'response' field can be added to voice and TTS messages. 'callerid' field is optional.
The message (sms/tts fields) must be written in one line of text, no newline characters are allowed.

Voice Gateway - Send Voice Message : Perl Example

use LWP::UserAgent;
use HTTP::Request::Common;

# The voice file provided must be in mp3 or wave format.
# It will be converted to: 16Bit 8kHz mono wave format.

my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
 POST 'http://www.smsmatrix.com/matrix_voice',
      Content_Type => 'form-data',
      Content      => [ username  => 'user@hotmail.com',
                        password  => 'pass8988',
                        phone     => '12502771720',  ## comma delimited list
                        voicefile => ['/tmp/november_sale.wav'],
                        response  => 1,  ## optional
                        callerid  => '16307791722'  ## optional
                      ]
);

if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response1: " . $res->content . "\n\n";

Voice Gateway - Send Voice Message by URL: Perl Example

use LWP::UserAgent;
use HTTP::Request::Common;

my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
 POST 'http://www.smsmatrix.com/matrix_voicew',
      Content      => [ username  => 'user@hotmail.com',
                        password  => 'pass8988',
                        phone     => '12502771720',  ## comma delimited list
                        voiceurl  => 'http://www.myweb.de/s/welcome.mp3',
                        response  => 0,  ## optional
                        callerid  => '16307791722'  ## optional
                      ]
);

if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response1: " . $res->content . "\n\n";

Voice/TTS Gateway - Send Combined: Voice plus TTS Message: Perl Example

use LWP::UserAgent;
use HTTP::Request::Common;
use JSON();

my $msg =
{
 username => 'user55@hotmail.com',
 password => 'mypass',
 phone    => '12502012503',    # comma delimited list
 language => 'us',             # optional, see list of supported languages
 gender   => 'male',           # optional
 callerid => '12501112233',    # optional
 response => 0,                # optional
 msg      => [ 'http://www.myserver.com/voices/welcome_prompt.wav',
               'This text will be converted to voice by TTS engine.',
               'http://www.myserver.com/voices/segment2.mp3' ]
};
my $ua = new LWP::UserAgent;
my $res = $ua->request
(
 POST 'http://www.smsmatrix.com/matrix_vtts',
      Content_Type => 'application/json',
      Content      => JSON::to_json ($msg)
);
if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response:\n" . $res->content . "\n\n";

Fax Gateway - Send Fax: Perl Example

use LWP::UserAgent;
use HTTP::Request::Common;

my $ua  = new LWP::UserAgent;
my $res = $ua->request
(
 POST 'http://www.smsmatrix.com/matrix_fax',
      Content_Type => 'form-data',
      Content      => [ username  => 'andywu@apples.mx',
                        password  => 'ibl0w',
                        phone     => '16053537141',
                        file      => ['/tmp/my_fax.pdf']
                      ]
);
if ($res->is_error) { die "HTTP Error\n"; }
print "Matrix API Response:\n" . $res->content . "\n\n";

Incoming SMS (Virtual Mobile Phone Number)

For all incoming SMS messages (when using virtual mobile phone number feature), and for all Voice or TTS messages responses,
our system can submit HTTP POST to an URL associated with the number.

The following data will be submitted:

phonefrom  : phone number of the sender
phoneto    : virtual phone number
id         : unique alphanumerical ID
orgserver  : our hostname (usually www.smsmatrix.com)
timestamp  : UNIX timestamp (GMT)
txt        : body of the SMS (or TTS/Voice response)
smsin      : 1 (always set to 1 for incoming SMS messages)
voiceresp  : 1 (always set to 1 for TTS/Voice responses)

Either 'smsin' or 'voiceresp' variables are present and set to 1, not both.

Here is an example of a Perl script that can handle incoming SMS messages:


use CGI;

print "Content-Type: text/plain\n\n";
my $query = new CGI;
my $phonefrom = $query->param ('phonefrom');
my $phoneto   = $query->param ('phoneto');
my $sms       = $query->param ('txt');

print "Received new SMS from $phone, text: $sms\n";

Similar scripts can be implemented in virtually any programming language.

Retrieve CSV report (message History)

Making a GET or POST HTTP request to this URL:

http://www.smsmatrix.com/csv_report

and providing the following parameters:

email       required
password    required
top         optional (number of records you want to get, e.g. 100)
in_only     optional (1 or 0, 1 if you want to get incoming messages only)

Example:

http://www.smsmatrix.com/csv_report?email=adam@yahoo.com&password=1234&top=10

SMS Gateway - Error Codes

The following numerical values are returned as statuscode field:

200 - OK

404 - ACCOUNT OR USER DOES NOT EXIST
500 - ERROR
502 - PIN IN DO NOT CALL DATABASE
503 - INSUFFICIENT BALANCE
504 - DATABASE ERROR
505 - USER NOT FOUND OR WRONG PASSWORD
506 - ACCOUNT NOT ACTIVE
507 - DATABASE ERROR
508 - DATABASE ERROR
510 - INVALID USERNAME
511 - INVALID TXT
512 - INVALID PASSWORD
513 - INVALID PIN
514 - NO VOICE FILE PROVIDED
520 - ERROR PARSING XML

All values from 0 - 399 (inclusive) mean success, all other values mean failure.

SMS Gateway - Languages supported by TTS

us    - US English
en    - US English
uk    - UK English
jp    - Japanese
ch    - Mandarin
it    - Italian
es    - Spanish
fr    - French
de    - German
pl    - Polish
fi    - Finnish
arabic - Arabic
ro    - Romanian
no    - Norwegian
tr    - Turkish
sw    - Swedish
gr    - Greek
pt    - Portuguese
ptb   - Portuguese Brazilian

All languages support male/female voice (gender variable in HTTP post)

Email:
Password:
Forgot password?