Developer's REST SMS API v.2 - communicating with the SMS Gateway

This document provides a reference for all features available to you via the HTTP interface for sending SMS.
The HTTP API allows you to integrate your Application (Client) to easysms (Gateway) using the HTTP protocol to send SMS.

General info

The Client issues a HTTP GET request to the easysms HTTP interface supplying a list of required parameters. easysms issues back a HTTP Response which indicates the success of the transaction.

Note that the delimiter used for status call in returned data, '|', is the pipe character (ASCII 124).

All parameters passed must be URL-encoded and also in UTF-8, as described in the following code samples.

API responses format

The API responds to all calls according to the parameter type. Accepted values for parameter type are: v2 which is the default value, json and xml.
Example of responses for API call key/get:

...&type=v2

Responds:

6fe2dd9c06df83

...&type=json

Responds:

{
   "status" : "1",
   "key" : "6fe2dd9c06df83",
   "remarks" : "Success"
}

...&type=xml

Responds:

<response>
   <status>1</status>
   <key>6fe2dd9c06ff83</key>
   <remarks>Success</remarks>
</response>

Try it out   (key/get)

http://easysms.gr/api/key/get?username=&password=&type=
Try it out  

The commands available in this version of the easysms API follows below.




API Key

The API Key should be used instead of username and password for all API calls. You can still use the username and password parameters, but we strongly recommend using the API Key instead for security reasons.

You acquire your API Key using the key/get call and you use it for all API calls instead of username and password parameters. If you need to change the API Key, you can do so using the key/reset call.
The key/get and key/reset calls are the only ones that require the use of username and password.
Once you get your API Key you can use it for all other API calls.

Try it out   (key/get)

http://easysms.gr/api/key/get?username=&password=&type=
Try it out  

Try it out   (key/reset)

http://easysms.gr/api/key/reset?username=&password=&type=
Try it out  

Return

...&type=v2

Responds:

6fe2dd9c06df83

...&type=json

Responds:

{
   "status" : "1",
   "key" : "6fe2dd9c06df83",
   "remarks" : "Success"
}

...&type=xml

Responds:

<response>
   <status>1</status>
   <key>6fe2dd9c06ff83</key>
   <remarks>Success</remarks>
</response>
 

Sending SMS

RESTful SMS API v.2

URL: http://easysms.gr/api/sms/send?key=[API Key]

Accepted Parameters

Parameter Description Presence
text Message to be sent. Must be URL encoded Mandatory
to MSIDSN of the recipient that the message will be sent to. Eg: 49175123456 Mandatory
from Sender ID (if alphanumeric, max 11 characters, numeric max 16 digits) Optional
flash Set true to send Flash SMS Optional
ucs Set true to send the sms using UCS encoding Optional
timestamp Set the timestamp to send the sms in Unix Epoch timestamp Optional
type Type of API response, can be one of v2, json or xml Optional

Returns

...&type=v2

Responds:

1234567890

...&type=json

Responds:

{
   "status" : "1",
   "id" : "1234567890",
   "balance" : "1234",
   "remarks" : "Success"
}

...&type=xml

Responds:

<response>
   <status>1</status>
   <id>1234567890</id>
   <balance>1234</balance>
   <remarks>Success</remarks>
</response>
Description
status 1 for message sent, otherwise message send failed
id the message id number (or 0 if failed). Delivery reports are given on message ids
balance the balance of the account
remarks Remarks about the call

Try it out   (sms/send)

http://easysms.gr/api/sms/send?key=&to=&from=&text=Hello&type=
Try it out  

Code Examples for sending SMS

<?php
	// Simple SMS send function
	function sendSMS($key, $to, $message, $originator) {
		$URL = "http://easysms.gr/api/sms/send?key=" . $key . "&to=" . $to;
		$URL .= "&text=" . urlencode( $message ) . '&from=' . urlencode( $originator );
		$fp = fopen( $URL, 'r' );
		return fread( $fp, 1024 );
	}
	// Example of use 
	$response = sendSMS( 'My API Key', '4917512345', 'My test message', 'MyMessage' );
	echo $response;
