📡 API Documentation

TellbySMS Communications provides a simple REST API that lets you send SMS, manage contacts and query your account from any programming language.

https://sms.scopehost.net/api/v1/
Authentication

Every request must include your API token. Get your token by creating a free account and visiting the API Access page.

Send your token using the Authorization header (recommended):

HTTP Header
Authorization: Bearer YOUR_API_TOKEN

Or as a query string parameter:

Query String
https://sms.scopehost.net/api/v1/?endpoint=balance&api_token=YOUR_API_TOKEN
Response Format

All responses are JSON. Every response includes a status field.

Success
{"status": "success", "message": "...", "data": [...]}
Error
{"status": "error", "message": "Reason for failure"}
Error Codes
HTTPstatusMeaning
200successRequest completed successfully
400errorMissing or invalid parameters
401errorInvalid or missing API token
402errorInsufficient credits
404errorUnknown endpoint
405errorWrong HTTP method
Login
POST https://sms.scopehost.net/api/v1/?endpoint=login Authenticate and retrieve your API token
Parameters
ParameterRequiredTypeDescription
email Required string Your account email address
password Required string Your account password
PHP Example
$result = api('login', 'POST', [
    'email'    => '[email protected]',
    'password' => 'yourpassword',
]);
$token = $result['api_token'];
Response
{"status":"success","api_token":"3b03e0a3...","user":{"id":1,"name":"John Dlamini","email":"[email protected]"}}
Balance
GET https://sms.scopehost.net/api/v1/?endpoint=balance Get your current credit balance
PHP Example
$balance = api('balance');
echo "Balance: " . $balance['currency'] . $balance['balance'];
Response
{"status":"success","balance":231.98,"currency":"E"}
Stats
GET https://sms.scopehost.net/api/v1/?endpoint=stats Get account statistics and 7-day SMS activity chart
PHP Example
$stats = api('stats');
echo "Sent: " . $stats['stats']['sent'];
echo "Balance: E" . $stats['balance'];
Response
{"status":"success","balance":231.98,"stats":{"sent":1420,"failed":3,"scheduled":2,"contacts":98},"chart":[{"date":"19 Apr","count":42},{"date":"20 Apr","count":87}]}
Send SMS
Credits are deducted from your balance per SMS sent. Check your balance before sending bulk messages.
POST https://sms.scopehost.net/api/v1/?endpoint=send Send a single, bulk or group SMS
Parameters
ParameterRequiredTypeDescription
to Required string Phone number(s) comma-separated, or group:{id} to send to an entire group
message Required string SMS text (max 612 chars). Supports {name} {mobile} personalisation
sender_id Optional string Approved Sender ID (e.g. MyBrand). Leave blank for default
scheduled_at Optional datetime Schedule delivery: YYYY-MM-DD HH:MM
PHP Example
$result = api('send', 'POST', [
    'to'      => '26876123456,26878654321',
    'message' => 'Hi {name}, your order is ready!',
]);
// Send to entire group
$result = api('send', 'POST', [
    'to'      => 'group:3',
    'message' => 'Special offer for VIP members!',
]);
Response
{"status":"success","message":"SMS sent to 3 recipient(s)","msg_id":42}
Message Reports
GET https://sms.scopehost.net/api/v1/?endpoint=messages List your sent message history
Parameters
ParameterRequiredTypeDescription
page Optional int Page number (default: 1)
limit Optional int Results per page (default: 20, max: 100)
status Optional string Filter: sent failed queued all
PHP Example
$messages = api('messages', 'GET', ['page' => 1, 'status' => 'sent']);
foreach ($messages['data'] as $msg) {
    echo $msg['id'] . " → " . $msg['status'];
}
Response
{"status":"success","total":142,"data":[{"id":42,"recipients":"26876123456","message":"Hello!","status":"sent","credits_used":0.40,"sent_at":"2026-04-25 10:30:00"}]}
Contacts
GET https://sms.scopehost.net/api/v1/?endpoint=contacts List your contacts
Parameters
ParameterRequiredTypeDescription
group_id Optional int Filter contacts by group ID
PHP Example
$contacts = api('contacts', 'GET', ['group_id' => 2]);
foreach ($contacts['data'] as $c) {
    echo $c['name'] . " — " . $c['mobile'];
}
Response
{"status":"success","data":[{"id":1,"name":"Jane Dlamini","mobile":"26876123456","group_id":2}]}
POST https://sms.scopehost.net/api/v1/?endpoint=contacts Add a new contact
Parameters
ParameterRequiredTypeDescription
mobile Required string Phone number (e.g. 26876123456)
name Optional string Contact name
group_id Optional int Assign to a group
PHP Example
$result = api('contacts', 'POST', [
    'mobile'   => '26876123456',
    'name'     => 'Jane Dlamini',
    'group_id' => 2,
]);
Response
{"status":"success","message":"Contact added","id":15}
DELETE https://sms.scopehost.net/api/v1/?endpoint=contacts Delete a contact
Parameters
ParameterRequiredTypeDescription
id Required int Contact ID to delete
PHP Example
$result = api('contacts', 'DELETE', ['id' => 15]);
Response
{"status":"success","message":"Contact deleted"}
Groups
GET https://sms.scopehost.net/api/v1/?endpoint=groups List your contact groups
PHP Example
$groups = api('groups');
foreach ($groups['data'] as $g) {
    echo $g['name'] . " (" . $g['contact_count'] . " contacts)";
}
Response
{"status":"success","data":[{"id":2,"name":"VIP Customers","contact_count":45}]}
POST https://sms.scopehost.net/api/v1/?endpoint=groups Create a new group
Parameters
ParameterRequiredTypeDescription
name Required string Group name
description Optional string Group description
PHP Example
$result = api('groups', 'POST', [
    'name'        => 'VIP Customers',
    'description' => 'Top tier clients',
]);
Response
{"status":"success","message":"Group created","id":3}
Sender IDs
GET https://sms.scopehost.net/api/v1/?endpoint=sender_ids List your approved Sender IDs
PHP Example
$senderIds = api('sender_ids');
foreach ($senderIds['data'] as $s) {
    echo $s['sender_id'] . " — " . $s['status'];
}
Response
{"status":"success","data":[{"id":1,"sender_id":"MyBrand","status":"approved"}]}
POST https://sms.scopehost.net/api/v1/?endpoint=sender_ids Apply for a new Sender ID
Parameters
ParameterRequiredTypeDescription
sender_id Required string Desired Sender ID (max 11 chars, no spaces)
description Optional string Business reason for this Sender ID
PHP Example
$result = api('sender_ids', 'POST', [
    'sender_id'   => 'MyBrand',
    'description' => 'Customer notifications for MyBrand eCommerce',
]);
Response
{"status":"success","message":"Application submitted. Pending review."}
Profile
GET https://sms.scopehost.net/api/v1/?endpoint=profile Get your account profile
PHP Example
$profile = api('profile');
echo $profile['data']['name'] . " — E" . $profile['data']['credits'];
Response
{"status":"success","data":{"name":"John Dlamini","email":"[email protected]","phone":"26876123456","credits":231.98}}
POST https://sms.scopehost.net/api/v1/?endpoint=profile Update your profile
Parameters
ParameterRequiredTypeDescription
name Optional string Your display name
phone Optional string Your phone number
PHP Example
$result = api('profile', 'POST', [
    'name'  => 'John Dlamini',
    'phone' => '26876123456',
]);
Response
{"status":"success","message":"Profile updated"}
Transactions
GET https://sms.scopehost.net/api/v1/?endpoint=transactions List your credit transaction history
Parameters
ParameterRequiredTypeDescription
page Optional int Page number (default: 1)
PHP Example
$txns = api('transactions', 'GET', ['page' => 1]);
foreach ($txns['data'] as $t) {
    $sign = $t['type'] === 'credit' ? '+' : '-';
    echo $sign . "E" . $t['amount'] . " — " . $t['description'];
}
Response
{"status":"success","data":[{"id":10,"type":"credit","amount":50.00,"description":"Top up via MoMo","created_at":"2026-04-20 14:00:00"}]}
PHP Helper Function

Use this reusable function to call any API endpoint. Download the full examples file for 17 pre-built examples.

// Include this in your project
function api(string $endpoint, string $method = 'GET', array $data = []): array
{
    $url = 'https://sms.scopehost.net/api/v1/?endpoint=' . $endpoint;
    if ($method === 'GET' && !empty($data)) {
        $url .= '&' . http_build_query($data);
    }
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_HTTPHEADER     => ['Authorization: Bearer YOUR_API_TOKEN'],
    ]);
    if ($method === 'POST') {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
    }
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true) ?? [];
}
Get Started Free Download PHP Examples