Blacklist Management

Manage your blacklist to honor opt-out requests and comply with SMS regulations.

Overview

The blacklist allows you to:

• 🚫 Block specific numbers from receiving messages
• ✅ Comply with opt-out requests from recipients
• 🔍 Check if a number is blacklisted before sending
• 📝 Track blacklist reasons with descriptions

Automatic Blocking

When you attempt to send SMS to a blacklisted number, you'll receive error code 13 and the message won't be sent.

---

Search in Blacklist

Check if a phone number is in your blacklist.

Endpoint:

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

Required Parameters:

Parameter	Type	Description
login	string	Your LightSMS login
signature	string	MD5 hash signature
phone	string	Phone number to check
timestamp	integer	UTC timestamp

Optional Parameters:

Parameter	Type	Description
return	string	Response format: json or xml

Example Request (JSON)

curl "https://www.lightsms.com/external/get/find_on_stop.php?login=YourLogin&signature=generated_signature&phone=37061234567&timestamp=1732809600&return=json"

Response - Number Found

{
    "time_in": "2024-08-29 11:07:43",
    "description": "Customer requested opt-out"
}

Response - Number Not Found

{}

Empty response means the number is NOT in the blacklist.

Response (XML)

<?xml version="1.0" encoding="utf-8"?>
<response>
    <time_in>2024-08-29 11:07:43</time_in>
    <description>Customer requested opt-out</description>
</response>

---

Add Number to Blacklist

Add a phone number to your blacklist.

Endpoint:

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

Required Parameters:

Parameter	Type	Description
login	string	Your LightSMS login
signature	string	MD5 hash signature
phone	string	Phone number to add
timestamp	integer	UTC timestamp

Optional Parameters:

Parameter	Type	Description
return	string	Response format: json or xml

Example Request

curl "https://www.lightsms.com/external/get/add2stop.php?login=YourLogin&signature=generated_signature&phone=37061234567&timestamp=1732809600&return=json"

Response (JSON)

{
    "id": "4419373"
}

Response (XML)

<?xml version="1.0" encoding="utf-8"?>
<response>
    <id>4419374</id>
</response>

---

PHP Example

<?php
class BlacklistManager {
    private $login;
    private $apiKey;

    public function __construct($login, $apiKey) {
        $this->login = $login;
        $this->apiKey = $apiKey;
    }

    private function getTimestamp() {
        return trim(file_get_contents('https://www.lightsms.com/external/get/timestamp.php'));
    }

    private function createSignature($params) {
        ksort($params);
        return md5(implode($params) . $this->apiKey);
    }

    /**
     * Check if phone number is blacklisted
     * @return array|null Blacklist info or null if not found
     */
    public function isBlacklisted($phone) {
        $timestamp = $this->getTimestamp();

        $params = [
            'login' => $this->login,
            'phone' => $phone,
            'timestamp' => $timestamp,
            'return' => 'json'
        ];

        $signature = $this->createSignature($params);
        $params['signature'] = $signature;

        $url = 'https://www.lightsms.com/external/get/find_on_stop.php?' . http_build_query($params);
        $response = file_get_contents($url);
        $data = json_decode($response, true);

        return !empty($data) ? $data : null;
    }

    /**
     * Add phone number to blacklist
     * @return string Blacklist entry ID
     */
    public function addToBlacklist($phone) {
        $timestamp = $this->getTimestamp();

        $params = [
            'login' => $this->login,
            'phone' => $phone,
            'timestamp' => $timestamp,
            'return' => 'json'
        ];

        $signature = $this->createSignature($params);
        $params['signature'] = $signature;

        $url = 'https://www.lightsms.com/external/get/add2stop.php?' . http_build_query($params);
        $response = file_get_contents($url);
        $data = json_decode($response, true);

        return $data['id'];
    }

    /**
     * Check multiple numbers at once
     * @return array Phone numbers that are blacklisted
     */
    public function filterBlacklisted($phones) {
        $blacklisted = [];

        foreach ($phones as $phone) {
            if ($this->isBlacklisted($phone)) {
                $blacklisted[] = $phone;
            }
            usleep(100000); // 100ms delay between checks
        }

        return $blacklisted;
    }
}

// Usage
$blacklist = new BlacklistManager('YourLogin', 'your_api_key');

// Check if number is blacklisted
$phone = '37061234567';
$info = $blacklist->isBlacklisted($phone);

if ($info) {
    echo "Number {$phone} is blacklisted\n";
    echo "Added on: {$info['time_in']}\n";
    echo "Reason: {$info['description']}\n";
} else {
    echo "Number {$phone} is not blacklisted\n";
}

// Add to blacklist
$newPhone = '37062345678';
$id = $blacklist->addToBlacklist($newPhone);
echo "Added {$newPhone} to blacklist (ID: {$id})\n";

// Filter list of numbers
$phoneList = ['37061234567', '37062345678', '37063456789'];
$blacklistedNumbers = $blacklist->filterBlacklisted($phoneList);
echo "Blacklisted numbers: " . implode(', ', $blacklistedNumbers) . "\n";
?>

---

Python Example

import requests
import hashlib
import time
from urllib.parse import urlencode

