Managing Recipient Lists

Organize recipients into lists (also called "bases") for efficient bulk SMS campaigns.

Overview

Recipient lists allow you to:

📋 Group recipients by category (customers, partners, leads)
🚀 Send bulk SMS to entire groups at once
📊 Track list statistics (size, pages, settings)
🎂 Automate birthday messages (optional)

Get All Lists

Retrieve all recipient lists in your account.

Endpoint:

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

Required Parameters:

Parameter	Type	Description
`login`	string	Your LightSMS login
`signature`	string	MD5 hash signature
`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/base.php?login=YourLogin&signature=generated_signature&timestamp=1732809600&return=json"

Response (JSON)

{
    "125448": {
        "name": "All qualified leads",
        "time_birth": "12:00:00",
        "day_before": "0",
        "local_time": "1",
        "birth_sender": "",
        "birth_text": "",
        "on_birth": "0",
        "count": "3618",
        "pages": "37"
    },
    "125452": {
        "name": "Valuable clients",
        "time_birth": "12:00:00",
        "day_before": "0",
        "local_time": "1",
        "birth_sender": "",
        "birth_text": "",
        "on_birth": "0",
        "count": "2255",
        "pages": "23"
    }
}

Response (XML)

<?xml version="1.0" encoding="utf-8"?>
<response>
    <bases>
        <base base="125448" name="All qualified leads" time_birth="12:00:00"
              day_before="0" local_time="1" birth_sender="" birth_text=""
              on_birth="0" count="3618" pages="37" />
        <base base="125452" name="Valuable clients" time_birth="12:00:00"
              day_before="0" local_time="1" birth_sender="" birth_text=""
              on_birth="0" count="2255" pages="23" />
    </bases>
</response>

Response Fields

Field	Type	Description
`base` (key)	string	Unique list ID
`name`	string	List name
`count`	string	Total number of recipients
`pages`	string	Number of pages (100 recipients per page)
`time_birth`	string	Birthday message sending time (HH:MM:SS)
`day_before`	string	Days before birthday to send (0 = on birthday)
`local_time`	string	Use local time (1) or UTC (0)
`birth_sender`	string	Sender name for birthday messages
`birth_text`	string	Birthday message template
`on_birth`	string	Birthday messages enabled (1) or disabled (0)

Get Recipients from List

Retrieve phone numbers from a specific list.

Endpoint:

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

Required Parameters:

Parameter	Type	Description
`login`	string	Your LightSMS login
`signature`	string	MD5 hash signature
`base`	string	List ID
`page`	integer	Page number (starting from 1)
`timestamp`	integer	UTC timestamp

Optional Parameters:

Parameter	Type	Description
`return`	string	Response format: `json` or `xml`

Pagination

Each page contains up to 100 recipients. Use the pages field from list info to know total pages.

Example Request

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

Response (JSON)

{
    "37061234567": {
        "name": "John",
        "last_name": "Doe",
        "middle_name": "Michael",
        "date_birth": "1990-05-15",
        "male": "1",
        "note1": "Premium customer",
        "note2": "Prefers email",
        "region": "Vilnius",
        "operator": "Telia"
    },
    "37062345678": {
        "name": "Jane",
        "last_name": "Smith",
        "middle_name": "",
        "date_birth": "1985-12-20",
        "male": "0",
        "note1": "",
        "note2": "",
        "region": "Kaunas",
        "operator": "Tele2"
    }
}

Response (XML)

<?xml version="1.0" encoding="utf-8"?>
<response>
    <phones>
        <phone phone="37061234567" name="John" last_name="Doe" middle_name="Michael"
               date_birth="1990-05-15" male="1" note1="Premium customer"
               note2="Prefers email" region="Vilnius" operator="Telia" />
        <phone phone="37062345678" name="Jane" last_name="Smith" middle_name=""
               date_birth="1985-12-20" male="0" note1="" note2=""
               region="Kaunas" operator="Tele2" />
    </phones>
</response>

Recipient Fields

Field	Type	Description
`phone` (key)	string	Phone number with country code
`name`	string	First name
`last_name`	string	Last name
`middle_name`	string	Middle name
`date_birth`	string	Date of birth (YYYY-MM-DD)
`male`	string	Gender: 1 (male), 0 (female)
`note1`	string	Custom field 1
`note2`	string	Custom field 2
`region`	string	Region/city
`operator`	string	Mobile operator

PHP Example

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

    // Prepare parameters
    $params = [
        'login' => $login,
        'base' => $listId,
        'page' => (string)$page,
        '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/phone.php?' . http_build_query($params);
    $response = file_get_contents($url);

    return json_decode($response, true);
}

// Get all lists
function getAllLists($login, $apiKey) {
    $timestamp = trim(file_get_contents('https://www.lightsms.com/external/get/timestamp.php'));

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

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

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

    return json_decode($response, true);
}

// Usage
$lists = getAllLists('YourLogin', 'your_api_key');

foreach ($lists as $listId => $listInfo) {
    echo "List: {$listInfo['name']} (ID: {$listId})\n";
    echo "Recipients: {$listInfo['count']}\n";

    // Get first page of recipients
    $recipients = getListRecipients('YourLogin', 'your_api_key', $listId, 1);

    foreach ($recipients as $phone => $data) {
        echo "  - {$data['name']} {$data['last_name']}: {$phone}\n";
    }
    echo "\n";
}
?>

Python Example

import requests
import hashlib
from urllib.parse import urlencode

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

    # Prepare parameters
    params = {
        'login': login,
        '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/base.php?{urlencode(params)}'
    response = requests.get(url)

    return response.json()

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

    # Prepare parameters
    params = {
        'login': login,
        'base': list_id,
        'page': str(page),
        '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/phone.php?{urlencode(params)}'
    response = requests.get(url)

    return response.json()

# Usage
lists = get_all_lists('YourLogin', 'your_api_key')

for list_id, list_info in lists.items():
    print(f"List: {list_info['name']} (ID: {list_id})")
    print(f"Recipients: {list_info['count']}")

    # Get first page
    recipients = get_list_recipients('YourLogin', 'your_api_key', list_id, 1)

    for phone, data in recipients.items():
        print(f"  - {data['name']} {data['last_name']}: {phone}")
    print()

Sending SMS to a List

To send SMS to an entire list through the web interface:

Go to the message creation window
Select the desired list from Base selection dropdown
Optionally add additional phone numbers
Optionally select exemption groups (recipients who won't receive the message)

API Sending

To send SMS to a list via API, retrieve all recipients using the endpoints above, then send SMS to those phone numbers using the send endpoint.

Birthday Messages

Lists support automatic birthday message sending when enabled (on_birth = 1).

Configuration fields:

time_birth: Time to send (e.g., "12:00:00")
day_before: Days before birthday (0 = on birthday, 1 = day before)
local_time: Use recipient's local time (1) or UTC (0)
birth_sender: Sender name for birthday messages
birth_text: Message template

Manage via Web

Birthday message settings are typically configured through the LightSMS web interface, not the API.

Common Errors

Error Code 15: List not specified

Problem: base parameter is missing

Solution: Include the base parameter with a valid list ID

Error Code 25: Error in access to the list

Problem: You don't have permission to access this list

Solutions:

Check if list ID is correct
Ensure the list belongs to your account
Contact support if you should have access

Error Code 26: No numbers in the list

Problem: The list is empty

Solution: Add recipients to the list first through the web interface

Overview​

Get All Lists​

Example Request (JSON)​

Response (JSON)​

Response (XML)​

Response Fields​

Get Recipients from List​

Example Request​

Response (JSON)​

Response (XML)​

Recipient Fields​

PHP Example​

Python Example​

Sending SMS to a List​

Birthday Messages​

Common Errors​

Error Code 15: List not specified​

Error Code 25: Error in access to the list​

Error Code 26: No numbers in the list​

Next Steps​

Related Documentation​

Overview

Get All Lists

Example Request (JSON)

Response (JSON)

Response (XML)

Response Fields

Get Recipients from List

Example Request

Response (JSON)

Response (XML)

Recipient Fields

PHP Example

Python Example

Sending SMS to a List

Birthday Messages

Common Errors

Error Code 15: List not specified

Error Code 25: Error in access to the list

Error Code 26: No numbers in the list

Next Steps

Related Documentation