SMS API

Last updated: August 1st, 2017

Send SMS

Call this API to send a SMS to specific phone number

If you need to send same SMS to 3 different number, call this API 3 times with different "to" parameter.

Endpoint:

https://api.esms.com.my/sms/send

Method:

POST, supported content-type are:

  • application/x-www-form-urlencoded; charset=utf-8
  • application/json; charset=utf-8

* charset behind is necessary when you're sending in Unicode messages, such as Chinese characters.

Parameters:
Name Type Required Description
user String Mandatory This would be your account's username or api key.
pass String Mandatory This would be your account's password or api secret.
to String Mandatory

The phone number of target recipient you'd like to send SMS to.

Phone number must be supplied along with country code.

Do not include any non-numeric character, eg: - ( ) or space.

Example: 60123456789

msg String Mandatory

The message that you'd like to send to the recipient.

Type (Normal/Unicode) would be automatically detected based on the content if parameter type is not supplied

Example: Hello world

type Numeric Optional

Please use only "0" for normal (ASCII) message or "8" for unicode message.

Example: 0

dlr Numeric Optional

Set to "1" if you'd like to receive DR report. Any other value would be ignored.

Example: 1

dlr-url String Optional

Specify your own DLR receiving endpoint to receive our DR report.

Parameter dlr must be set to 1 for this to take effect.

Example: https://www.yourownsite.com/dlrreceiver

Response:

Response would be returned in application/json format.

An example of Successful response would be:

{"status":0,"creditDeducted":1,"message":"ok","id":"88ce9c6e-1707-41b8-95a2-91d228001fc7","parts":1,"type":0}

An example of Failed response would be:

{"status":9,"message":"Invalid phone number, please do not include any non-numeric character","id":"c8d6bb1c-bff6-47d5-9e01-dc2596bbdbe7"}

Name Type Description
status Numeric Status code of the request, kindly refer to below Status mapping table for more details
message String A short description of given status, for more information you may contact our support team at support@esms.com.my
id String ID of this particular request, you may want to keep this ID in your own SMS table for future reference, our DR would be based on this ID.
creditDeducted Numeric The total credit amount deducted from your account.
parts Numeric To show how many parts of SMS this message requires.
type Numeric

Type of this SMS, "0" for normal (ASCII) SMS, "8" for unicode SMS.

If you submitted a valid type during the request, it would be used, otherwise this would be automatically detected.

Response Status Code:
Status Code Description
0Success.
1Insufficient parameters
Please make sure all mandatory parameter exists.
2Invalid calling IP
You are getting this error because you've previously requested your account to be able to call only from certain IP, and you're not calling from the designated IP.
3Invalid username/password combination.
If you believe this is an error, kindly contact our support team at support@esms.com.my.
4Invalid country code
The country code of the phone number you provides is not recognized.
For Malaysia recipients, do remember to send to 60123456789 instead of 0123456789.
5Insufficient credits
Contact your account manager for reload procedures.
6Internal error
You may retry again shortly.
7Invalid "type" parameter
Please use only "0" Normal (ASCII) SMS or "8" for Unicode SMS.
8Content too long
SMS can only contains maximum of 1530 GSM characters for Normal SMS, and 670 characters for Unicode SMS.
9Invalid "to" parameter
Please include only numeric in "to" parameter
For example, please send 60123456789 instead of 60-12 345 6789
10Invalid message content
For SMS to Malaysia mobile phones, you're required to append RM0.00<space> at the front of the message
For example, intead of sending Thank you for purchasing product A.
You should send RM0.00 Thank you for purchasing product A.
SMS Length Calculation:

Note that SMS has their length limitation, for example, an ASCII SMS can only contains up to 160 characters. SMS containing more than 160 characters would be treated as 2 SMS or more.

  • We support up to maximum of 10 parts SMS.
  • Not all operators support long SMS, certain operator (such as DiGi) may split long SMS to different SMS part, hence you will receive it as 2 or more different SMS message.
  • Unicode and ASCII have different maximum character count, kindly refer to table below.
Parts Maximum Length
ASCII Unicode
116070
2306134
3459201
4612268
5765335
6918402
71071469
81224536
91377603
101530670

* Certain special characters may be treated as 2 character in ASCII mode, you may refer at table "Basic Character Set Extension" here

Code Sample:

PHP

<?php 
	function sendSmsToEsms() {
		$url = 'https://api.esms.com.my/sms/send';
		
		// replace yourusername, yourpassword, and 60123456789 to suits your need
		$data = array('user' => 'yourusername', 
			'pass' => 'yourpassword', 
			'to' => '60123456789', 
			'msg' => 'RM0.00 Hello from ESMS');

		$options = array(
			'http' => array(
				'header'  => "Content-type: application/x-www-form-urlencoded; charset=utf-8",
				'method'  => 'POST',
				'content' => http_build_query($data)
			)
		);
		$context  = stream_context_create($options);
		$result = file_get_contents($url, false, $context);
		if ($result === FALSE) { /* Handle error */ }

		var_dump($result);
	}
