Delivery Status & Monitoring

Track the delivery status of sent SMS messages and view detailed statistics about your campaigns.

Check Message Status

Get the delivery status of one or multiple SMS messages by their IDs.

Endpoint:

GET https://www.lightsms.com/external/get/status.php

Required Parameters:

Parameter	Type	Description
login	string	Your LightSMS login
signature	string	MD5 signature
state	string	SMS ID(s) - comma-separated for multiple messages
timestamp	integer	UTC timestamp (valid for 10 seconds)

Optional Parameters:

Parameter	Type	Description
return	string	Response format: json or xml (default: plain text)

---

Single Message Status

Check the status of a single SMS message.

Example Request:

curl "https://www.lightsms.com/external/get/status.php?login=YourLogin&signature=generated_signature&state=4091297100348873330001&timestamp=1732809600&return=json"

Response (JSON):

{
    "4091297100348873330001": "delivered"
}

---

Multiple Messages Status

Check the status of multiple SMS messages at once (comma-separated IDs).

Example Request:

curl "https://www.lightsms.com/external/get/status.php?login=YourLogin&signature=generated_signature&state=4091297100348873330001,4091297100348880230003&timestamp=1732809600&return=json"

Response (JSON):

{
    "4091297100348873330001": "delivered",
    "4091297100348880230003": "not_deliver"
}

Response (XML):

<?xml version="1.0" encoding="utf-8"?>
<response>
    <statuses>
        <status id_sms="4091297100348873330001" status="delivered" />
        <status id_sms="4091297100348880230003" status="not_deliver" />
    </statuses>
</response>

---

Status Values

Messages can have the following statuses:

Status	Description
delivered	Message successfully delivered to recipient
not_deliver	Message failed to deliver
expired	Message expired before delivery (exceeded validity time)
pending	Message is being processed or queued
sent	Message sent to operator but delivery not yet confirmed

---

Code Examples

PHP

<?php
function getMessageStatus($login, $apiKey, $messageIds) {
    // Get timestamp
    $timestamp = trim(file_get_contents('https://www.lightsms.com/external/get/timestamp.php'));

    // Prepare parameters
    $params = [
        'login' => $login,
        'state' => $messageIds, // Single ID or comma-separated IDs
        'timestamp' => $timestamp,
        'return' => 'json'
    ];

    // Create signature
    ksort($params);
    $signature = md5(implode($params) . $apiKey);
    $params['signature'] = $signature;

    // Make request
    $url = 'https://www.lightsms.com/external/get/status.php?' . http_build_query($params);
    $response = file_get_contents($url);

    return json_decode($response, true);
}

// Configuration
$login = 'YourLogin';
$apiKey = 'your_api_key_here';

// Check single message
$messageId = '4091297100348873330001';
$status = getMessageStatus($login, $apiKey, $messageId);
echo "Message status: " . $status[$messageId] . "\n";

// Check multiple messages
$messageIds = '4091297100348873330001,4091297100348880230003';
$statuses = getMessageStatus($login, $apiKey, $messageIds);
foreach ($statuses as $id => $status) {
    echo "Message $id: $status\n";
}
?>

---

Python

import requests
import hashlib
from urllib.parse import urlencode

def get_message_status(login, api_key, message_ids):
    # Get timestamp
    timestamp_response = requests.get('https://www.lightsms.com/external/get/timestamp.php')
    timestamp = timestamp_response.text.strip()

    # Prepare parameters
    params = {
        'login': login,
        'state': message_ids,  # Single ID or comma-separated IDs
        'timestamp': timestamp,
        'return': 'json'
    }

    # Create signature
    sorted_params = sorted(params.items())
    param_string = ''.join([str(value) for key, value in sorted_params])
    signature = hashlib.md5((param_string + api_key).encode()).hexdigest()
    params['signature'] = signature

    # Make request
    url = f'https://www.lightsms.com/external/get/status.php?{urlencode(params)}'
    response = requests.get(url)

    return response.json()

# Configuration
LOGIN = 'YourLogin'
API_KEY = 'your_api_key_here'

# Check single message
message_id = '4091297100348873330001'
status = get_message_status(LOGIN, API_KEY, message_id)
print(f"Message status: {status[message_id]}")

# Check multiple messages
message_ids = '4091297100348873330001,4091297100348880230003'
statuses = get_message_status(LOGIN, API_KEY, message_ids)
for msg_id, msg_status in statuses.items():
    print(f"Message {msg_id}: {msg_status}")

