README

Package: pratiksahu2003/smscountry-php-sdk
Version: 1.0.0
Last updated: 24 June 2026
Author: Pratik Sahu · pratiksahu1535@gmail.com
Repository: github.com/Pratiksahu2003/smscountry-php-sdk
API reference: SMS Country HTTP API Documentation

Framework-agnostic PHP Composer library to send SMS, check balance, fetch delivery reports, and store every attempt in a database log table. Works in plain PHP, Laravel, Symfony, CodeIgniter, WordPress, and any PHP project.

Features
Requirements
Installation
Environment variables
Quick setup (.env)
Database log table
Implementation guides
Sending SMS
Balance & delivery reports
Delivery webhook callback
Message types
Delivery status codes
Troubleshooting
Development & testing
License

Features

Feature	Description
Single SMS	Send to one mobile number
Bulk SMS	Same message to many numbers
Personalized SMS	Different message per number in one API call
Credit balance	Check remaining SMS credits
Delivery reports	Pull reports by date range
Auto country code	Prefix local numbers with `SMS_COUNTRY_DEFAULT_COUNTRY_CODE`
Database logging	Every send logged to `smscountry_logs`
Laravel ready	Auto-discovery, migration, Eloquent model, Facade
Webhook handler	Update delivery status from SMS Country callback

Requirements

Requirement	Version
PHP	8.1 or higher
Guzzle HTTP	7.x (installed via Composer)
Database	MySQL / MariaDB / PostgreSQL (for SMS logs)
PDO extension	Required for plain PHP logging
Laravel	10+ (optional, for Laravel integration)

Installation

composer require pratiksahu2003/smscountry-php-sdk

Environment variables

Use these variables in any PHP project. They are the standard configuration for the SMS Country gateway.

Variable	Required	Example	Description
`SMS_COUNTRY_AUTH_KEY`	Yes	`myaccount`	SMS Country username (API param: `User`)
`SMS_COUNTRY_AUTH_TOKEN`	Yes	`your_secret_password`	SMS Country password (API param: `passwd`)
`SMS_COUNTRY_BASE_URL`	No	`https://api.smscountry.com`	API base URL (endpoints are built from this)
`SMS_COUNTRY_SENDER_ID`	No	`SUGNTA`	Approved sender ID (API param: `sid`)
`SMS_COUNTRY_DEFAULT_COUNTRY_CODE`	No	`91`	Auto-prefix local numbers (India = `91`)
`SMS_COUNTRY_DELIVERY_REPORT`	No	`true`	Request delivery report (`DR=Y`)
`SMS_COUNTRY_ENCODE_MESSAGES`	No	`true`	Encode special HTTP characters in message
`SMS_COUNTRY_LOGGING`	No	`true`	Save every SMS to database log table
`SMS_COUNTRY_LOGS_TABLE`	No	`smscountry_logs`	Custom log table name

Legacy aliases (still supported): SMSCOUNTRY_USERNAME, SMSCOUNTRY_PASSWORD, SMSCOUNTRY_SENDER_ID

How credentials map to the API

SMS_COUNTRY_AUTH_KEY   →  User=xxxxxx
SMS_COUNTRY_AUTH_TOKEN →  passwd=xxxxxx
SMS_COUNTRY_SENDER_ID  →  sid=SUGNTA
SMS_COUNTRY_BASE_URL   →  https://api.smscountry.com/SMSCwebservice_bulk.aspx

Quick setup (.env)

Copy this into your project .env file and replace with your real credentials from SMS Country:

# ── SMS Gateway (SMSCountry) ─────────────────────────────────────
SMS_COUNTRY_AUTH_KEY=your_username
SMS_COUNTRY_AUTH_TOKEN=your_password
SMS_COUNTRY_BASE_URL=https://api.smscountry.com
SMS_COUNTRY_SENDER_ID=SUGNTA
SMS_COUNTRY_DEFAULT_COUNTRY_CODE=91

# Optional
SMS_COUNTRY_DELIVERY_REPORT=true
SMS_COUNTRY_ENCODE_MESSAGES=true
SMS_COUNTRY_LOGGING=true
SMS_COUNTRY_LOGS_TABLE=smscountry_logs

Mobile number examples with SMS_COUNTRY_DEFAULT_COUNTRY_CODE=91:

You send	API receives
`9876543210`	`919876543210`
`09876543210`	`919876543210`
`919876543210`	`919876543210` (unchanged)
`+91 98765 43210`	`919876543210`

Database log table

When logging is enabled, every SMS is stored in smscountry_logs.

Create table — plain SQL

mysql -u root -p your_database < vendor/pratiksahu2003/smscountry-php-sdk/database/schema/smscountry_logs.sql

Or run manually from database/schema/smscountry_logs.sql.

Create table — Laravel

php artisan vendor:publish --tag=smscountry-migrations
php artisan migrate

Log table columns

Column	Type	Description
`id`	BIGINT	Auto-increment primary key
`job_id`	VARCHAR(64)	Message ID from API response `OK:515789649`
`mobile_number`	VARCHAR(255)	Destination number(s) with country code
`message`	TEXT	SMS body sent
`sender_id`	VARCHAR(32)	Sender ID used (`SUGNTA`)
`message_type`	VARCHAR(8)	`N`, `LNG`, `OL`, etc.
`delivery_report`	BOOLEAN	Whether DR was requested
`send_type`	ENUM	`single`, `bulk`, `multiple`
`status`	ENUM	`pending` → `sent` or `failed`
`api_response`	TEXT	Raw API response
`error_message`	TEXT	Error text on failure
`delivery_status`	TINYINT	`0`–`11` delivery code
`delivery_status_label`	VARCHAR(64)	Human-readable delivery status
`delivered_at`	DATETIME	Delivery timestamp
`created_at` / `updated_at`	DATETIME	Timestamps

Implementation guides

1. Plain PHP / Core PHP

Step 1 — Install

composer require pratiksahu2003/smscountry-php-sdk

Step 2 — Set environment variables (Apache/Nginx, .env loader, or server config)

SMS_COUNTRY_AUTH_KEY=your_username
SMS_COUNTRY_AUTH_TOKEN=your_password
SMS_COUNTRY_BASE_URL=https://api.smscountry.com
SMS_COUNTRY_SENDER_ID=SUGNTA
SMS_COUNTRY_DEFAULT_COUNTRY_CODE=91

Step 3 — Create log table

mysql -u root -p myapp < vendor/pratiksahu2003/smscountry-php-sdk/database/schema/smscountry_logs.sql

Step 4 — Send SMS

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use SMSCountry\Config;
use SMSCountry\Database\PdoSmsLogger;
use SMSCountry\MessageType;
use SMSCountry\SMSCountryClient;

// Load .env manually if needed (or use vlucas/phpdotenv)
// putenv('SMS_COUNTRY_AUTH_KEY=...');

$config = Config::fromEnv();
$pdo = new PDO('mysql:host=127.0.0.1;dbname=myapp;charset=utf8mb4', 'root', 'secret');
$logger = new PdoSmsLogger($pdo, 'smscountry_logs');
$client = new SMSCountryClient($config, logger: $logger);

// Local number — country code 91 is added automatically
$result = $client->send('9876543210', 'Hello from SMS Country!', MessageType::Normal);

echo 'Job ID: ' . $result->messageId . PHP_EOL;
echo 'Status: ' . ($result->success ? 'sent' : 'failed') . PHP_EOL;

Step 5 — Check balance

$balance = $client->getBalance();
echo 'Credits: ' . $balance->balance;

2. Laravel

Step 1 — Install

composer require pratiksahu2003/smscountry-php-sdk

Step 2 — Add to .env

SMS_COUNTRY_AUTH_KEY=your_username
SMS_COUNTRY_AUTH_TOKEN=your_password
SMS_COUNTRY_BASE_URL=https://api.smscountry.com
SMS_COUNTRY_SENDER_ID=SUGNTA
SMS_COUNTRY_DEFAULT_COUNTRY_CODE=91
SMS_COUNTRY_LOGGING=true

Step 3 — Publish config & migration

php artisan vendor:publish --tag=smscountry-config
php artisan vendor:publish --tag=smscountry-migrations
php artisan migrate

Step 4 — Send via Facade

use SMSCountry\Laravel\Facades\SMSCountry;
use SMSCountry\MessageType;

SMSCountry::send('9876543210', 'Your OTP is 482910', MessageType::Normal);

Step 5 — Inject in a Service / Controller

use SMSCountry\Contracts\SMSCountryClientInterface;
use SMSCountry\MessageType;

class OtpController extends Controller
{
    public function __construct(private SMSCountryClientInterface $sms) {}

    public function sendOtp(Request $request)
    {
        $result = $this->sms->send(
            mobileNumber: $request->phone,   // e.g. 9876543210
            message: 'Your OTP is 482910. Valid for 5 minutes.',
            type: MessageType::Normal,
        );

        return response()->json([
            'job_id' => $result->messageId,
            'status' => 'sent',
        ]);
    }
}