class BlacklistManager:
    def __init__(self, login, api_key):
        self.login = login
        self.api_key = api_key

    def _get_timestamp(self):
        response = requests.get('https://www.lightsms.com/external/get/timestamp.php')
        return response.text.strip()

    def _create_signature(self, params):
        sorted_params = sorted(params.items())
        param_string = ''.join([str(value) for key, value in sorted_params])
        return hashlib.md5((param_string + self.api_key).encode()).hexdigest()

    def is_blacklisted(self, phone):
        """Check if phone number is blacklisted"""
        timestamp = self._get_timestamp()

        params = {
            'login': self.login,
            'phone': phone,
            'timestamp': timestamp,
            'return': 'json'
        }

        signature = self._create_signature(params)
        params['signature'] = signature

        url = f'https://www.lightsms.com/external/get/find_on_stop.php?{urlencode(params)}'
        response = requests.get(url)
        data = response.json()

        return data if data else None

    def add_to_blacklist(self, phone):
        """Add phone number to blacklist"""
        timestamp = self._get_timestamp()

        params = {
            'login': self.login,
            'phone': phone,
            'timestamp': timestamp,
            'return': 'json'
        }

        signature = self._create_signature(params)
        params['signature'] = signature

        url = f'https://www.lightsms.com/external/get/add2stop.php?{urlencode(params)}'
        response = requests.get(url)
        data = response.json()

        return data['id']

    def filter_blacklisted(self, phones):
        """Filter out blacklisted numbers from a list"""
        blacklisted = []

        for phone in phones:
            if self.is_blacklisted(phone):
                blacklisted.append(phone)
            time.sleep(0.1)  # Rate limiting

        return blacklisted

# Usage
blacklist = BlacklistManager('YourLogin', 'your_api_key')

# Check single number
phone = '37061234567'
info = blacklist.is_blacklisted(phone)

if info:
    print(f"Number {phone} is blacklisted")
    print(f"Added on: {info['time_in']}")
    print(f"Reason: {info['description']}")
else:
    print(f"Number {phone} is not blacklisted")

# Add to blacklist
new_phone = '37062345678'
entry_id = blacklist.add_to_blacklist(new_phone)
print(f"Added {new_phone} to blacklist (ID: {entry_id})")

# Filter list
phone_list = ['37061234567', '37062345678', '37063456789']
blacklisted_numbers = blacklist.filter_blacklisted(phone_list)
print(f"Blacklisted numbers: {', '.join(blacklisted_numbers)}")

---

JavaScript Example

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

class BlacklistManager {
    constructor(login, apiKey) {
        this.login = login;
        this.apiKey = apiKey;
    }

    async getTimestamp() {
        const response = await axios.get('https://www.lightsms.com/external/get/timestamp.php');
        return response.data.trim();
    }

    createSignature(params) {
        const sortedKeys = Object.keys(params).sort();
        const paramString = sortedKeys.map(key => params[key]).join('');
        return crypto.createHash('md5').update(paramString + this.apiKey).digest('hex');
    }

    async isBlacklisted(phone) {
        const timestamp = await this.getTimestamp();

        const params = {
            login: this.login,
            phone: phone,
            timestamp: timestamp,
            return: 'json'
        };

        const signature = this.createSignature(params);
        params.signature = signature;

        const queryString = new URLSearchParams(params).toString();
        const url = `https://www.lightsms.com/external/get/find_on_stop.php?${queryString}`;

        const response = await axios.get(url);
        return Object.keys(response.data).length > 0 ? response.data : null;
    }

    async addToBlacklist(phone) {
        const timestamp = await this.getTimestamp();

        const params = {
            login: this.login,
            phone: phone,
            timestamp: timestamp,
            return: 'json'
        };

        const signature = this.createSignature(params);
        params.signature = signature;

        const queryString = new URLSearchParams(params).toString();
        const url = `https://www.lightsms.com/external/get/add2stop.php?${queryString}`;

        const response = await axios.get(url);
        return response.data.id;
    }

    async filterBlacklisted(phones) {
        const blacklisted = [];

        for (const phone of phones) {
            const info = await this.isBlacklisted(phone);
            if (info) {
                blacklisted.push(phone);
            }
            await new Promise(resolve => setTimeout(resolve, 100)); // Rate limiting
        }

        return blacklisted;
    }
}

// Usage
(async () => {
    const blacklist = new BlacklistManager('YourLogin', 'your_api_key');

    // Check single number
    const phone = '37061234567';
    const info = await blacklist.isBlacklisted(phone);

    if (info) {
        console.log(`Number ${phone} is blacklisted`);
        console.log(`Added on: ${info.time_in}`);
        console.log(`Reason: ${info.description}`);
    } else {
        console.log(`Number ${phone} is not blacklisted`);
    }

    // Add to blacklist
    const newPhone = '37062345678';
    const entryId = await blacklist.addToBlacklist(newPhone);
    console.log(`Added ${newPhone} to blacklist (ID: ${entryId})`);

    // Filter list
    const phoneList = ['37061234567', '37062345678', '37063456789'];
    const blacklistedNumbers = await blacklist.filterBlacklisted(phoneList);
    console.log(`Blacklisted numbers: ${blacklistedNumbers.join(', ')}`);
})();

---

Common Errors

Error Code 20: Number already exists

Problem: Number is already in the blacklist

Solution: This is not really an error - the number was already blacklisted, so no action needed

Error Code 33: Phone number is not set

Problem: phone parameter is missing or empty

Solution: Include a valid phone number with country code

---

Compliance

Legal Requirements

• Honor opt-out requests within 24-48 hours
• Include opt-out instructions in marketing messages
• Keep blacklist records for compliance audits
• Respect regional regulations (GDPR, TCPA, etc.)

---

Next Steps

• Send SMS safely
• Manage recipient lists
• Check sender names

---

Related Documentation

• Sending SMS
• Error Codes
• FAQ