Introduction

This document aims to provide you with all the necessary information for working with the EasySms API.

Base URL

https://www.easysms.co

Authenticating requests

This API is authenticated by sending an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token by visiting your dashboard and clicking Generate API token.

Security

Protocol

You must use the HTTPS protocol for every request to EasySms. HTTP is not supported.

TLS and certificates

TLS (Transport Layer Security) is a cryptographic protocol that ensures secure communication over a network. It's commonly used to secure connections between web browsers and servers, email servers, and other types of communication. Certificates play a crucial role in TLS. They are digital documents that verify the authenticity of a website or server. When a user connects to a website over HTTPS (HTTP Secure), the server presents its certificate to prove its identity. If the certificate is valid and trusted, a secure connection is established. Certificates contain information such as the issuer (a trusted Certificate Authority), the entity it belongs to, a digital signature, and the public key. This encryption process helps protect data transmitted between the client (such as a web browser) and the server, ensuring confidentiality and integrity.

Status Codes

The errors that API endpoints may return are listed below.

Endpoints

Send Sms

requires authentication

You can use this endpoint to send bulk SMS messages to your recipients. The receiver list can contain a maximum of 1000 recipients.

curl --request POST \
    "https://www.easysms.co/api/send-sms" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"receivers\": [
        {
            \"phone\": \"358403536665\"
        }
    ],
    \"text\": \"Test Sms\"
}"

$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://www.easysms.co/api/send-sms',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'receivers' => [
                [
                    'phone' => '358403536665',
                ],
            ],
            'text' => 'Test Sms',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

const url = new URL(
    "https://www.easysms.co/api/send-sms"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "receivers": [
        {
            "phone": "358403536665"
        }
    ],
    "text": "Test Sms"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

import requests
import json

url = 'https://www.easysms.co/api/send-sms'
payload = {
    "receivers": [
        {
            "phone": "358403536665"
        }
    ],
    "text": "Test Sms"
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

{
    "status": true,
    "message": "Messages sent.",
    "data": null
}
 

{
    "status": false,
    "message": "Unauthenticated.",
    "data": null
}
 

{
    "status": false,
    "message": "The given data was invalid.",
    "data": null,
    "errors": {
        "receivers.0.phone": [
            "The receivers.0.phone format is invalid.",
            "The receivers.0.phone must be at least 10 characters."
        ]
    }
}
 

Create Otp

requires authentication

This endpoint lets you send a otp code.

curl --request POST \
    "https://www.easysms.co/api/create-otp" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"phone\": \"358403536665\"
}"

$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://www.easysms.co/api/create-otp',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'phone' => '358403536665',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

const url = new URL(
    "https://www.easysms.co/api/create-otp"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "phone": "358403536665"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

import requests
import json

url = 'https://www.easysms.co/api/create-otp'
payload = {
    "phone": "358403536665"
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

{
    "status": true,
    "message": "Otp sent.",
    "data": null
}
 

{
    "status": false,
    "message": "Unauthenticated.",
    "data": null
}
 

{
    "status": false,
    "message": "The given data was invalid.",
    "data": null,
    "errors": {
        "phone": [
            "The phone format is invalid.",
            "The phone must be at least 10 characters."
        ]
    }
}
 

Validate Otp

requires authentication

This endpoint lets you validate code.

curl --request POST \
    "https://www.easysms.co/api/validate-otp" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"phone\": \"358403536665\",
    \"code\": 123456
}"

$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://www.easysms.co/api/validate-otp',
    [
        'headers' => [
            'Authorization' => 'Bearer {YOUR_AUTH_KEY}',
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'phone' => '358403536665',
            'code' => 123456.0,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));

const url = new URL(
    "https://www.easysms.co/api/validate-otp"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "phone": "358403536665",
    "code": 123456
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

import requests
import json

url = 'https://www.easysms.co/api/validate-otp'
payload = {
    "phone": "358403536665",
    "code": 123456
}
headers = {
  'Authorization': 'Bearer {YOUR_AUTH_KEY}',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

response = requests.request('POST', url, headers=headers, json=payload)
response.json()

{
    "status": true,
    "message": "OTP is valid",
    "data": null
}
 

{
    "status": false,
    "message": "Unauthenticated.",
    "data": null
}
 

{
    "status": false,
    "message": "OTP does not exist",
    "data": null
}
 

Phone Number Standard

In all requests, the phone number must be sent with the country code added and without + or any special characters at the beginning.