Introduction

Welcome to the LightningMSG SMS API. This documentation will help you integrate our SMS sending services into your applications quickly and easily.

BASE URL https://www.lightningmsg.com/api/v1/sms_services/sms/

About the API



  • SMS sending service

  • REST API architecture

  • JSON request/response format

  • API key based authentication

Features



  • Single SMS sending

  • Bulk SMS sending

  • Scheduled SMS

  • SMS status inquiry

  • Listing sent SMS messages

  • Querying packages and balance

  • Webhook support

Authentication

To access the API, you must include your API key in the headers of every request.

API keys can be generated on your dashboard. Multiple API keys are supported, and they can be deleted or rotated as needed.

Header format


X-Api-Key: YOUR_API_KEY

curl -X POST https://www.lightningmsg.com/api/v1/sms_services/sms/get_packages \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded"

Quick Start

Send your first SMS in just a few lines of code.

POST send

Parameters

Parameter Type Required Description
secret_code string Yes

Your API secret code.
mobile string Yes

The recipient's mobile number in international format (e.g., +40123456789).
message string Yes

The content of the SMS.

Headers

X-Api-Key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded

Request Body

{
  "secret_code": "89gysdgsldn232",
  "mobile": "+40123456789",
  "message": "This is a test message"
}

Response

{
  "status": "success",
  "message": "",
  "sms_data": {
    "mobile": "+40123456789",
    "sms_id": "ldshgshgenwngknsngdskgnskngks",
    "status": "queued"
  },
  "total_sms": "100",
  "used_sms": "1",
  "is_own_mobile": "0"
}

Send a Single SMS

Sends a single text message to a specified mobile number. Supports scheduling via the `send_date` parameter.

POST send

Parameters

Parameter Type Required Description
secret_code string Yes

Your API secret code.
mobile string Yes

The recipient's mobile number in international format (e.g., +40123456789).
message string Yes

The content of the SMS.
send_date string No

Optional date and time to schedule the SMS (Format: YYYY-MM-DD HH:MM:SS).

Headers

X-Api-Key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded

Example Request Body

{
  "secret_code": "89gysdgsldn232",
  "mobile": "+40123456789",
  "message": "This is a test message",
  "send_date": "2030-06-10 18:30:00"
}

Example Response

{
  "status": "success",
  "message": "",
  "sms_data": {
    "mobile": "+40123456789",
    "sms_id": "ldshgshgenwngknsngdskgnskngks",
    "status": "queued"
  },
  "total_sms": "100",
  "used_sms": "1",
  "is_own_mobile": "0"
}

Send Multiple SMS

Send bulk SMS messages efficiently. Accepts an array of message objects.

POST send_multiple

Parameters

Parameter Type Required Description
secret_code string Yes

Your API secret code.
messages array Yes

Array of message objects (mobile, message, optional send_date).

Headers

X-Api-Key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded

Example Request Body

{
  "secret_code": "89gysdgsldn232",
  "messages": [
    {
      "mobile": "+40123456789",
      "message": "This is a test message",
      "send_date": "2026-06-10 18:30:00"
    },
    {
      "mobile": "+40123456789",
      "message": "This is another test message",
      "send_date": "2030-06-10 18:30:00"
    }
  ]
}

Example Response

{
  "status": "success",
  "message": "",
  "messages": [
    {
      "mobile": "+40123456789",
      "sms_id": "ldshgshgenwngknsngdskgnskngks",
      "status": "queued"
    }
  ]
}

Get SMS Status

Retrieve the current delivery status of a specific SMS using its ID. Possible statuses: `pending`, `sent`, `cancelled`.

POST get_status/{id}

Parameters

Parameter Type Required Description
secret_code string Yes

Your API secret code.

Headers

X-Api-Key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded

Example Request Body

{
  "secret_code": "89gysdgsldn232"
}

Example Response

{
  "status": "success",
  "message": "",
  "sms_data": {
    "id": "ldshgshgenwngknsngdskgnskngks",
    "message": "Test message",
    "mobile": "+40123456789",
    "status": "sent",
    "is_sent": "1"
  }
}

List Sent Messages

Fetch a paginated list of your sent SMS messages.

POST get_sent_messages

Parameters

Parameter Type Required Description
secret_code string Yes

Your API secret code.
limit_from integer No

Start index to get items from. Default: 0.
limit integer No

How many items to retrieve. Max: 100.

Headers

X-Api-Key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded

Example Request Body

{
  "secret_code": "89gysdgsldn232",
  "limit_from": 0,
  "limit": 100
}

Example Response

{
  "status": "success",
  "message": "",
  "messages": [
    {
      "id": "ldshgshgenwngknsngdskgnskngks",
      "message": "Test message",
      "mobile": "+40123456789",
      "status": "sent",
      "is_sent": "1"
    }
  ],
  "nr_messages": 20
}

Cancel Scheduled SMS

Cancel a previously scheduled SMS. Only messages that have not yet been sent can be cancelled.

POST cancel/{id}

Parameters

Parameter Type Required Description
secret_code string Yes

Your API secret code.

Headers

X-Api-Key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded

Example Request Body

{
  "secret_code": "89gysdgsldn232"
}

Example Response

{
  "status": "success",
  "message": ""
}

Get Active Packages

Query your purchased active SMS packages and current balance.

POST get_packages

Parameters

Parameter Type Required Description
secret_code string Yes

Your API secret code.

Headers

X-Api-Key: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded

Example Request Body

{
  "secret_code": "89gysdgsldn232"
}

Example Response

{
  "status": "success",
  "message": "",
  "packages": [
    {
      "name": "100 SMS",
      "total_sms": "100",
      "used_sms": "0",
      "expire_date": "2026-12-01 18:59:23",
      "is_own_mobile": "1"
    }
  ]
}

Webhooks

The LightningMSG system can notify your application when the status of an SMS changes by sending an HTTP POST request to your webhook URL.

Setting up a Webhook


You can configure your webhook URL in the dashboard. Our system will attempt to notify this URL upon status changes.

Events



  • sms.sent: Triggered when an SMS is successfully sent.

  • sms.cancelled: Triggered when a scheduled SMS is cancelled.

Webhook Security

Clients can set custom header parameters in the dashboard. This allows you to define your own secret keys or tokens, making it easy to verify that incoming webhook requests are genuinely originating from our system.

Retry Policy

If your server fails to respond with a HTTP 200 status code, our system implements a retry mechanism to ensure delivery:


  • The system attempts to send the webhook up to 4 times.

  • There is a 5-second wait between each attempt.

  • A webhook is considered successful only when it receives an HTTP 200 OK response.

Webhook Payload Example

{
  "sms_id": "sms_123",
  "status": "sent",
  "timestamp": "2026-05-13T12:33:11Z"
}

Error Codes

When an error occurs, the API will return a JSON object with a specific status code and message.

Code Name Description
0001 WRONG_PARAMETERS Wrong or missing parameters in the request.
0050 WRONG_MODULE Incorrect module specified.
0100 ITEM_NOT_FOUND The requested item could not be found.
0200 ITEM_VALIDATION Validation failed for the provided item.
0300 DEVICE_NOT_FOUND The specified device was not found.
4001 WRONG_SECRET_CODE The provided secret code is invalid.
4002 INCORRECT_CODE Incorrect code provided.
4003 INVALID_API_KEY The provided API key is invalid or unauthorized.
4004 NO_VALID_PACKAGES No valid packages available for this account.
4005 NO_VALID_PACKAGE No valid package available for this request.
4007 INVALID_NUMBER The mobile number format is invalid.
4008 MESSAGE_TOO_LONG The SMS message exceeds the maximum allowed length.
4009 INVALID_SCHEDULE_DATE The provided schedule date is invalid or in the past.

Error Response Example

{
  "status": "0001",
  "message": "Wrong parameters, please check your settings"
}

HTTP Status Codes

200
Success - Request completed successfully.
400
Bad Request - Invalid syntax or missing parameters.
401
Unauthorized - Authentication failed or missing API key.
402
Payment Required - No active package or credits available.
403
Forbidden - No access to the requested resource.
404
Not Found - The requested endpoint or item does not exist.
429
Too Many Requests - Rate limit exceeded.
500
Internal Server Error - Something went wrong on our end.

Rate Limits

To ensure stability and fairness, the API enforces rate limits on incoming requests. Details regarding request limits, bulk SMS throttling, and specific `X-RateLimit` headers will be provided upon integration.

PHP SDK

Currently, we provide a PHP SDK to easily integrate the service. Here are examples of how to use it:

Send SMS using PHP SDK

<?php
include_once PLUGINPATH . "SakerSMS/SakerSMS.php";

$sms_sender = new \SakerSMS\SakerSMS();
$result = $sms_sender->Send("0712345678", "Test message");

if (!$result) {
    echo $sms_sender->GetErrorMessage();
} else {
    echo "totalSMS = " . $sms_sender->getTotalSMS() . ", usedSMS = " . $sms_sender->getUsedSMS();
}
?>

Get Packages using PHP SDK

<?php
include_once PLUGINPATH . "SakerSMS/SakerSMS.php";

$sms_sender = new \SakerSMS\SakerSMS();
$packages = $sms_sender->GetPackages();

print_r($packages);
?>

Test Credits

New accounts receive free test SMS credits to properly test the integration.

*Why?* The full functionality of the SMS service, including delivery reports, can only be properly tested on a live cellular network.