easysendsms.com

HTTP(s) API

The EasySendSMS HTTP(S) API offers a straightforward and reliable way to send SMS messages, perform HLR number validation, and more. This API is designed to be easy to integrate into your existing systems, providing a flexible solution for various messaging needs. Whether you’re sending a single message, validating phone numbers, or managing bulk SMS campaigns, the HTTP(S) API allows you to do so with minimal effort and maximum efficiency.

By leveraging the HTTP(S) API, you can automate your messaging processes, ensuring that your communications are delivered promptly and accurately. The API supports a wide range of functionalities, including message scheduling, delivery reporting, and real-time number validation. These features are essential for businesses that require reliable and scalable messaging solutions.

The API’s design prioritizes ease of use, with clear documentation and examples to help you get started quickly. Whether you’re integrating the API into a simple application or a complex system, the HTTP(S) API offers the tools you need to achieve your messaging objectives efficiently.

Send SMS HTTP(s) API

This page provides a reference for all features available via the HTTP interface for sending SMS.

The HTTP-API allows you to integrate your system (client) to EasySendSMS using the HTTP protocol to send SMS. HTTPS is also supported for secure transactions using SSL encryption.

The Client issues either a GET or POST request to the EasySendSMS HTTP API, supplying a list of required parameters. Our system issues back an HTTP response indicating the status of the sent message.

The HTTP-API is used for one-way messaging only.

API Base URL:

https://api.easysendsms.app/bulksms

Method: GET, POST

Required Parameters

The following parameters must be included in your API request:

Parameter Description Presence
Username Your EasySendSMS username Mandatory
Password Your EasySendSMS account password or your API password (if set in your account settings) Mandatory
From Sender Name that the message will appear from.
  • Max Length: 15 if numeric
  • Max Length: 11 if alphanumeric
  • Prefix the plus sign (+) to the sender's address if needed (URL encoded).
Mandatory
To Mobile number of the recipient, e.g., 61409317436 (Do not use + or 00 before the country code). Mandatory
Text The message to be sent. It can be plain text or Unicode, max message length 5 parts.
  • 153 characters per message for plain text.
  • 67 characters per message for Unicode.
Mandatory
Type Indicates the type of message:
  • 0: Plain text (GSM 3.38 Character encoding)
  • 1: Unicode (For any other language)
Mandatory

HTTP Response

The HTTP response from our system contains the following:

  • Status Code: Indicates the status of the SMS request. A successful submission will return "OK".
  • Message ID: A unique identifier generated, e.g., 760d54eb-3a82-405c-a7a7-0a0096833615.
  • Error Message: A descriptive error code will be included if the request fails.
Status Codes

If the message has been sent successfully, the status code will return as:

OK: 760d54eb-3a82-405c-a7a7-0a0096833615

If the message request has an error, it will return an error code, for example:

1001

Below are an examples of a GET request using the HTTP interface:

Send Single SMS (English)

The message has to be url encoded, and the type parameter must be set to type=0 for English messages.

Request:

https://api.easysendsms.app/bulksms?username=testuser&password=secret&from=Test&to=12345678910&text=Hello%20world&type=0

Output:

OK: 760d54eb-3a82-405c-a7a7-0a0096833615

Send Bulk SMS

A request containing multiple destination numbers will be aborted immediately if any error other than "Invalid mobile number" [Code: 1005] is encountered. If an "Invalid mobile number" [Code: 1005] is found, that destination number will be skipped, and the request will proceed with the next number. A maximum of 30 numbers can be submitted per request. Duplicate numbers will be ignored.

Request:

https://api.easysendsms.app/bulksms?username=testuser&password=secret&from=Test&to=12345678910,12345678910&text=Hello%20world&type=0

Output:

OK: 760d54eb-3a82-405c-a7a7-0a0096833615, OK: b9f12a34-6d78-4e8a-9bfa-2a6c7a63f891

Send Single SMS (Unicode)

The message has to be encoded in the UTF-16BE format, and the type parameter must be set to type=1 for Unicode messages.

Request:

https://api.easysendsms.app/bulksms?username=testuser&password=secret&from=Test&to=12345678910&text=006500610073007900730065006E00640073006D0073002E0063006F006D&type=1

Output:

OK: 34763d84-683e-4b53-bd9f-fc9eb8c532b7

Alternate Method: URI Encoded Unicode Message

The message has to be uri encoded, and the type parameter must be set to type=1 for Unicode messages.

Sending Unicode Text with URI Encoding When sending a message containing non-ASCII characters, such as those in languages like Korean, Japanese, or Arabic, you need to use URI encoding to ensure that the text is transmitted correctly over the HTTP protocol.

URI Encoding is a process where certain characters in the text are replaced with a percent sign (%) followed by two hexadecimal digits representing the character's byte value in UTF-8.

This is necessary because URLs can only be sent over the Internet using the ASCII character set. Example: Suppose you want to send the following Unicode message:
안녕하세요 세상

This message should be URI encoded before sending it via the API. The encoded version would look like this:

Request:

https://api.easysendsms.app/bulksms?username=testuser&password=secret&from=Test&to=12345678910&text=%EC%95%88%EB%85%95%ED%95%98%EC%84%B8%EC%9A%94%20%EC%84%B8%EC%83%81&type=1

Output:

OK: 34763d84-683e-4b53-bd9f-fc9eb8c532b7
API Rate Limit

EasySendSMS API applies rate limits for its SMS API to maintain a high quality of service.

  • Default request rate limit: 30 requests per second per account (can reach up to 150 requests per second per IP address).

Requests exceeding this limit will be rejected with a 429 Too Many Requests HTTP Status. Retry after 1 second.

SMS Status

Status Description
Pending The message has been sent to the route and not yet received by the handset.
Delivered The message has been received by the handset.
Expired The carrier has timed out.
Undelivered The message failed to reach the handset.

API Error Codes

Code Description
1001 Invalid URL. One of the parameters was not provided or left blank.
1002 Invalid username or password parameter.
1003 Invalid type parameter.
1004 Invalid message.
1005 Invalid mobile number.
1006 Invalid sender name.
1007 Insufficient credit.
1008 Internal error (do NOT re-submit the same message again).
1009 Service not available (do NOT re-submit the same message again).
Call The API By Code

var options = new RestClientOptions("")
    {
        MaxTimeout = -1,
    };

var client = new RestClient(options);
var request = new RestRequest("https://api.easysendsms.app/bulksms", Method.Post);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("username", "username");
request.AddParameter("password", "password");
request.AddParameter("to", "12345678900");
request.AddParameter("from", "test");
request.AddParameter("text", "Hello world");
request.AddParameter("type", "0");
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
                                                

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.easysendsms.app/bulksms',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => 'username=username&password=password&to=12345678900&from=test&text=Hello%20world&type=0',
    CURLOPT_HTTPHEADER => array(
    'Content-Type: application/x-www-form-urlencoded'
    ),
));

$response = curl_exec($curl);
curl_close($curl);
echo $response;
                                                    

Unirest.setTimeouts(0, 0);
HttpResponse response = Unirest.post("https://api.easysendsms.app/bulksms")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .field("username", "username")
    .field("password", "password")
    .field("to", "12345678900")
    .field("from", "test")
    .field("text", "Hello world")
    .field("type", "0")
    .asString();
                                                    

import http.client
    