?>
<?php
    // Simple SMS send function
    function sendSMS($key, $to, $message, $originator) {
        $URL = "http://easysms.gr/api/sms/send?key=" . $key . "&to=" . $to;
        $URL .= "&text=".urlencode($message).'&from='.urlencode($originator);
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $URL);
        curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $output = curl_exec($ch);
        $info = curl_getinfo($ch);
        curl_close($ch);
        return $output;
    }
    // Example of use
    $response = sendSMS('My API Key', '4917512345', 'My test message', 'MyMessage');
    echo $response ;
?>
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.UnsupportedEncodingException;
import java.net.URL;
import java.net.URLConnection;
import java.net.URLEncoder;
// Uses Apache Common URL utils, download from apache.org and put it in CLASSPATH
import org.apache.commons.codec.binary.Base64;

// Simple send SMS programm
public class SendSMS {
    public static String sendSMS( String key, String to, String message, String originator ) {
		
        String webPage;
        try {
            webPage = "http://easysms.gr/api/sms/send?key=" + key + 
                "&to=" + to + "&text=" + URLEncoder.encode( message, "UTF-8" ) +
                "&from=" + URLEncoder.encode( originator, "UTF-8" );
        } catch ( UnsupportedEncodingException e ) {
            return "UnsupportedEncodingException";
        }

		try{
			URL url = new URL(webPage);
			URLConnection urlConnection = url.openConnection();

			InputStream is = urlConnection.getInputStream();
			InputStreamReader isr = new InputStreamReader(is);

			int numCharsRead;
			char[] charArray = new char[1024];
			StringBuffer sb = new StringBuffer();

			while ((numCharsRead = isr.read(charArray)) > 0) {
				sb.append(charArray, 0, numCharsRead);
			}
			String result = sb.toString();
			return result;		

		} catch ( Exception e ){
			return "MalformedURLException";
		}
    }

    public static void main( String[] args ){
        // Example of use 
        String response = sendSMS( "My API Key", "4917512345", "My test message", "MyMessage" );
        System.out.println( response );
    }
}
<%
    mykey = "My API Key" 'put your API Key here
    mobile = "4917512345"

    message = Server.URLEncode("My test message")
    originator  = Server.URLEncode("TextMessage")

    url = "http://easysms.gr/api/sms/send?key=" + mykey + "&to=" + mobile + "&text=" + message + "&from=" + originator

    set objSrvHTTP = Server.CreateObject("Msxml2.ServerXMLHTTP")
    objSrvHTTP.open "GET", url, False
    objSrvHTTP.send()
    Resp = objSrvHTTP.responseText

    Response.Write( Resp )
%>
using System;
using System.IO;
using System.Net;
using System.Text;
using System.Web;

namespace SendSMS {
    class Program {
        public static string SendSMS( string key, string to, string message, string originator ) {
            StringBuilder sb  = new StringBuilder();
            byte[] buf = new byte[ 1024 ];
            string url = "http://easysms.gr/api/sms/send?key=" + key +
                "&to=" + to + "&text=" + HttpUtility.UrlEncode( message ) +
                "&from=" + HttpUtility.UrlEncode( originator );
            HttpWebRequest request = ( HttpWebRequest ) WebRequest.Create( url );
            HttpWebResponse response = ( HttpWebResponse ) request.GetResponse();
            Stream resStream = response.GetResponseStream();
            string tempString = null;
            int count = 0;
            do {
                count = resStream.Read( buf, 0, buf.Length );
                if ( count != 0 ) {
                    tempString = Encoding.ASCII.GetString( buf, 0, count );
                    sb.Append( tempString );
                }
            }
            while ( count > 0 );
            return sb.ToString();
        }
        static void Main( string[] args ) {
            string respXML = SendSMS( "My API Key", "4917512345", "My test message", "MyMessage" );
            Console.WriteLine( respXML );
       }
    }
}
/* * Send SMS C/C++ example need curllib download from http://curl.haxx.se/ */

#include <stdio.h>
#include <tchar.h>
#include <string.h>
#include <curl/curl.h>
#define URLSIZE 512

