Below we collected all the information needed to integrate your system or application with SMS-24, using the API interface. API interface allows you to integrate most of on-line applications.

How to start?

  • To start work with SMS-24, first register with our web site. Registration is completely free.
  • You can top-up your account using several payment methods (PayPal, OkPay, bank transfer, etc). All payments on our SMS platform do not have expiration time (open-ended validity).
  • You are able to send your first automated SMS in few minutes after registration. Contact our Support Team in case of any questions.

IP filter for API interface

In order to improve interface API protection you may set list of IP addresses which will be whitelisted. You may do it inside your account „Tools & Settings” → „Gateway Settings” (API access by IP). It will be possible to send messages only from these whitelisted IP addresses (try of sending from other IPs will result in responding: ERROR:105).

API password

API password after registering is the same as web panel password. You may change your API password inside your account "Tools & Settings" → "Gateway Settings" (API password). Changing your web account access password doesn't change API password.

Individual SMS message sending

URL links needed for connecting with our Gateway:

  • http://sms-24.com/gateway/send/ – for standard connections;
  • https://sms-24.com/gateway/send/ – for SSL secured connections (256bit).

Messages should be sent as a HTTP GET or POST request to our system with the following parameters.

Parameter * Length Value Description
Email Max 25 Chars String Mandatory. Your SMS-24 e-mail.
Password Max 25 Chars String Mandatory. Your SMS-24 API password (by default the same as your password provided during registration)
Receiver Max 16 Alphanumeric Chars String Mandatory. Mobile phone number that will receive the SMS (436641234567)
Message Max 4096 String

Mandatory. Message text or message data (Hex, Bin, RTTTL) that will be sent. A SMS text message may consist of up to 160 characters belonging to the
following set: · A…Z a…z 0…9, blank space, the meta characters "\n", etc; or 4096 characters if data SMS.

Test Max 1 Char Integer Optional. Indicates "test" mode. 1 = TRUE, 0 = FALSE. By default "test=0". If the Test parameter is set TRUE (or 1), the Gateway will process the
message but not deliver it. A result code will be returned. This mode is useful for debugging the SMS request in your application.
Sender Max 16 Alphanumeric Chars String Optional. The sender of the SMS message (or originator number). The Sender may be alphanumeric or numeric. If the originator is alphanumeric, it must consist of 1-11 digits or letters. Unicode characters are not allowed in Sender. If the originator is numeric, it must consist of 1-15 digits. It will appear on
the mobile recipient's phone number as an international-format dialing number (prefixed with a "+"). The originator field is not supported by all recipients or networks. Depending on the particular brand and model, it also may not be recognized by the recipient's mobile phone. We cannot guarantee that any user-defined originator will indeed appear as specified on the recipient's phone.
DeliveryTime Max 30 Characters Date/Time String Optional. Date and Time for deferred delivery (2000-01-01 00:00:00). If left blank system will take the current date & time value. Setting a past date will result in sending message instantly.
SmsType Max 3 Chars String Optional. This optional parameter indicates the type of message to deliver. The following values are accepted:
  • Empty = SMS Text
  • FLH = Flash SMS Text
  • UTF = SMS Text in Unicode UTF-8
  • UCS = SMS Text in Unicode UCS-2
  • WBK = WAP Bookmark
  • WPS = WAP PUSH
SmsValidity Max 4 Chars Integer

Optional. Message expiration date (in unix timestamp) is a date after which message won't be delivered if it wasn't delivered yet. The value must to be between 30 minutes and 4320 minutes (72 hours). If the parameter is empty, for the value will be used the default validity present in the account.

ReferenceID Max 10 Chars Integer Optional. This parameter allow to send an Reference ID. The number will be saved inside the record of the SMS sent and will be returned back through the email/callback notification.
Notify Max 150 Chars String Optional. Use this parameter in order to retrieve from our system the “delivered/not delivered” status through email or via HTTP/HTTPS:
- Notification=“mailto:xxxxxxxxx@domain.com” (the notification will be sent to this email address)
- Notification=“http://www.xxxxxx.com/script.asp” (the notification will be sent to the script with special parameters - see below)