?>

										

C#

static async void sendSmsToEsms()
{
	var url = "https://api.esms.com.my/sms/send";
	try
	{
		// replace yourusername, yourpassword, and 60123456789 to suits your need
		var values = new Dictionary
		{
		   { "user", "yourusername" },
		   { "pass", "yourpassword" },
		   { "to", "60123456789" },
		   { "msg", "RM0.00 Hello from ESMS" }
		};

		var content = new FormUrlEncodedContent(values);

		var client = new HttpClient();
		var response = await client.PostAsync(url, content);

		var responseString = await response.Content.ReadAsStringAsync();
		Console.WriteLine("Response: " + responseString);
	}
	catch (Exception ex)
	{
		Console.WriteLine(ex.Message);
		Console.WriteLine(ex.StackTrace);
	}
}

										

VB

Imports System.Text
Imports System.Net
Imports System.IO
Imports System.Web

Module Module1

    Sub Main()
        SendSmsToEsms("RM0.00 Hello from ESMS", "60123456789")
    End Sub

    Private Sub SendSmsToEsms(msg As String, number As String)
        Dim s As HttpWebRequest
        Dim enc As UTF8Encoding
        Dim postdata As String
        Dim postdatabytes As Byte()
        s = HttpWebRequest.Create("https://api.esms.com.my/sms/send")
        enc = New System.Text.UTF8Encoding()

        postdata = "user=yourusername"
        postdata += "&pass=yourpassword"
        postdata += "&to=" & number
        postdata += "&msg=" & System.Web.HttpUtility.UrlEncode(msg)

        postdatabytes = enc.GetBytes(postdata)
        s.Method = "POST"
        s.ContentType = "application/x-www-form-urlencoded; charset=utf-8"
        s.ContentLength = postdatabytes.Length

        Using stream = s.GetRequestStream()
            stream.Write(postdatabytes, 0, postdatabytes.Length)
        End Using
        Dim result = s.GetResponse()
        Dim reader As New StreamReader(result.GetResponseStream())
        Dim streamText As String = reader.ReadToEnd()

        Console.WriteLine("Response: " & streamText)
    End Sub

End Module

										

Java

import java.io.*;
import java.net.*;
import java.util.*;

// Other codes

public void sendSmsToEsms() {
	try {
		URL url = new URL("https://api.esms.com.my/sms/send");
		
		// replace yourusername, yourpassword, and 60123456789 to suits your need
		Map params = new LinkedHashMap<>();
		params.put("user", "yourusername");
		params.put("pass", "yourpassword");
		params.put("to", "60123456789");
		params.put("msg", "RM0.00 Hello from ESMS");

		StringBuilder postData = new StringBuilder();
		for (Map.Entry param : params.entrySet()) {
			if (postData.length() != 0) postData.append('&');
			postData.append(URLEncoder.encode(param.getKey(), "UTF-8"));
			postData.append('=');
			postData.append(URLEncoder.encode(String.valueOf(param.getValue()), "UTF-8"));
		}
		byte[] postDataBytes = postData.toString().getBytes("UTF-8");

		HttpURLConnection conn = (HttpURLConnection)url.openConnection();
		conn.setRequestMethod("POST");
		conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded; charset=utf-8");
		conn.setRequestProperty("Content-Length", String.valueOf(postDataBytes.length));
		conn.setDoOutput(true);
		conn.getOutputStream().write(postDataBytes);

		try (InputStream is = conn.getInputStream()) {
			try (InputStreamReader isr = new InputStreamReader(is, "UTF-8")) {
				try (Reader in = new BufferedReader(isr)) {
					for (int c; (c = in.read()) >= 0;)
						System.out.print((char)c);
				}
			}
		}

	} catch (Exception ex) {
		ex.printStackTrace(System.out);
	}
}

										

NodeJS

var querystring = require('querystring');
var https = require('https');

function SendSmsToEsms() {
  var post_data = querystring.stringify({
      'user' : 'yourusername',
      'pass': 'yourpassword',
      'to': '60123456789',
      'msg' : 'RM0.00 Testing'
  });

  // An object of options to indicate where to post to
  var post_options = {
      host: 'api.esms.com.my',
      port: '443',
      path: '/sms/send',
      method: 'POST',
      headers: {
          'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8',
          'Content-Length': Buffer.byteLength(post_data)
      }
  };

  // Set up the request
  var post_req = https.request(post_options, function(res) {
      res.setEncoding('utf8');
      res.on('data', function (chunk) {
          console.log('Response: ' + chunk);
      });
  });

  // post the data
  post_req.write(post_data);
  post_req.end();

}

SendSmsToEsms();