struct MemoryStruct {
        char *memory;
        size_t size;
};

/* Converts a hex character to its integer value */

char from_hex(char ch) {
        return isdigit(ch) ? ch - '0' : tolower(ch) - 'a' + 10;
}

/* Converts an integer value to its hex character*/

char to_hex(char code) {
        static char hex[] = "0123456789abcdef";
        return hex[code & 15];
}

/* Returns a url-encoded version of str */

char *url_encode(char *str) {
        char *pstr = str, *buf = (char *)malloc(strlen(str) * 3 + 1), *pbuf = buf;
        while (*pstr) {
                if (isalnum(*pstr) || *pstr == '-' || *pstr == '_' || *pstr == '.' || *pstr == '~')
                        *pbuf++ = *pstr;
                else if (*pstr == ' ')
                        *pbuf++ = '+';
                else
                        *pbuf++ = '%', *pbuf++ = to_hex(*pstr >> 4), *pbuf++ = to_hex(*pstr & 15);
                pstr++;
        }
        *pbuf = '\0';
        return buf;
}

/* CURL Callback write function */

static size_t WriteMemoryCallback(void *contents, size_t size, size_t nmemb, void *userp) {
        size_t realsize = size * nmemb;
        struct MemoryStruct *mem = (struct MemoryStruct *)userp;
        mem->memory = (char *)realloc(mem->memory, mem->size + realsize + 1);
        if (mem->memory == NULL) {
                /* out of memory! */
                printf("not enough memory (realloc returned NULL)\n");
                exit(EXIT_FAILURE);
        }
        memcpy(&(mem->memory[mem->size]), contents, realsize);
        mem->size += realsize;
        mem->memory[mem->size] = 0;
        return realsize;
}

/* Send SMS */

char * sendSMS(const char *key, const char *to, char *message, char *originator) {
        static char url[URLSIZE] = "http://easysms.gr/api/sms/send?key=";
        char *encoded;
        CURL *curl;
        CURLcode res;
        struct MemoryStruct chunk;
        chunk.memory = (char *)malloc(1);  /* will be grown as needed by the realloc above */
        chunk.size = 0;    /* no data at this point */
        curl = curl_easy_init();
        if(curl) {
                strcat_s(url, URLSIZE, key);
                strcat_s(url, URLSIZE, "&to=");
                strcat_s(url, URLSIZE, to);
                strcat_s(url, URLSIZE, "&text=");
                encoded = url_encode(message);
                strcat_s(url, URLSIZE, encoded);
                free(encoded);
                encoded = url_encode(originator);
                strcat_s(url, URLSIZE, "&from=");
                strcat_s(url, URLSIZE, encoded);
                free(encoded);
                curl_easy_setopt(curl, CURLOPT_URL, url);
                /* send all data to this function  */
                curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteMemoryCallback);
                /* we pass our 'chunk' struct to the callback function */
                curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)&chunk);
                if((res = curl_easy_perform(curl)) != CURLE_OK) {
                        return NULL;
                }
                curl_easy_cleanup(curl);
        }
        return chunk.memory;
}

int main(void) {
        char *response;
        response = sendSMS("My API Key", "4917512345", "My test message", "MyMessage");
        if(response != NULL) {
                printf(response);
                free(response);
        }
        getchar();
        return 0;
}
#include <iostream>
#include <string>
#using <System.Dll>
#using <System.Web.Dll>

using namespace std;
using namespace System;
using namespace System::Web;
using namespace System::Net;
using namespace System::IO;
using namespace System::Runtime::InteropServices;

ref class SMSSender
{

private:
        static String^ Key = "My API Key";

public:
        SMSSender()
        {}
        String^ SendSMS(String^ To, String^ Message, String^ From)
        {
                Message = HttpUtility::UrlEncode(Message);
                From = HttpUtility::UrlEncode(From);
                String^ URL = "http://easysms.gr/api/sms/send?key=" + Key + "&text=" + Message + "&from=" + From + "&to=" + To;
                WebRequest^ Handle = WebRequest::Create(URL);
                WebResponse^ HTTPResponse = Handle->GetResponse();
                StreamReader^ Stream = gcnew StreamReader(HTTPResponse->GetResponseStream());
                String^ Response = Stream->ReadToEnd()->Trim();
                HTTPResponse->Close();
                return Response;
        }
};

