SMS Gateway

In addition to our web (GUI) based SMS/Voice messaging platform, we also offer bulk SMS Gateway.
Matrix SMS Gateway provides an easy way to integrate SMS, Voice and TTS capabilities with your IT system, be it a simple website or a complex bulk messaging or alerting system. It allows to deliver SMS, TTS and Voice messages to phone numbers around the world. SMS Matrix provides worldwide coverage.

SMS Matrix Gateway is extremely reliable and developer friendly; it handles either simple HTTP/HTTPS Post, which allows usage of any programming language capable of making HTTP posts. So far, access to Matrix SMS Gateway has been successfully implemented and tested with the following programming languages: PHP, Perl, Java, C#, Python, C/C++ and others.
If in doubt, please refer to Perl examples, as they are the most complete and were most thoroughly tested.

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.

Text to Speech (TTS) and Voice messaging, however not being a part of the 'SMS' functionality, are also covered in this document.

Technical Support for the SMS Gateway is available at this email address: support@smsmatrix.com

The following API functions are provided:

Send SMS message(s)

Send TTS (Text-to-Speech) message (text message delivered as voice: cell and landline phones)
Send Voice message
Query message's status
Lookup cellular carrier for given cell phone number
Query account's balance
Query message rate (fee)
SMTP gateway for SMS/TTS delivery

Voice and TTS messaging does not really belong to the "SMS" functionality, but nevertheless they are also covered by this document.

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) are supported for SMS delivery.
Text-to-Speech currently supports English language only (ASCII).
Both: HTTP and HTTPS protocols are supported.

PDF Version - Matrix SMS Gateway Developer's Guide
Examples of the usage of our SMS Gateway API, in several programming languages, are listed below.

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 $URL = 'http://www.smsmatrix.com/matrix';
my $PIN = '12506063167';  ## comma separated list of phone numbers
# my $PIN = '12506063167,12508763211';
my $USERNAME = 'user@hotmail.com';
my $PASSWORD = 'pass72727';
my $TXT = 'This is a test, pls ignore';

# my $TXT = "This is Chinese unicode text: ".
#          "\xE6\x96\x87\xE6\x98\x8E\xE5\x8A\x9E\xE7\xBD\x91\xE6\x96\x87\xE6\x98\x8E" .
#          "\xE4\xB8\x8A\xE7\xBD\x91\xE4\xB8\xBE\xE6\x8A\xA5\xE7\x94\xB5\xE8\xAF\x9D";

##################################################

my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
 POST $URL,
 Content_Type  => 'application/x-www-form-urlencoded',
 Content       => [ 'username' => $USERNAME,
                    'password' => $PASSWORD,
                    'pin' => $PIN,
                    '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

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

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 TTS message : Perl Example

##################################################
## Example of using SMS Matrix HTTP API in Perl
## Sending Text-to-Speech message

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

my $URL = 'http://www.smsmatrix.com/matrix_tts';
my $USERNAME = 'user@hotmail.com';
my $PASSWORD = 'pass72727';
my $PIN = '12506063167';   ## accepts only 1 number
my $TXT = 'Adam, web server is down';

##################################################

my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
 POST $URL,
 Content_Type  => 'application/x-www-form-urlencoded',
 Content       => [ 'username' => $USERNAME,
                    'password' => $PASSWORD,
                    'pin' => $PIN,            ## Phone number
                    'repeat'   => 1,          ## Optional (default is 0)
                    'gender' => 'male',       ## Optional, 'female' is default
                    'language' => 'us',       ## Optional ('us' or 'es', 'us' is default)
                    'txt' => $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';
$PIN = '12506063167'; // comma separated list of phone numbers
// $PIN = '12506063167,12508763211';
$USERNAME = urlencode ('user@hotmail.com');
$PASSWORD = urlencode ('pass72727');
$TXT = urlencode ('This is a test, pls ignore');

$Q = "$URL?username=$USERNAME&password=$PASSWORD&pin=$PIN&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 PIN = "12506063167"; // phone number
 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 += "&" + "pin=" + PIN;
 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 PIN = "12506063167"; // phone number
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 +
 "&pin=" + PIN +
 "&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

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

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

my $URL = 'http://www.smsmatrix.com/carrier';
my $PIN = '12506063167'; ## phone number
my $USERNAME = 'user@hotmail.com';
my $PASSWORD = 'pass72727';

##################################################

my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
 POST $URL,
 Content_Type  => 'application/x-www-form-urlencoded',
 Content       => [ 'username' => $USERNAME,
                    'password' => $PASSWORD,
                    'pin' => $PIN]
);

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

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

SMS Gateway - Get Account's Balance : Perl Example

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

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

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

##################################################

my $ua = LWP::UserAgent->new();
my $res = $ua->request
(
 POST $URL,
 Content_Type  => 'application/x-www-form-urlencoded',
 Content       => [ 'username' => $USERNAME,
                    'password' => $PASSWORD]
);

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

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

SMTP gateway for SMS/TTS 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 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 or TTS (Text-to-Speech) message will be delivered as a result.

SMS Message via SMTP:

username:user78@hotmail.com
password:mypass883
pin:2501238585
sms:Hello Adam, this is a test, please ignore.

TTS Message via SMTP:

username:user78@hotmail.com
password:mypass883
pin:6301238534
tts:Hello John, are you up?.

Keywords (username,password,pin,sms,tts) in these emails ARE CASE SENSITIVE, and must be typed in lowercase - just like in the examples above.

Please note that email delivery is not very secure, there is a small chance that your username/password might be intercepted.

Voice Gateway - Send Voice Message : Perl Example

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

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

# The voice file provided must be in WAVE format: 16Bit 8kHz mono.

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',
                        pin       => '12502771720',  ## comma delimited list
                        voicefile => ['/tmp/november_sale.wav'],
                        callerid  => '16307791722'  ## optional
                      ]
);

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

SMS Gateway - Error Codes

The following numerical values are returned as statuscode field:


200 - OK

404 - ACCOUNT OR USER DOES NOT EXIST
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.

Email:
Password:
Forgot password ?