PHPackages                             sms-partners/php-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. sms-partners/php-sdk

ActiveLibrary[API Development](/categories/api)

sms-partners/php-sdk
====================

Official PHP SDK for the SMS Partners API.

v1.0.3(3w ago)0107MITPHPPHP ^8.1CI passing

Since Apr 20Pushed 3w agoCompare

[ Source](https://github.com/SMSPartners/php-sdk)[ Packagist](https://packagist.org/packages/sms-partners/php-sdk)[ RSS](/packages/sms-partners-php-sdk/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (4)Dependencies (3)Versions (8)Used By (0)

SMS Partners PHP SDK
====================

[](#sms-partners-php-sdk)

Official PHP SDK for the [SMS Partners](https://smspartners.app) API.

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Composer

Installation
------------

[](#installation)

```
composer require sms-partners/php-sdk
```

Getting Started
---------------

[](#getting-started)

Generate an API key from the **Developer → API Tokens** section of your SMS Partners account, then create a client:

```
use SmsPartners\Client;

$client = new Client(apiKey: 'your-api-key');
```

---

Sending SMS
-----------

[](#sending-sms)

```
$response = $client->send(
    to: '+61412345678',
    message: 'Your verification code is 123456.',
);

echo $response->id;          // Message ID
echo $response->status;      // "sending"
echo $response->to;          // "+61412345678" (first recipient)
echo $response->body;        // "Your verification code is 123456."
echo $response->creditsUsed; // 1
```

### With a custom Sender ID

[](#with-a-custom-sender-id)

Pass an approved Sender ID as the `from` argument to control how the message appears to the recipient:

```
$response = $client->send(
    to: '+61412345678',
    message: 'Your order has shipped.',
    from: 'MYCOMPANY',
);
```

The `from` value must match an **approved** Sender ID on your account. If omitted, the message is sent from the shared number pool.

### Scheduling a message

[](#scheduling-a-message)

Pass a `\DateTimeInterface` as `scheduledAt` to send the message at a future time. Credits are reserved immediately.

```
$response = $client->send(
    to: '+61412345678',
    message: 'Your appointment is tomorrow at 10am.',
    scheduledAt: new \DateTimeImmutable('+24 hours'),
);

echo $response->status;     // "scheduled"
echo $response->scheduledAt // DateTimeImmutable
```

### Credit cost

[](#credit-cost)

Credits are consumed based on message length and character encoding:

EncodingSingle SMSPer segment (multipart)GSM-7 (standard ASCII)160 chars153 charsUnicode (emoji, non-Latin)70 chars67 charsA single message can be up to 1,600 characters. Long messages are split into multiple segments and charged per segment.

### SendResponse properties

[](#sendresponse-properties)

`SendResponse` extends `Message` and adds a convenience `to` property.

PropertyTypeDescription`id``int`Message ID`status``string``sending`, `scheduled`, `sent`, `failed``body``string`Message body`from``?string`Sender ID name or pool number used`scheduledAt``?DateTimeImmutable`Scheduled send time, or `null``creditsUsed``int`Credits deducted`createdAt``DateTimeImmutable`When the message was created`recipients``Recipient[]`Delivery status per recipient`to``string`Convenience — phone of the first recipient---

Credit Balance
--------------

[](#credit-balance)

Quickly check the current balance without fetching the full account object:

```
$balance = $client->balance();

echo $balance; // 350
```

---

Messages
--------

[](#messages)

### List messages

[](#list-messages)

Retrieve your outbound message history, newest first. Results are paginated at 25 per page.

```
$page = $client->listMessages();

foreach ($page->data as $message) {
    echo "{$message->id}: {$message->status} — {$message->body}\n";
}

echo $page->total;       // Total messages across all pages
echo $page->currentPage; // 1
echo $page->lastPage;    // 4

if ($page->hasMore()) {
    $next = $client->listMessages(page: 2);
}
```

#### Filter by status

[](#filter-by-status)

```
$scheduled = $client->listMessages(status: 'scheduled');
$failed    = $client->listMessages(status: 'failed');
```

Available statuses: `scheduled`, `queued`, `sending`, `sent`, `failed`, `cancelled`.

### Get a single message

[](#get-a-single-message)

```
$message = $client->getMessage(id: 42);

echo $message->status; // "sent"

foreach ($message->recipients as $recipient) {
    echo "{$recipient->phone}: {$recipient->status}\n";
    echo $recipient->deliveredAt?->format('c'); // DateTimeImmutable or null
}
```

### Message properties

[](#message-properties)

PropertyTypeDescription`id``int`Message ID`status``string`Current message status`body``string`Message body`from``?string`Sender ID name or pool number used`scheduledAt``?DateTimeImmutable`Scheduled send time, or `null``creditsUsed``int`Credits charged`createdAt``DateTimeImmutable`When the message was created`recipients``Recipient[]`Delivery status per recipient### Recipient properties

[](#recipient-properties)

PropertyTypeDescription`phone``string`Recipient phone number`status``string``queued`, `sent`, `delivered`, or `failed``deliveredAt``?DateTimeImmutable`Delivery confirmation time, or `null``errorMessage``?string`Failure reason, or `null`### MessagePage properties

[](#messagepage-properties)

PropertyTypeDescription`data``Message[]`Messages on this page`total``int`Total messages across all pages`perPage``int`Page size (25)`currentPage``int`Current page number`lastPage``int`Last page number`hasMore()``bool`Whether more pages exist---

Sender IDs
----------

[](#sender-ids)

List all approved Sender IDs on your account. These are the values you can pass as `from` when sending:

```
$senderIds = $client->listSenderIds();

foreach ($senderIds as $sender) {
    echo "{$sender->name}\n"; // "MYCOMPANY"
}
```

### SenderId properties

[](#senderid-properties)

PropertyTypeDescription`id``int`Sender ID record ID`name``string`The sender name (use this as the `from` value)`status``string`Always `approved`---

Account
-------

[](#account)

Fetch your full account details:

```
$account = $client->account();

echo $account->name;           // "Acme Corp"
echo $account->email;          // "billing@acme.com"
echo $account->balanceCredits; // 500
echo $account->status;         // "active"

if ($account->isActive()) {
    // Account is in good standing
}
```

### AccountResponse properties

[](#accountresponse-properties)

PropertyTypeDescription`id``int`Account user ID`name``string`Account holder name`email``string`Account email address`balanceCredits``int`Current credit balance`status``string``active` or `suspended``autoTopupEnabled``bool`Whether auto top-up is active`autoTopupThreshold``int`Balance level that triggers top-up`autoTopupAmount``int`Credits purchased on auto top-up---

Webhooks
--------

[](#webhooks)

SMS Partners can send webhook events to your server when a message is delivered or fails. Configure webhook endpoints from the **Developer → Webhooks** section of your account.

### Verifying signatures

[](#verifying-signatures)

Every webhook request includes an `X-Webhook-Signature` header containing an HMAC-SHA256 signature of the raw request body. Always verify this before processing:

```
$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$secret    = 'your-webhook-secret';

if (! Client::verifyWebhook($payload, $signature, $secret)) {
    http_response_code(401);
    exit;
}
```

### Parsing events

[](#parsing-events)

After verifying the signature, parse the payload into a typed event object:

```
$event = Client::parseWebhook($payload);

echo $event->event;            // "message.delivered"
echo $event->messageId();      // 42
echo $event->recipientPhone(); // "+61412345678"

$event->timestamp; // DateTimeImmutable
```

### Handling specific events

[](#handling-specific-events)

```
if ($event->isDelivered()) {
    $messageId = $event->messageId();
    // Update your records...
}

if ($event->isFailed()) {
    $error = $event->data['recipient']['error_message'] ?? 'Unknown error';
    // Alert your team...
}
```

### Full webhook handler example

[](#full-webhook-handler-example)

```