* Variable names are case-sensitive.

Request: https://sms-24.com/gateway/send/?
Email=your_email&Password=md5(your_password)&Sender=from_name
&Receiver=44123456789&Message=message_content

Response: OK:<ID>:<MONEY>
or (when error occur)
ERROR:<ERR>

<ID> Message unique ID. You will need it for delivery confirmation
<MONEY> Amount of used money (i.e. Text sent in 3 messages will return 3xSMS amount)
<ERR> Error code (check the error code list below)

Example: OK:530006523459:1
or
ERROR:102

Receiving delivery confirmation (Callback function)

We offer you possibility to run any available script in the web with callback delivery reports. In order to use this option please login on SMS-24 web site, then inside your profile in "Tools & Settings" → "Gateway Settings" set "Callback URL". Also you can set Notify variable, it will have priority over value set within the profile.

Example: http://www.yoursite.com/delivery-status.php

It is important that entered address is a valid address to existing, available script.

After updating message status in SMS-24 system the update will be sent to callback script (one status per one request).
$_GET['MsgId']=09062345671234567
$_GET['Status']=403

Parameter are described in following table:

Parameter * Description
MsgId Message ID
Status Status code, list of codes - see below.
ReferenceID Optional parameter send with SMS
DeliveredTime Date and time in of delivery report (in the following format: 2000-01-01 00:00:00)
Email E-mail address in SMS-24 which sent SMS

*Variable names are case-sensitive.

Script have to return 200 OK, i.e. status "The request has succeeded" (echo „OK”), otherwise the system will be sending requests every 300 seconds.

Delivery reports statuses list:

Id Status Description
0 SENT Message is sent
1 DELIVERED Message is delivered to recipient
2 QUEUED Message is waiting to be sent
3 UNDELIVERED Message is undelivered (invalid number, roaming error etc)

Getting number of remaining on your SMS-24 balance

URL links needed for connecting with our Gateway:

  • http://sms-24.com/gateway/balance/ – for standard connections;
  • https://sms-24.com/gateway/balance/ – for SSL secured connections (256bit).

Messages should be sent as a HTTP GET or POST request to our system with the following parameters.

Parameter * Length Value Description
Email Max 25 Chars String Mandatory. Your SMS-24 email
Password Max 25 Chars String Mandatory. Your SMS-24 API password (by default the same as your password provided during registration)

* Variable names are case-sensitive.

Request: https://sms-24.com/gateway/balance/?
Email=your_email&Password=md5(your_password)

Response: OK:<MONEY>
or (when error occur)
ERROR:<ERR>

<MONEY> Amount of money available for client
<ERR> Error code (check the error code list below)

Example: OK:12345
or
ERROR:102

API Error codes

Error Code Description
101 Invalid authorization info
102 Invalid username or password
103 Insufficient money on your account
105 Wrong IP address (for IP filter turned on)
200 Unsuccessful message submission "" (+ Gateway error text goes here)
201 System internal error (please report)
202 Too many simultaneous request, message won't be sent

Particular Cases and Examples

Sending Simple SMS Message

Use request below to send simple text SMS:

https://sms-24.com/gateway/send/?
Email=your_email&Password=md5(your_password)&Sender=from_name
&Receiver=44123456789&Message=message%20text

Sending Unicode Messages

Gateway interface fully supports Unicode messaging. It’s possible to submit messages containing foreign (non-Latin) characters to our SMS Gateway using one of the following two encoding methods:

  • UCS-2 (SmsType=UCS)
  • UTF-8 (SmsType=UTF)

Unicode is a worldwide standard maintained by the international Unicode consortium. You can learn more about Unicode by visiting the following links: http://www.unicode.org. A SMS message in Unicode format can contain at most 70 characters (280 Byte in Hex Dump) and will only displayed correctly on UCS-capable mobile phones.

Sending Messages in UCS-2 Format

In UCS-2 format, the entire SMS message is sent as a sequence of hex-encoded Unicode characters. Each Unicode character is represented as four hex digits (0..9, A..F in uppercase). For example, the string "ABC" consists of the following Unicode characters (in hexadecimal):

  • A = 0041
  • B = 0042
  • C = 0043