conn = http.client.HTTPSConnection("api.easysendsms.app")
payload = 'username=username&password=password&to=12345678900&from=test&text=Hello%20world&type=0'
headers = {
    'Content-Type': 'application/x-www-form-urlencoded'
}
conn.request("POST", "/bulksms", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8")) 
                                                    

SMS Balance HTTP(s) API

This page provides a comprehensive reference for all features available via the HTTP interface for querying your balance.

The HTTP API allows you to integrate your system (client) with EasySendSMS using HTTP or HTTPS protocols to request and check your account balance securely using SSL encryption.

The client issues either a GET or POST request to the EasySendSMS HTTP API, supplying the required parameters. Our system responds with a text-format HTTP response that indicates the account balance.

This API call retrieves the current credit balance in your account.

API Base URL:
https://api.easysendsms.app/balance

Method: GET, POST

Required Parameters

The following parameters must be included in your API request:

Parameter Description Required
Username Your EasySendSMS username. Yes
Password Your EasySendSMS account password or your API password (if set in your account settings). Yes
HTTP Response

The HTTP response from our system will contain the following information:

Response Format

If the balance request is successful, the response will contain your account balance:

Example:

1000 (Balance)

If the balance query fails, the response will return ERROR: {Error code}.

Example:

1002
Example GET Request

Below is an example of a GET request using the HTTP interface:

Request:

https://api.easysendsms.app/balance?username=testuser&password=secret

Output:

1000 (Balance)

API Rate Limit

To maintain a high quality of service, EasySendSMS API enforces rate limits for its balance query API.

The default request rate limit is 2 requests per minute per account per IP address. The API will reject requests exceeding this limit with a 429 Too Many Requests HTTP status.

You can retry the request after 60 seconds.

API Error Codes

The following table outlines possible error codes you may encounter:

Code Description
1001 Invalid username or password. This indicates the parameter was not provided or was left blank.
1002 Authentication failed.
1007 Inactive or expired demo account.
Call the API with Code

Use the following examples to call the API from different programming languages:


var options = new RestClientOptions("")
    {
        MaxTimeout = -1,
    };
var client = new RestClient(options);
var request = new RestRequest("https://api.easysendsms.app/balance", Method.Post);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("username", "username");
request.AddParameter("password", "password");
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);   
                                                

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.easysendsms.app/balance',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => 'username=username&password=password',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/x-www-form-urlencoded',
    ),
));

$response = curl_exec($curl);
curl_close($curl);
echo $response;
                                                    

Unirest.setTimeouts(0, 0);
HttpResponse response = Unirest.post("https://api.easysendsms.app/balance")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .field("username", "username")
    .field("password", "password")
    .asString();
                                                    

HLR HTTP(s) API

This page provides a detailed reference for all features available via the HTTP interface for HLR (Home Location Register) queries.

The HTTP API allows you to integrate your system (client) with EasySendSMS using the HTTP or HTTPS protocols to request HLR lookups securely with SSL encryption.

The client issues either a GET or POST request to the EasySendSMS HTTP API, supplying the required parameters. Our system responds with a JSON-format HTTP response that indicates the status of the number, including details such as status, MCC, MNC, and whether the number is ported.

Using an HLR Lookup, you can clean your data lists or check the status of a phone number before sending an SMS. This can help save costs on delivery for both Bulk SMS campaigns and single SMS messages. HLR Lookup is commonly used by SMS Service Providers for Mobile Number Portability enquiries to obtain MCC and MNC (IMSI) information.

Our HLR Lookup tool also allows users to perform bulk checks of up to 30 numbers at once by separating them with commas. This feature saves time and enhances efficiency, making it ideal for businesses and individuals who need to verify multiple phone numbers quickly. By integrating our HLR API, you can seamlessly incorporate this functionality into your application, ensuring accurate and up-to-date information on number status.

API Base URL:
https://api.easysendsms.app/hlr

Method: GET, POST

Required Parameters

The following parameters must be included in your API request:

Parameter Description Required
Username Your EasySendSMS username. Yes
Password Your EasySendSMS account password or your API password (if set in your account settings). Yes
Number The subscriber's MSISDN (mobile number) to check. Yes
HTTP Response

The HTTP response from our system will contain the following information:

Response JSON Format

If the HLR query is successful, the status code will be returned as follows

Example:


{
    "33644444444": {
        "number": "33644444444",
        "country": "France",
        "err_desc": "Dead",
        "operator": "Transatel",
        "type": "Mobile",
        "mccmnc": "",
        "roaming": "False",
        "err_code": "1",
        "status": "Undelivered",
        "ported": "False"
    }
}
                                    

If the HLR query fails, the response will return ERROR: {Error description}.

Example:

{"error":"Authentication failed"}

Example GET Request

Below is an example of a GET request using the HTTP interface:

https://api.easysendsms.app/hlr?username=testuser&password=secret&number=33644444444

Output:


{
    "33644444444": {
        "number": "33644444444",
        "country": "France",
        "err_desc": "Dead",
        "operator": "Transatel",
        "type": "Mobile",
        "mccmnc": "",
        "roaming": "False",
        "err_code": "1",
        "status": "Undelivered",
        "ported": "False"
    },
    "33644444445": {
        "number": "33644444445",
        "country": "France",
        "err_desc": "Dead",
        "operator": "Transatel",
        "type": "Mobile",
        "mccmnc": "",
        "roaming": "False",
        "err_code": "1",
        "status": "Undelivered",
        "ported": "False"
    }
}
                                    