Step 6 — View SMS logs

use SMSCountry\Laravel\Models\SmsLog;

$logs = SmsLog::query()
    ->where('status', 'sent')
    ->latest()
    ->paginate(20);

3. CodeIgniter 4

.env

SMS_COUNTRY_AUTH_KEY=your_username
SMS_COUNTRY_AUTH_TOKEN=your_password
SMS_COUNTRY_BASE_URL=https://api.smscountry.com
SMS_COUNTRY_SENDER_ID=SUGNTA
SMS_COUNTRY_DEFAULT_COUNTRY_CODE=91

app/Config/Services.php

use SMSCountry\Config;
use SMSCountry\SMSCountryClient;

public static function smsCountry(bool $getShared = true)
{
    if ($getShared) {
        return static::getSharedInstance('smsCountry');
    }

    return new SMSCountryClient(Config::fromEnv([
        'SMS_COUNTRY_AUTH_KEY' => env('SMS_COUNTRY_AUTH_KEY'),
        'SMS_COUNTRY_AUTH_TOKEN' => env('SMS_COUNTRY_AUTH_TOKEN'),
        'SMS_COUNTRY_BASE_URL' => env('SMS_COUNTRY_BASE_URL'),
        'SMS_COUNTRY_SENDER_ID' => env('SMS_COUNTRY_SENDER_ID'),
        'SMS_COUNTRY_DEFAULT_COUNTRY_CODE' => env('SMS_COUNTRY_DEFAULT_COUNTRY_CODE'),
    ]));
}

Controller

$sms = service('smsCountry');
$sms->send('9876543210', 'Hello from CodeIgniter!');

4. Symfony

.env

SMS_COUNTRY_AUTH_KEY=your_username
SMS_COUNTRY_AUTH_TOKEN=your_password
SMS_COUNTRY_BASE_URL=https://api.smscountry.com
SMS_COUNTRY_SENDER_ID=SUGNTA
SMS_COUNTRY_DEFAULT_COUNTRY_CODE=91

config/services.yaml

services:
    SMSCountry\Config:
        factory: ['SMSCountry\Config', 'fromEnv']

    SMSCountry\Contracts\SMSCountryClientInterface:
        class: SMSCountry\SMSCountryClient
        arguments:
            $config: '@SMSCountry\Config'

Usage in a service

public function __construct(
    private SMSCountryClientInterface $sms,
) {}

public function notify(string $phone, string $message): void
{
    $this->sms->send($phone, $message);
}

5. WordPress / WooCommerce

wp-config.php or plugin .env

define('SMS_COUNTRY_AUTH_KEY', 'your_username');
define('SMS_COUNTRY_AUTH_TOKEN', 'your_password');
define('SMS_COUNTRY_BASE_URL', 'https://api.smscountry.com');
define('SMS_COUNTRY_SENDER_ID', 'SUGNTA');
define('SMS_COUNTRY_DEFAULT_COUNTRY_CODE', '91');

Plugin snippet

require_once WP_PLUGIN_DIR . '/your-plugin/vendor/autoload.php';

use SMSCountry\Config;
use SMSCountry\SMSCountryClient;

$config = Config::fromEnv([
    'SMS_COUNTRY_AUTH_KEY' => SMS_COUNTRY_AUTH_KEY,
    'SMS_COUNTRY_AUTH_TOKEN' => SMS_COUNTRY_AUTH_TOKEN,
    'SMS_COUNTRY_BASE_URL' => SMS_COUNTRY_BASE_URL,
    'SMS_COUNTRY_SENDER_ID' => SMS_COUNTRY_SENDER_ID,
    'SMS_COUNTRY_DEFAULT_COUNTRY_CODE' => SMS_COUNTRY_DEFAULT_COUNTRY_CODE,
]);

$client = new SMSCountryClient($config);
$client->send('9876543210', 'Order confirmed!');

Sending SMS

Single SMS

$result = $client->send('9876543210', 'Hello!');
// $result->messageId  →  "515789649"
// $result->success    →  true
// $result->rawResponse → "OK:515789649"

Bulk SMS (same message, many numbers)

$client->sendBulk(
    ['9876543210', '9123456789', '9988776655'],
    'Flash sale starts now!',
);

Personalized SMS (different message per number)

$client->sendMultiple([
    '9876543210' => 'Hi Rahul, your order is ready.',
    '9123456789' => 'Hi Priya, your order is ready.',
]);

With custom sender ID per call

$client->send('9876543210', 'Hello!', senderId: 'SUGNTA');

Balance & delivery reports

Check SMS credit balance