Request: https://sms-24.com/gateway/send/?
Email=your_email&Password=md5(your_password)&Sender=from_name
&Receiver=44123456789&SmsType=utf&Message=ABC

Sending Messages in UTF-8 Format

Web browsers generate foreign characters in the UTF-8 format ("Unicode Transformation Format"). In UTF-8, each Unicode character has the form

 &#nnnn; 

For example, a web browser will send the string "Привет World! " to your script as follows:

&#1055;&#1088;&#1080;&#1074;&#1077;&#1090; World!

Request: https://sms-24.com/gateway/send/?
Email=your_email&Password=md5(your_password)&Sender=from_name
&Receiver=44123456789&SmsType=utf&Message=&#1589;&#1576;&#1575;&#1581;&#1575;&#1604;&#1582;&#1610;&#1585; World!

 

Sending WAP PUSH messages

To send WAP PUSH message the link and message content have to be be converted to binary.

The result of the conversion should be given in a request as a message content. There should be used following parameters &datacoding=bin and &udh=0605040b8423f0 in API request.

Request: https://sms-24.com/gateway/send/?
Email=your_email&Password=md5(your_password)&Sender=sender_name
&Receiver=4412345678&SmsStype=wps
&
Message=0605040b8423f0860601ae02056a0045c60c03687474703a2f2f
7777772e736d736170692e706c000701034e61737a61207374726f6e613a000101

Code Samples

PHP class:

<?php
class Sms24
{
    private $Email = 'your@email.here';       // Login
    private $Password = 'Your password';      // Password
 
    public function __construct($login = false, $password = false)
    {
        if($login) $this->Email = $login;
        if($password) $this->Password = $password;
    }
 
    /**
     * Send SMS
     *
     * @return string
     */
    public function Send($Sender = false,       // Sender name or phone #
                         $Receiver = false,     // Reciever phone #
                         $Message = false,      // SMS text/data
                         $SmsType = false,      // Type of message to deliver
                         $ReferenceID = false,  // Saved reference ID
                         $DeliveryTime = false, // If deferred delivery
                         $SmsValidity = false,  // When sms expire
                         $Notify = false,       // Notification URL
                         $Test = false)         // Test mode
    {
        if($Sender && $Receiver && $Message) {
            # Making api request
            $request =  'Email='.$this->Email.
                        '&Password='.md5($this->Password).
                        '&Receiver='.$Receiver.
                        '&Sender='.$Sender.
                        '&Message='.urlencode($Message);
            if($DeliveryTime) $request .= '&DeliveryTime='.$DeliveryTime;
            if($SmsType)      $request .= '&SmsType='.$SmsType;
            if($SmsValidity)  $request .= '&SmsValidity='.$SmsValidity;
            if($ReferenceID)  $request .= '&ReferenceID='.$ReferenceID;
            if($Notify)       $request .= '&Notify='.$Notify;
            if($Test)         $request .= '&Test='.$Test;
 
            if (extension_loaded('curl')) {
                $curl = curl_init();
                curl_setopt($curl, CURLOPT_URL, 'https://sms-24.com/gateway/send/');
                curl_setopt($curl, CURLOPT_POST, true);
                curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
                curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); 
                $rawResponse = curl_exec ($curl);
                curl_close ($curl);
            } else {
                $header = 'POST /gateway/send/ HTTP/1.0' . "rn";
                $header = 'Host: sms-24.com' . "rn";
                $header .= 'Content-Type: application/x-www-form-urlencoded' . "rn";
                $header .= 'Content-Length: ' . strlen($request) . "rn";
                $header .= 'Connection: close' . "rnrn";
                $fp = fsockopen('sms-24.com', 80, $errno, $errstr, 30);
                if ($fp) {
                    fputs($fp, $header . $request);
                    while (!feof($fp)) {
                        $rawResponse = fgets($fp, 1024);
                    }
                    fclose($fp);
                } else {
                    return false;
                }
            }
            return $rawResponse;
        } else {
            # Required params are empty
            return false;
        }
    }
 
    /**
     * Get balance
     *
     * @return float
     */
    public function getBalance()
    {
        $request =  'Email='.$this->Email.'&Password='.md5($this->Password);
 
        if (extension_loaded('curl')) {
            $curl = curl_init();
            curl_setopt($curl, CURLOPT_URL, 'https://sms-24.com/gateway/balance/');
            curl_setopt($curl, CURLOPT_POST, true);
            curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
            curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); 
            $rawResponse = curl_exec ($curl);
            curl_close ($curl);
        } else {
            $header = 'POST /gateway/balance/ HTTP/1.0' . "rn";
            $header = 'Host: sms-24.com' . "rn";
            $header .= 'Content-Type: application/x-www-form-urlencoded' . "rn";
            $header .= 'Content-Length: ' . strlen($request) . "rn";
            $header .= 'Connection: close' . "rnrn";
            $fp = fsockopen('sms-24.com', 80, $errno, $errstr, 30);
            if ($fp) {
                fputs($fp, $header . $request);
                while (!feof($fp)) {
                    $rawResponse = fgets($fp, 1024);
                }
                fclose($fp);
            } else {
                return false;
            }
        }
        $response = explode(':', $rawResponse);
        switch($response[0]){
            case 'OK':
                return $response[1];
                break;
            case 'ERROR':
                return false;
                break;
            default:
                return false;
                break;
        }
    }
 
    /**
     * Convert cp1251 string into UTF-8 entities
     *
     * @return string
     */
    public function Convert($message)
    {
        $return = '';
 
        // Get existing entities else double-escape
        $message = html_entity_decode(stripslashes($message),ENT_QUOTES,'UTF-8');
        // Return array of every multi-byte character
        $ar = preg_split('/(?<!^)(?!$)/u', $message );
 
        foreach ($ar as $c)
        {
            $o = ord($c);
            if ( (strlen($c) > 1)     || # multi-byte [unicode]
                 ($o <32 || $o > 126) || # <- control / latin weirdos ->
                 ($o >33 && $o < 40)  || # quotes + ambersand
                 ($o >59 && $o < 63) )   # html
            {
                // Convert to numeric entity
                $c = mb_encode_numericentity($c,array (0x0, 0xffff, 0, 0xffff), 'UTF-8');
            }
            $return .= $c;
        }
        return $return;
    }
}
 