int main() {
        SMSSender^ test = gcnew SMSSender();
        String^ resp = test->SendSMS("4917512345", "My test message", "MyMessage");
        Console::WriteLine(resp);
        return 0;
}
require 'net/http'
require 'uri'

def send_sms( key, to, message, originator )
  requested_url = 'http://easysms.gr/api/sms/send?key=' + key + 
                "&to=" + to + "&text=" + URI.escape( message ) +
                "&from=" + URI.escape( originator )
  url = URI.parse( requested_url )
  full_path = ( url.query.blank? ) ? url.path : "#{url.path}?#{url.query}"
  the_request = Net::HTTP::Get.new( full_path )
  the_response = Net::HTTP.start( url.host, url.port ) { |http|
    http.request( the_request )
  }
  raise "Response was not 200, response was #{the_response.code}" if the_response.code != "200"
  return the_response.bodyend
resp = send_sms( 'My API Key', '4917512345', 'My test message', 'MyMessage' )

puts(resp)
Imports System.Web

Module Module1

	Public Function SendSMS( ByVal key As String, ByVal toPhone As String, 
								ByVal message As String, ByVal originator As String )
		Dim request As HttpWebRequest  
		Dim response As HttpWebResponse = Nothing  
		Dim reader As StreamReader  
		Dim url As String = "http://easysms.gr/api/sms/send?key=" & key & 
		                "&to=" & toPhone & "&text=" & System.Web.HttpUtility.UrlEncode( message ) &
		                "&from=" & System.Web.HttpUtility.urlencode( originator )
		Try  
		    ' Create the web request  
		    request = DirectCast(WebRequest.Create(url), HttpWebRequest)  
		    ' Get response  
		    response = DirectCast(request.GetResponse(), HttpWebResponse)  
		    ' Get the response stream into a reader  
		    reader = New StreamReader(response.GetResponseStream())  
		    ' Return response
			SendSMS = reader.ReadToEnd()
		Finally  
		    If Not response Is Nothing Then 
				response.Close()  
				Console.WriteLine("Error connecting")
			End If
		End Try  
	End Function

    Sub Main()
        Dim result As String = SendSMS( "My API Key", "4917512345", "My test message", "MyMessage" )
        Console.WriteLine( result )
        Console.ReadKey()
    End Sub

End Module


Get Balance

URL:   http://easysms.gr/api/balance/get?key=[API Key]

Returns

The number of SMS left in the account.

...&type=v2

Responds:

1234

...&type=json

Responds:

{
   "status" : "1",
   "balance" : "1234",
   "remarks" : "Success"
}

...&type=xml

Responds:

<response>
   <status>1</status>
   <balance>1234</balance>
   <remarks>Success</remarks>
</response>

Try it out   (balance/get)

http://easysms.gr/api/balance/get?key=&type=
Try it out  

Get Status

URL:   http://easysms.gr/api/status/get?key=[API Key]

Returns

Returns all messages whose status has been changed, separated with the pipe character | (when the type parameter is v2).

The status can be s (sent), d (delivered) or f (failed).

...&type=v2

Responds:

...&type=json

Responds:

{
   "0" : {
           "id" : "1231223122",
           "status" : "d"
   },
   "1" : {
           "id" : "1234561232",
           "status" : "f"
   },
   "status" : "1",
   "total" : "2",
   "remarks" : "Success"
}

...&type=xml

Responds:

<response>
   <status>1</status>
   <total>2</total>
   <remarks>Success</remarks>
   <sms>
            <id>1231223122</id>
            <status>d</status>
   </sms>
   <sms>
            <id>1234561232</id>
            <status>f</status>
   </sms>
</response>

Try it out   (status/get)

http://easysms.gr/api/status/get?key=&type=
Try it out