$balance = $client->getBalance();

if ($balance->success) {
    echo 'Remaining credits: ' . $balance->balance;
} else {
    echo 'Error: ' . $balance->rawResponse;
}

API endpoint: {BASE_URL}/SMSCwebservice_User_GetBal.asp

Fetch delivery reports (auto-updates log table)

$from = new DateTime('2026-06-01 00:00:00');
$to   = new DateTime('2026-06-24 23:59:59');

$reports = $client->getDeliveryReports($from, $to);

foreach ($reports as $report) {
    echo sprintf(
        "Job %s → %s (%s)\n",
        $report->jobId,
        $report->status?->label() ?? 'Unknown',
        $report->mobileNumber,
    );
}

API endpoint: {BASE_URL}/smscwebservices_bulk_reports.aspx

Delivery webhook callback

Plain PHP

use SMSCountry\Support\DeliveryWebhookHandler;

$handler = new DeliveryWebhookHandler($logger);
$handler->handle($_GET);
// Params: jobno, mobilenumber, status, doneTime, messagepart

Laravel route

use Illuminate\Http\Request;
use SMSCountry\Support\DeliveryWebhookHandler;

Route::get('/sms/delivery-callback', function (Request $request) {
    app(DeliveryWebhookHandler::class)->handle($request->query());
    return response('OK', 200);
});

Message types

Per official API documentation:

PHP Enum	API `mtype`	Use case
`MessageType::Normal`	`N`	Standard text SMS (max 160 chars)
`MessageType::Unicode`	`LNG`	Unicode — Arabic, Hindi, Chinese, etc. (max 70 chars)
`MessageType::Hexadecimal`	`OL`	Hex-encoded Unicode content
`MessageType::Ringtone`	`R`	Ringtone messages
`MessageType::Picture`	`P`	Picture messages
`MessageType::Logo`	`L`	Logo messages
`MessageType::Flash`	`F`	Flash SMS
`MessageType::WapPush`	`WP`	WAP push
`MessageType::LongSms`	`LS`	Long SMS (multi-part)

use SMSCountry\MessageType;

$client->send('9876543210', 'नमस्ते', MessageType::Unicode);
$client->send('9876543210', 'Your OTP: 482910', MessageType::Normal);

Delivery status codes

Code	Status	Meaning
`0`	Queued	Message in queue
`1`	SubmittedToCarrier	Submitted to carrier
`2`	Undelivered	Not delivered
`3`	Delivered	Successfully delivered
`4`	Expired	Message expired
`8`	Rejected	Rejected by gateway
`9`	Sent	Message sent
`10`	OptedOut	Number opted out
`11`	InvalidMobile	Invalid mobile number

Use in PHP:

use SMSCountry\DeliveryStatus;

$status = DeliveryStatus::Delivered;
echo $status->label(); // "Delivered"

Troubleshooting

Error / Issue	Cause	Fix
`Invalid User Name!!`	Wrong `SMS_COUNTRY_AUTH_KEY`	Verify username in SMS Country account
`Invalid Password!!`	Wrong `SMS_COUNTRY_AUTH_TOKEN`	Reset password in account panel
`Insufficient Balance!!!`	No SMS credits	Top up at smscountry.com
`Invalid mobile number(s)`	Missing country code	Set `SMS_COUNTRY_DEFAULT_COUNTRY_CODE=91`
SMS not delivered	Unapproved sender ID	Use approved ID or set `SMS_COUNTRY_SENDER_ID=SUGNTA`
Special chars broken	Encoding issue	Keep `SMS_COUNTRY_ENCODE_MESSAGES=true`
No log in database	Logging disabled	Set `SMS_COUNTRY_LOGGING=true` and run migration

Common API response formats

OK:515789649          → Success (job ID = 515789649)
Invalid Password!!    → Auth failure
Insufficient Balance  → Top up required

Development & testing

git clone https://github.com/Pratiksahu2003/smscountry-php-sdk.git
cd smscountry-php-sdk
composer install
composer test

Package info

Item	Value
Author	Pratik Sahu · pratiksahu1535@gmail.com
Repository	Pratiksahu2003/smscountry-php-sdk
Package	`pratiksahu2003/smscountry-php-sdk`
Namespace	`SMSCountry\`
Version	`1.0.0`
PHP	`^8.1`
License	MIT

License

MIT — see LICENSE.

Author & support: Pratik Sahu · pratiksahu1535@gmail.com · Report an issue

SMS Country API: Developers · API Documentation

pratiksahu2003/smscountry-php-sdk

包简介

关键字：

README 文档