HLR Response Fields

The following table outlines the possible fields returned in the HLR response:

Field Description
number The subscriber's MSISDN to check.
country The subscriber's network country.
err_desc Description of the status of the number. Possible values include:
  • Live
  • Dead
  • Inconclusive
  • No Teleservice Provisioned
  • Absent Subscriber
operator The subscriber's mobile network operator.
type The type of number (e.g., Mobile, Fixed).
mccmnc The actual MCC and MNC of the subscriber.
roaming Indicates whether the subscriber number is currently roaming.
err_code Error code corresponding to the err_desc. Possible values include:
  • 0 = Active mobile number
  • 1 = Number decommissioned by the owning network
  • 5 = Unable to retrieve a response from the network for this number
  • 11 = Number unable to receive calls or SMS messages (e.g., data SIM)
  • 27 = Absent Subscriber
status The status of the number. This field is linked with err_code and err_desc. Possible values include:
  • Delivered
  • Undelivered

API Rate Limit

To maintain a high quality of service, EasySendSMS API enforces rate limits for its HLR API.

The default request rate limit is 30 requests per second per account per IP address. The API will reject requests exceeding this limit with a 429 Too Many Requests HTTP status.

You can retry the request after 1 second.

HLR API Error Codes

The following table outlines possible error codes you may encounter:

Error Text Description
Invalid Number Parameter Invalid Number. This means the parameter was not provided or was left blank.
Invalid Password Parameter Invalid password. This means the parameter was not provided or was left blank.
Invalid Username Parameter Invalid username. This means the parameter was not provided or was left blank.
Authentication failed Invalid username or password, or account not active or does not exist.
Insufficient credits HLR lookup account has insufficient credits.
Http Error Code: 429 API calls quota exceeded! Maximum allowed is 30 requests per second.
HLR Code Examples

var options = new RestClientOptions("")
    {
        MaxTimeout = -1,
    };
var client = new RestClient(options);
var request = new RestRequest("https://api.easysendsms.app/hlr", Method.Post);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("username", "username");
request.AddParameter("password", "password");
request.AddParameter("number", "12345678900");
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);   
                                        

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.easysendsms.app/hlr',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => 'username=username&password=password&number=12345678900',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/x-www-form-urlencoded'
    ),
));

$response = curl_exec($curl);
curl_close($curl);
echo $response;
                                            

Unirest.setTimeouts(0, 0);
HttpResponse response = Unirest.post("https://api.easysendsms.app/hlr")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .field("username", "username")
    .field("password", "password")
    .field("number", "12345678900")
    .asString();
                                            

Number Validation (NV) HTTP(s) API

This page provides a comprehensive reference for all features available via the HTTP interface for number validation queries.

The HTTP API allows you to integrate your system (client) with the Number Validation service using HTTP or HTTPS protocols to request network information securely with SSL encryption.

The client issues either a GET or POST request to the NV HTTP API, supplying the required parameters. Our system responds with a JSON-format HTTP response that indicates the status of the number, including the country, MCC, MNC, and operator information.

This service validates if the phone number is in the correct format, verifies the correct country code, and identifies the original network where the number was registered. Unlike the HLR Lookup, the Number Validation service is offline and does not provide live data.

Our Number Validation tool also allows users to perform bulk checks of up to 30 numbers at once by separating them with commas. This feature saves time and enhances efficiency, making it ideal for businesses and individuals who need to verify multiple phone numbers quickly. By integrating our NV API, you can seamlessly incorporate this functionality into your application, ensuring accurate and up-to-date information on number status.

API Base URL
https://api.easysendsms.app/nv

Method: GET, POST

Required Parameters

The following parameters must be included in your API request:

Parameter Description Required
Username Your NV service username. Yes
Password Your NV account password or your API password (if set in your account settings). Yes
Number Comma-separated list of numbers to check. Yes

HTTP Response

The HTTP response from our system will contain the following information:

Response JSON Format

If the query is successful, the status code will be returned as shown below:

Example:


{
    "results": [
        {
            "Status": "INVALID",
            "Country": "Australia",
            "ISO3166_2": "AU",
            "CC": "61",
            "NetName": "",
            "MCC": "505",
            "MNC": "",
            "OPERATOR": "",
            "Type": "SUPPLEMENTARY SERVICES",
            "NetType": "",
            "MSISDN": "61111111111111"
        }
    ]
}
                                    

If the query is incorrect, it will return ERROR: {Error description}

Example:

{"error":"Authentication failed"}

Example GET Request

Below is an example of a GET method request using the HTTP interface:

https://api.easysendsms.app/nv?username=testuser&password=secret&number=61111111111111

Output:


{
    "results": [
        {
            "Status": "INVALID",
            "Country": "Australia",
            "ISO3166_2": "AU",
            "CC": "61",
            "NetName": "",
            "MCC": "505",
            "MNC": "",
            "OPERATOR": "",
            "Type": "SUPPLEMENTARY SERVICES",
            "NetType": "",
            "MSISDN": "61111111111111"
        }
    ]
}
                                    

Example for Bulk Query (Max 30 numbers per request)

You can also perform a bulk number validation by supplying up to 30 numbers, separated by commas:

https://api.easysendsms.app/nv?username=testuser&password=secret&number=123456789999,123456789000

Output:


{
    "results": [
        {
            "Status": "VALID",
            "Country": "United States of America",
            "ISO3166_2": "US",
            "CC": "1",
            "NetName": "",
            "MCC": "310-316",
            "MNC": "",
            "OPERATOR": "",
            "Type": "FIXED",
            "NetType": "",
            "MSISDN": "123456789999"
        },
        {
            "Status": "VALID",
            "Country": "United States of America",
            "ISO3166_2": "US",
            "CC": "1",
            "NetName": "",
            "MCC": "310-316",
            "MNC": "",
            "OPERATOR": "",
            "Type": "FIXED",
            "NetType": "",
            "MSISDN": "123456789000"
        }
    ]
}
                                    
API Rate Limit

To maintain a high quality of service, the NV API enforces rate limits. The default request rate limit is 30 requests per second per account per IP address.

The API will reject requests exceeding this limit with a 429 Too Many Requests HTTP status. You can retry the request after 1 second.

NV API Response Fields

Field Description
Status VALID: Indicates that the number format and details are correct and belong to either a mobile or fixed type.
INVALID: Indicates that the number is neither a valid mobile number nor a landline (fixed) number. However, the API will still display the type of number in the response.
Country The country where the number is registered (e.g., United States of America).
ISO3166_2 The two-letter ISO 3166-1 alpha-2 country code (e.g., US for the United States).
CC The country calling code associated with the number (e.g., 1 for the United States).
NetName The name of the network associated with the number, if available.
MCC The Mobile Country Code (MCC) associated with the number (e.g., 310-316 for the United States).
MNC The Mobile Network Code (MNC) associated with the number, if available.
OPERATOR The operator or service provider associated with the number, if available.
Type The type of number, such as "MOBILE", "FIXED", or "SUPPLEMENTARY SERVICES".
NetType The network type associated with the number, if available.
MSISDN The full phone number including the country code (e.g., 123456789000).
API Error Codes
Error Text Description
Invalid Number Parameter Invalid number. This means the parameter was not provided, left blank, or the number format is incorrect.
Invalid Password Parameter Invalid password. This means the parameter was not provided or left blank.
Invalid Username Parameter Invalid username. This means the parameter was not provided or left blank.
Authentication failed Invalid username or password, or account not active or does not exist.
Insufficient credits The account has insufficient credits.
Http Error Code: 429 API calls quota exceeded! Maximum allowed is 30 requests per second.
NV Code Examples

var options = new RestClientOptions("")
    {
        MaxTimeout = -1,
    };
var client = new RestClient(options);
var request = new RestRequest("https://api.easysendsms.app/nv", Method.Post);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("username", "username");
request.AddParameter("password", "password");
request.AddParameter("number", "12345678900");
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
                                        

$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.easysendsms.app/nv',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => 'username=username&password=password&number=12345678900',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/x-www-form-urlencoded'
    ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
                                            

Unirest.setTimeouts(0, 0);
HttpResponse response = Unirest.post("https://api.easysendsms.app/nv")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .field("username", "username")
    .field("password", "password")
    .field("number", "12345678900")
    .asString();