SMS Quickstart Guide for PHP

This guide is for the current version of the PHP SDK.

Looking for v1? See our Quickstart guide for our Go v1 SDK.

Send your first SMS with the official ClickSend PHP SDK in under 5 minutes.

1. Prerequisites

Before you start, make sure you have:

Requirement	Details
A ClickSend account	Sign up free if you don't have one. New accounts get free credit to test with.
API credentials	Your username and API key, both on the API Credentials page of the dashboard. You'll authenticate with these, not your dashboard login password.
PHP 8.1 or newer with Composer	Check with `php -v` and `composer --version`.
Account credit	Sending SMS consumes credit. Free trial credit is enough for this guide; top up on the Billing page if you get an `INSUFFICIENT_CREDIT` error later.

2. Install

Install the SDK with Composer:

composer require clicksend/clicksend

3. Configure the client

The SDK authenticates with HTTP Basic auth, using a Configuration object built from your ClickSend username and API key. Never hard-code real credentials — load them from environment variables:

export CLICKSEND_USERNAME="your-clicksend-username"
export CLICKSEND_API_KEY="your-clicksend-api-key"

<?php
require_once __DIR__ . '/vendor/autoload.php';

use ClickSend\Configuration;
use ClickSend\Api\SmsApi;

$config = Configuration::getDefaultConfiguration()
    ->setUsername(getenv('CLICKSEND_USERNAME')) // placeholder: your ClickSend username
    ->setPassword(getenv('CLICKSEND_API_KEY'));  // placeholder: your ClickSend API key

$smsApi = new SmsApi(null, $config);

$smsApi is now an authenticated client for every SMS endpoint (send, history, templates, delivery receipts, etc.). Each ClickSend resource has its own API class (ClickSend\Api\MmsApi, ClickSend\Api\ManagementApi, ...) — construct one per resource you need, reusing the same $config.

4. Send your first SMS

This is a complete, runnable example. Save it as send-sms.php, set the two environment variables from step 3, replace the to number with a real one, and run it.

<?php
require_once __DIR__ . '/vendor/autoload.php';

use ClickSend\ApiException;
use ClickSend\Configuration;
use ClickSend\Api\SmsApi;
use ClickSend\Model\SendSmsRequest;
use ClickSend\Model\SendSmsRequestMessagesInner;

$config = Configuration::getDefaultConfiguration()
    ->setUsername(getenv('CLICKSEND_USERNAME'))
    ->setPassword(getenv('CLICKSEND_API_KEY'));

$smsApi = new SmsApi(null, $config);

$message = (new SendSmsRequestMessagesInner())
    ->setSource('sdk')
    ->setFrom('YOUR_SENDER_ID')          // placeholder: e.g. a ClickSend number, or omit to use your default sender
    ->setBody('Hello from ClickSend!')
    ->setTo('+61411111111');             // placeholder: recipient in E.164 format

$request = (new SendSmsRequest())->setMessages([$message]);

try {
    $result = $smsApi->sendSms(null, $request);
    print_r($result);
} catch (ApiException $e) {
    echo 'Failed to send SMS: ' . $e->getCode() . ' ' . $e->getResponseBody() . "\n";
}

Run it:

php send-sms.php

5. Understand the response

$smsApi->sendSms(...) returns a SendSms object. Its getters mirror the API's JSON response:

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Messages queued for delivery.",
  "data": {
    "total_price": 0.0388,
    "total_count": 1,
    "queued_count": 1,
    "blocked_count": 0,
    "messages": [
      {
        "to": "+61411111111",
        "body": "Hello from ClickSend!",
        "from": "SENDERID",
        "message_id": "6811A5CE-E374-5D26-82F5-1D9E52FA9AB3",
        "message_parts": 1,
        "message_price": "0.0388",
        "status": "SUCCESS",
        "date": 1758434400
      }
    ]
  }
}

The fields you'll use most, via the generated getters:

Field	Where	Meaning
Message ID	`$result->getData()->getMessages()[0]->getMessageId()`	The unique ID for this message. Quote this when contacting support or looking up delivery receipts.
Status	`$result->getData()->getMessages()[0]->getStatus()`	The outcome for this specific message (`SUCCESS`, `INVALID_RECIPIENT`, ...). Check this per message — a batch send can succeed overall while individual messages fail (see §6).
Cost	`$result->getData()->getMessages()[0]->getMessagePrice()`	Cost of this one message. `$result->getData()->getTotalPrice()` is the sum across every message in the request.

$message = $result->getData()->getMessages()[0];
echo "Message ID: " . $message->getMessageId() . "\n";
echo "Status: " . $message->getStatus() . "\n";
echo "Cost: " . $message->getMessagePrice() . "\n";

6. Common errors

$smsApi->sendSms(...) throws an ApiException on a non-2xx HTTP response — catch it with try/catch. But ClickSend also reports some failures — like an invalid recipient in an otherwise-valid batch — inside a 200 OK response, which won't throw at all. Always check each message's own getStatus(), not just whether the call threw.

try {
    $result = $smsApi->sendSms(null, $request);

    // Even on HTTP 200, check each message's own status
    foreach ($result->getData()->getMessages() as $message) {
        if ($message->getStatus() !== 'SUCCESS') {
            echo 'Message to ' . $message->getTo() . ' failed: ' . $message->getStatus() . "\n";
        }
    }
} catch (ApiException $e) {
    echo $e->getCode() . ' ' . $e->getResponseBody() . "\n";
}

Error	How it shows up	What it means	Fix
Authentication failure	`ApiException` with `->getCode() == 401` — thrown, caught in `catch`. `->getResponseBody()`'s `response_code` is `MISSING_CREDENTIALS` (no username/API key sent) or `INVALID_CREDENTIALS` (wrong username/API key).	Your `Configuration`'s username/password doesn't match a valid ClickSend account, or an env var wasn't set.	Double-check `CLICKSEND_USERNAME`/`CLICKSEND_API_KEY` are set and copied exactly from the API Credentials page — use the API key, not your dashboard password.
Invalid recipient	Request usually still returns HTTP 200 (`response_code: SUCCESS` at the top level) — the failure is on the individual message: `getStatus()` is `INVALID_RECIPIENT`. This does not throw — you must check the status yourself.	The destination mobile number isn't a valid, deliverable number (bad format, wrong country, disconnected, etc).	Validate/normalize numbers to E.164 (e.g. `+61411111111`) before sending, and surface per-message status values to your own logs or users.
Insufficient balance	`response_code` (or a message's `getStatus()`) is `INSUFFICIENT_CREDIT`, typically alongside an `ApiException` with `->getCode() == 400` when it blocks the whole request.	Your account has run out of message credit.	Top up credit on the Billing page, or check balance first with `(new ManagementApi(null, $config))->viewAccountDetails()`.

Next steps

Full endpoint reference: developers.clicksend.com/docs/rest/v3
Every other message type (MMS, voice, email, campaigns) and account/contact management: the package README
SDK source & issues: github.com/ClickSend/clicksend-php-v2

Products

Developers

Resources

SMS Quickstart

On this page:

Resources: