EasySendSMS API

Help Center EasySendSMS API EasySendSMS.com REST API

EasySendSMS.com REST API

EasySendSMS.com provides a powerful REST API that allows businesses and developers to send and manage SMS communications, perform HLR queries, and validate phone numbers with ease. This API is designed to integrate seamlessly with your applications, offering a reliable way to enhance your communication capabilities. In this blog, we will explore how to utilize the EasySendSMS REST API for sending SMS messages, conducting HLR lookups, and validating phone numbers using your API key for authentication.

Getting Started with EasySendSMS REST API

Before you can start sending SMS or performing number validations, you need to set up your account and obtain your API key. Here’s a quick guide on how to get started:

Sign Up and Obtain Your API Key:
- Create an account on EasySendSMS.com.
- Navigate to the API settings section within your dashboard to generate your API key.
Set Up Your Environment:
- Depending on your programming language, install the necessary libraries to make HTTP requests, such as HttpClient in .NET, requests in Python, or Axios in JavaScript.
Understand the Documentation:
- Visit the EasySendSMS Developers Page to familiarize yourself with the API endpoints and the required parameters.

Sending SMS Messages with EasySendSMS REST API

Sending SMS is one of the core functionalities of the EasySendSMS API. Here’s a detailed look at how to send SMS using the REST API.

API Endpoint for Sending SMS

The endpoint for sending an SMS is:

POST https://restapi.easysendsms.app/v1/rest/sms/send

Required Headers

Your API requests must include the following headers:

apikey: Your API key for authentication.
Content-Type: application/json
Accept: application/json

Request Body Schema

All SMS requests should use the application/json content type, and the request body should be formatted in JSON. The following parameters are required:

from: The sender's name or number. For numeric values, the max length is 15 characters. For alphanumeric values, the max length is 11 characters. If you want the sender's name to appear with a plus sign, prefix it in the request (URL encoded).
to: The recipient’s mobile number in international format, without the plus sign or leading zeros. You can send messages to multiple numbers by separating them with commas (maximum 30 numbers per request).
text: The message content. It can be plain text or Unicode, with a maximum length of 5 parts (concatenated messages).
type: The message type. Use 0 for plain text (GSM 3.38 encoding) and 1 for Unicode.
scheduled (optional): The scheduled date and time for sending the message in ISO 8601 format. The time is in UTC.

Example Request

Here’s an example of how to send an SMS using the API in Python:

python

import requests

headers = {
    'apikey': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}

data = {
    "from": "YourSenderName",
    "to": "12345678900,19876543210",
    "text": "Hello, this is a test message!",
    "type": "0"
}

response = requests.post('https://restapi.easysendsms.app/v1/rest/sms/send', headers=headers, json=data)

print(response.json())

Handling Responses

The API returns a JSON response indicating the success or failure of your request. The response will include message IDs for successful sends or error codes if the request fails.

Example Success Response:

json

{
    "status": "OK",
    "scheduled": "Now",
    "messageIds": [
        "OK: 69991a73-a560-429f-9c5a-3251dc1522bb"
    ]
}

Example Error Response:

json

{
    "error": 4012,
    "description": "Invalid mobile number."
}

Performing HLR Lookup Using EasySendSMS REST API

HLR (Home Location Register) lookup is used to verify the status of a mobile number, including whether it is active, its network operator, and whether it is currently roaming. This can help reduce SMS delivery failures.

API Endpoint for HLR Lookup

To perform an HLR lookup, send a request to:

POST https://restapi.easysendsms.app/v1/rest/hlr/query

Request Body Schema

The request body should be in JSON format and include the following parameter:

number: The mobile number(s) to be checked, formatted without the plus sign or leading zeros. You can check multiple numbers by separating them with commas (maximum 30 numbers per request).

Example Request

Here’s how to perform an HLR lookup in PHP:

php

<?php
$apiKey = "YOUR_API_KEY";
$url = "https://restapi.easysendsms.app/v1/rest/hlr/query";

$data = array(
    'number' => '19876543210'
);

$options = array(
    'http' => array(
        'header'  => "apikey: $apiKey\r\n" .
                     "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($data),
    ),
);

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === FALSE) { /* Handle error */ }

var_dump($result);
?>

Understanding the HLR Response

The response will provide details about the mobile number, including:

status: Whether the number is live or not.
country: The country of the mobile number.
operatorName: The network operator.
roaming: Whether the number is currently roaming.

Example Success Response:

json

{
    "12345678900": {
        "number": "12345678900",
        "country": "United States of America",
        "err_desc": "Live",
        "operatorName": "First Communications",
        "type": "Landline",
        "mccmnc": "-",
        "roaming": "False",
        "err_code": "0",
        "status": "Delivered",
        "ported": "True"
    }
}

Number Validation with EasySendSMS REST API

The Number Validation (NV) feature allows you to validate the format and status of a phone number before sending an SMS. This is especially useful for ensuring that messages are sent to valid and reachable numbers.

API Endpoint for Number Validation

To validate a number, use the following endpoint:

POST https://restapi.easysendsms.app/v1/rest/nv/query

Request Body Schema

The request body should include:

number: The mobile number(s) to be validated, without the plus sign or leading zeros. Multiple numbers can be separated by commas (maximum 30 numbers per request).

Example Request

Here’s how to perform number validation using the API in C#:

csharp

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("apikey", "YOUR_API_KEY");

        var content = new StringContent("{\"number\":\"19876543210\"}", Encoding.UTF8, "application/json");

        var response = await client.PostAsync("https://restapi.easysendsms.app/v1/rest/nv/query", content);
        var responseString = await response.Content.ReadAsStringAsync();

        Console.WriteLine(responseString);
    }
}

Analyzing the Validation Response

The validation response will include the status of the number, the country, the network operator, and other relevant information.

Example Success Response:

json

{
    "results": [
        {
            "status": "VALID",
            "country": "United States of America",
            "iso3166_2": "US",
            "cc": "1",
            "netName": "",
            "mcc": "310",
            "mnc": "316",
            "operator": "",
            "type": "FIXED",
            "netType": "",
            "msisdn": "12345678900"
        }
    ]
}

Best Practices for Using EasySendSMS REST API

To make the most of the EasySendSMS API, it’s important to follow best practices:

API Key Security: Keep your API key secure and never expose it in client-side code or public repositories.
Rate Limiting: Respect the API’s rate limits to avoid your requests being rejected. Implement a queuing system in your application to manage the rate at which requests are sent.
Error Handling: Implement robust error handling to manage different types of errors, such as invalid numbers, insufficient credits, or network issues.
Monitor Usage: Regularly monitor your API usage and SMS credits to avoid unexpected disruptions.
Use Valid Numbers: Validate phone numbers before sending SMS to reduce the number of failed deliveries.

Conclusion

The EasySendSMS REST API is a comprehensive tool for businesses and developers who need to integrate SMS functionality, perform HLR lookups, and validate phone numbers in their applications. By following the steps and best practices outlined in this blog, you can ensure that your communication is effective, reliable, and secure.

For more detailed information, visit the EasySendSMS Developers Page. This resource provides extensive documentation and examples to help you make the most of the API. Whether you’re sending marketing messages, transactional alerts, or validating phone numbers, EasySendSMS offers the tools you need to succeed.