?>

PHP class usage:

<?php
 
# You can set your login & password here
$gateway = new Sms24();
 
# Send SMS     Sender      Receiver         Message
$gateway->Send('SMS24', '+15550123456', 'Hello World!')
 
# Check balance
if($balance = $gateway->getBalance()) {
    echo 'My balance is '.$balance.' points!';
} else {
    echo 'Connection error';
}
 
?>

PHP callback handler:

<?php
    /**
     * Parse callback and return callback data as array or false while error
     */
 
    if(isset($_REQUEST["MsgId"]) && !empty($_REQUEST["MsgId"]))
    {
        $return = array(
            "MsgId" => $_REQUEST["MsgId"],
            "Status" => (isset($_REQUEST["Status"]) ? $_REQUEST["Status"] : ''),
            "ReferenceID" => (isset($_REQUEST["ReferenceID"]) ? $_REQUEST["ReferenceID"] : ''),
            "DeliveredTime" => (isset($_REQUEST["DeliveredTime"]) ? $_REQUEST["DeliveredTime"] : ''),
            "Email" => (isset($_REQUEST["Email"]) ? $_REQUEST["Email"] : '')
            );
        # Do something with recieved data
        mysql_query("UPDATE
                        `SMS`
                    SET
                        'Status'='".$return["Status"]."',
                        'ReferenceID'='".$return["ReferenceID"]."',
                        'DeliveredTime'='".$return["DeliveredTime"]."'
                    WHERE
                        'MsgId' = '".$return["MsgId"]."'"
                    );
    } else {
        # Not a callback - log error
        mysql_query("INSERT INTO
                        `Log`
                    SET
                        'Type'='Notice',
                        'Text'='Request, seems to be callback, but not a callback',
                        'DateTime'='".date("Y.m.d H:i:s")."'"
                    );
        header("HTTP/1.0 404 Not Found");
        die();
    }
 
?>