---

JavaScript (Node.js)

const crypto = require('crypto');
const axios = require('axios');

async function getMessageStatus(login, apiKey, messageIds) {
    // Get timestamp
    const timestampResponse = await axios.get('https://www.lightsms.com/external/get/timestamp.php');
    const timestamp = timestampResponse.data.trim();

    // Prepare parameters
    const params = {
        login: login,
        state: messageIds,  // Single ID or comma-separated IDs
        timestamp: timestamp,
        return: 'json'
    };

    // Create signature
    const sortedKeys = Object.keys(params).sort();
    const paramString = sortedKeys.map(key => params[key]).join('');
    const signature = crypto.createHash('md5').update(paramString + apiKey).digest('hex');
    params.signature = signature;

    // Make request
    const queryString = new URLSearchParams(params).toString();
    const url = `https://www.lightsms.com/external/get/status.php?${queryString}`;
    const response = await axios.get(url);

    return response.data;
}

// Configuration
const LOGIN = 'YourLogin';
const API_KEY = 'your_api_key_here';

(async () => {
    // Check single message
    const messageId = '4091297100348873330001';
    const status = await getMessageStatus(LOGIN, API_KEY, messageId);
    console.log(`Message status: ${status[messageId]}`);

    // Check multiple messages
    const messageIds = '4091297100348873330001,4091297100348880230003';
    const statuses = await getMessageStatus(LOGIN, API_KEY, messageIds);
    for (const [id, msgStatus] of Object.entries(statuses)) {
        console.log(`Message ${id}: ${msgStatus}`);
    }
})();

---

Monthly Statistics

Get detailed statistics for sent messages grouped by day for a specific month.

Endpoint:

GET https://www.lightsms.com/external/get/stat_by_month.php

Required Parameters:

Parameter	Type	Description
login	string	Your LightSMS login
signature	string	MD5 signature
month	string	Year and month in format YYYY-MM
timestamp	integer	UTC timestamp

Optional Parameters:

Parameter	Type	Description
return	string	Response format: array, json, or xml

---

Statistics Request Example

Request:

curl "https://www.lightsms.com/external/get/stat_by_month.php?login=YourLogin&signature=generated_signature&month=2025-01&timestamp=1732809600&return=json"

Response (JSON):

{
    "2025-01-15": {
        "deliver": {
            "cost": "1738.300",
            "parts": "3909"
        },
        "not_deliver": {
            "cost": "1057.700",
            "parts": "2380"
        },
        "expired": {
            "cost": "194.300",
            "parts": "436"
        }
    },
    "2025-01-16": {
        "deliver": {
            "cost": "2901.500",
            "parts": "5803"
        },
        "not_deliver": {
            "cost": "1796.000",
            "parts": "3592"
        },
        "expired": {
            "cost": "357.000",
            "parts": "714"
        }
    }
}

Response (XML):

<?xml version="1.0" encoding="utf-8"?>
<response>
    <statistics>
        <date date="2025-01-15"
              deliver_cost="1738.300" deliver_parts="3909"
              not_deliver_cost="1057.700" not_deliver_parts="2380"
              expired_cost="194.300" expired_parts="436" />
        <date date="2025-01-16"
              deliver_cost="2901.500" deliver_parts="5803"
              not_deliver_cost="1796.000" not_deliver_parts="3592"
              expired_cost="357.000" expired_parts="714" />
    </statistics>
</response>

---

Statistics Response Fields

Field	Description
deliver	Successfully delivered messages
not_deliver	Failed delivery messages
expired	Expired messages (exceeded validity time)
cost	Total cost for messages in that category
parts	Number of message parts sent

---

Error Handling

Common errors when checking status:

Error 17: SMS ID Not Specified

Problem: state parameter is missing

Solution: Include state parameter with message ID(s)

---

Error 18: Status Not Obtained

Problem: Message ID doesn't exist or is invalid

Solutions:

• ✅ Verify message ID is correct
• ✅ Check if message was successfully sent
• ✅ Message IDs are returned in send response

---

Next Steps

• Send SMS messages
• View error codes
• Set up webhooks for real-time status updates

---

Need Help?

For questions about delivery status monitoring:

• Email: [email protected]
• Phone: Contact Information
• Hours: Monday-Friday, 8:00-20:00 (EET)