API Overview

Our SMS API allows you to send text messages programmatically via HTTP requests. The API is RESTful and returns JSON responses.

Base URL

https://ezzysms.com/api/v1/messaging

All API endpoints are accessed via HTTPS and follow REST principles. The API accepts JSON payloads and returns JSON responses.

Rate Limits

API calls are limited to 1000 requests per hour per account. Exceeding this limit will result in a 429 Too Many Requests error.

Authentication

All API requests require authentication using your account username and password. Use HTTP Basic Authentication by including your credentials in the request header:

                Authorization: Basic base64(username:password)
                Content-Type: application/json
            

Alternatively, you can include credentials directly in the request body or as URL parameters. Use the same username and password you use to login to your account. Always use HTTPS to keep your credentials secure.

Authentication Methods

Method	Implementation	Example
HTTP Basic Auth	Authorization header	Authorization: Basic
Request Body	JSON payload	{ "username": "username", "password": "password" }
URL Parameters	Query string	?username=username& password=password

Send SMS

Send SMS messages to recipients.

Endpoint

https://ezzysms.com/api/v1/messaging/

Parameters

Parameter	Type	Description
to Required	string	Recipient's phone number in E.164 format (e.g., +25671234567)
message Required	string	SMS message content (max 160 characters for single SMS)
from Optional	string	Sender ID or phone number (if not provided, uses default)

Example

https://ezzysms.com/api/v1/messaging?username=your_username&password=Password&message=your%20message&to=0751234567,0771234567

Use Sender ID if provided

https://ezzysms.com/api/v1/messaging?username=your_username&password=Password&message=your%20message&to=0751234567,0771234567&from=SenderID

Response Format

Success Response

200

Processed - SMS has been processed successfully

201

Sent - SMS has been sent to the carrier

202

Queued - SMS is queued for delivery

                {

                "status": "success",

                "to": "+25671234567",

                "message": "Your verification code is 123456",

                "status_code": 201,

                "cost": 40,

                "status": "Sent",

                }

Error Codes

When an error occurs, the API returns an appropriate HTTP status code along with error details in JSON format.

401

Unauthorized - Missing or Invalid Logins Details

402

InvalidSenderId - The sender ID provided is invalid or not approved

403

InvalidPhoneNumber - The recipient phone number format is invalid

404

UnsupportedNumberType - Phone number type is not supported

405

InsufficientBalance - Account balance is insufficient to send SMS

406

UserInBlacklist - Recipient is in your account blacklist

407

CouldNotRoute - Unable to find route for the destination number

409

DoNotDisturbRejection - Message rejected due to Do Not Disturb settings

500

InternalServerError - Something went wrong on our server

501

GatewayError - Error occurred at the gateway level

502

RejectedByGateway - Message rejected by the gateway

Error Response Format

                {

                "status": "error",

                "error_code": 403,

                "message": "InvalidPhoneNumber",

                "details": "The phone number format is invalid.",

                }

Check Balance

Get your account balance.

Endpoint

GET /

https://ezzysms.com/api/v1/balance/

Example

https://ezzysms.com/api/v1/balance?username=your_username&password=Password

Code Examples

JavaScript (Node.js)

                const fetch = require('node-fetch');

                const sendSMS = async () => {
                const username = 'your_username';
                const password = 'your_password';
                const credentials = btoa(`${username}:${password}`);
                
                try {
                    const response = await fetch('https://ezzysms.com/api/v1/messaging/', {
                    method: 'POST',
                    headers: {
                        'Authorization': `Basic ${credentials}`,
                        'Content-Type': 'application/json'
                    },
                    body: JSON.stringify({
                        to: '+25671234567',
                        message: 'Hello from SMS API!',
                        from: 'YourApp'
                    })
                    });

                    const result = await response.json();
                    console.log('SMS sent:', result);
                } catch (error) {
                    console.error('Error:', error);
                }
                };

                sendSMS();
            

Python

                import requests
                import json
                import base64

                def send_sms():
                    url = "https://ezzysms.com/api/v1/messaging/"
                    
                    username = "your_username"
                    password = "your_password"
                    credentials = base64.b64encode(f"{username}:{password}".encode()).decode()
                    
                    headers = {
                        "Authorization": f"Basic {credentials}",
                        "Content-Type": "application/json"
                    }
                    
                    payload = {
                        "to": "+25671234567",
                        "message": "Hello from SMS API!",
                        "from": "YourApp"
                    }
                    
                    try:
                        response = requests.post(url, headers=headers, json=payload)
                        result = response.json()
                        print("SMS sent:", result)
                    except requests.exceptions.RequestException as e:
                        print("Error:", e)

                send_sms()
            

PHP

                function sendSMS() {
                    $url = 'https://ezzysms.com/api/v1/messaging/';
                    $username = 'your_username';
                    $password = 'your_password';
                    $credentials = base64_encode($username . ':' . $password);
                    
                    $data = array(
                        'to' => '+25671234567',
                        'message' => 'Hello from SMS API!',
                        'from' => 'YourApp'
                    );
                    
                    $options = array(
                        'http' => array(
                            'header' => [
                                "Authorization: Basic $credentials",
                                "Content-Type: application/json"
                            ],
                            'method' => 'POST',
                            'content' => json_encode($data)
                        )
                    );
                    
                    $context = stream_context_create($options);
                    $result = file_get_contents($url, false, $context);
                    
                    if ($result === FALSE) {
                        echo "Error sending SMS";
                    } else {
                        echo "SMS sent: " . $result;
                    }
                }

                sendSMS();
            

cURL

                curl -X POST "https://ezzysms.com/api/v1/messaging/" \
                -H "Authorization: Basic $(echo -n 'your_username:your_password' | base64)" \
                -H "Content-Type: application/json" \
                -d '{
                    "to": "+25671234567",
                    "message": "Hello from SMS API!",
                    "from": "YourApp"
                }'
            