ASP .NET

C# library source code

using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.Net;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;
using System.Web;
 
namespace Sms24
{
    public class Sms24ApiClient
    {
        public string SendUrl = "https://sms-24.com/gateway/send/";
        public string BalanceUrl = "https://sms-24.com/gateway/balance/";
        private string _email;
        private string _password;
        private const string TimeFormat = "yyyy-MM-dd hh:mm:ss";
 
        public Sms24ApiClient(string email, string password)
        {
            if (String.IsNullOrEmpty(email) || String.IsNullOrEmpty(password))
                throw new Exception("Email & Password parameters are required");
            _email = email;
            _password = password;
        }
 
        private string SendRequest(string dataToPost, string url)
        {
            using (var wc = new WebClient())
            {
                wc.Headers[HttpRequestHeader.ContentType] = "application/x-www-form-urlencoded";
                var htmlResult = wc.UploadString(url, dataToPost);
 
                return htmlResult;
            }
        }
 
        private string EncodePassword(string originalPassword)
        {
            //Declarations
            Byte[] originalBytes;
            Byte[] encodedBytes;
            MD5 md5;
 
            //Instantiate MD5CryptoServiceProvider, get bytes for original password and compute hash (encoded password)
            md5 = new MD5CryptoServiceProvider();
            originalBytes = Encoding.Default.GetBytes(originalPassword);
            encodedBytes = md5.ComputeHash(originalBytes);
 
            //Convert encoded bytes back to a 'readable' string
            return BitConverter.ToString(encodedBytes).Replace("-", string.Empty).ToLowerInvariant();
        }
 
 
 
        public string Send(string sender, string reciever, string message, string smsType = "", string referenceId = "", DateTime deliveryTime = new DateTime(), DateTime smsValidity = new DateTime(), string notifyUrl = "", bool test = false)
        {
            var sb = new StringBuilder(String.Format("Email={0}&Password={1}&Receiver={2}&Sender={3}&Message={4}", HttpUtility.UrlEncode(_email), HttpUtility.UrlEncode(_password), HttpUtility.UrlEncode(reciever), HttpUtility.UrlEncode(sender), HttpUtility.UrlEncode(message)));
 
            if (deliveryTime != new DateTime())
            {
                sb.Append("&DeliveryTime=" + HttpUtility.UrlEncode(deliveryTime.ToString(TimeFormat)));
            }
 
            if (smsValidity != new DateTime())
            {
                sb.Append("&SmsValidity=" + HttpUtility.UrlEncode(smsValidity.ToString(TimeFormat)));
            }
 
            if (!String.IsNullOrEmpty(referenceId))
            {
                sb.Append("&ReferenceID=" + HttpUtility.UrlEncode(referenceId));
            }
 
            if (!string.IsNullOrEmpty(notifyUrl))
                sb.Append("&Notify=" + HttpUtility.UrlEncode(notifyUrl));
 
            if (test)
                sb.Append("&Test=1");
 
            if (!String.IsNullOrEmpty(smsType))
                sb.Append("&SmsType=" + HttpUtility.UrlEncode(smsType));
 
            return SendRequest(sb.ToString(), SendUrl);
        }
 
        public decimal GetBalance()
        {
            var requestString = String.Format("Email={0}&Password={1}", _email, _password);
            var response = SendRequest(requestString, BalanceUrl);
 
            var result = response.Split(':');
 
            switch (result[0])
            {
                case "OK":
                    return decimal.Parse(result[1], CultureInfo.InvariantCulture);
                case "ERROR":
                default:
                    throw new Exception("Error");
            }
        }
 
 
    }
 
}
 

You can download compiled library here

C# library usage

using System;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using Sms24;
 
namespace Tests
{
    [TestClass]
    public class UnitTest1
    {
        [TestMethod]
        public void GetBalanceTest()
        {
            var client = new Sms24ApiClient("test@test.com", "1234567");
            var balance = client.GetBalance();
        }
 
        [TestMethod]
        public void SendSms()
        {
            var client = new Sms24ApiClient("test@test.com", "1234567");
            var result = client.Send("15550123456", "15550123456", "Hello");
        }
    }
}