README

Official PHP client for the Tuseme SMS API.

Installation

composer require tuseme/sdk

Quick Start

<?php
require 'vendor/autoload.php';

use Tuseme\TusemeClient;

$client = new TusemeClient([
    'api_key'    => 'tk_test_your_api_key',
    'api_secret' => 'sk_test_your_api_secret',
]);

$response = $client->messages->send([
    'content'    => 'Hello from Tuseme! Your OTP is 482910.',
    'sender_id'  => 'TUSEME-LTD',
    'recipients' => [
        ['msisdn' => '+254712345678', 'name' => 'John Doe']
    ],
    'type'     => 'transactional',
    'priority' => 'HIGH',
]);

echo "Message ID: " . $response['message_id'] . "\n";
echo "Status: " . $response['status'] . "\n";

Features

• Zero dependencies — uses built-in cURL
• Automatic authentication — tokens obtained and refreshed transparently
• Built-in retries — exponential backoff for transient failures
• PHP 8.0+ with strict types

Authentication

// Sandbox credentials (for testing)
$client = new TusemeClient(['api_key' => 'tk_test_...', 'api_secret' => 'sk_test_...']);

// Production credentials
$client = new TusemeClient(['api_key' => 'tk_live_...', 'api_secret' => 'sk_live_...']);

The SDK will:

1. Automatically obtain an access token on the first request
2. Cache the token until it expires
3. Transparently refresh expired tokens

Usage

Send SMS

// Single recipient
$response = $client->messages->send([
    'content'    => 'Your verification code is 123456',
    'sender_id'  => 'TUSEME-LTD',
    'recipients' => [['msisdn' => '+254712345678']],
    'type'       => 'transactional',
]);

// Multiple recipients with metadata
$response = $client->messages->send([
    'content'    => 'Flash sale! 50% off today only.',
    'sender_id'  => 'TUSEME-LTD',
    'recipients' => [
        ['msisdn' => '+254712345678', 'name' => 'Alice'],
        ['msisdn' => '+254798765432', 'name' => 'Bob'],
    ],
    'type'     => 'promotional',
    'metadata' => ['campaign' => 'flash_sale_q2'],
]);

Check Delivery Status

$status = $client->messages->get('msg_a1b2c3d4...');
echo "Status: " . $status['status'] . "\n";
echo "Delivered at: " . $status['delivered_at'] . "\n";

List Messages

$result = $client->messages->list(['page' => 1, 'page_size' => 20, 'status' => 'delivered']);
foreach ($result['data'] as $msg) {
    echo $msg['recipient'] . ': ' . $msg['status'] . "\n";
}

Error Handling

use Tuseme\TusemeException;

try {
    $response = $client->messages->send([
        'content'    => 'Hello!',
        'recipients' => [['msisdn' => '+254712345678']],
    ]);
} catch (TusemeException $e) {
    if ($e->getCode() === 401) {
        echo "Invalid credentials — check your API key and secret\n";
    } elseif ($e->getCode() === 400) {
        echo "Bad request: " . $e->getMessage() . "\n";
    } elseif ($e->getCode() === 429) {
        echo "Rate limited — try again later\n";
    }
}

Configuration

$client = new TusemeClient([
    'api_key'     => '...',
    'api_secret'  => '...',
    'base_url'    => 'https://api.tuseme.co.ke/api/v1',  // default
    'timeout'     => 30,   // request timeout in seconds
    'max_retries' => 3,    // automatic retries on failure
]);

License

MIT — see LICENSE.