Developers / SMS Quickstart

SMS Quickstart

The fastest way to get started with ClickSend API in your preferred coding language.

Choose your language:

Resources:

Send your first SMS with the official ClickSend Java SDK (com.clicksend:clicksend-java on Maven Central) 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.
Java 8 or newer	Check with `java -version`. Maven or Gradle for dependency management.
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

Add the dependency with Maven:

<dependency>
  <groupId>com.clicksend</groupId>
  <artifactId>clicksend-java</artifactId>
  <version>6.0.3</version>
</dependency>

Or with Gradle:

implementation 'com.clicksend:clicksend-java:6.0.3'

3. Configure the client

The SDK authenticates with HTTP Basic auth, using your ClickSend username and API key set on the default ApiClient's basicAuth authentication. Never hard-code real credentials — load them from environment variables:

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

import ClickSend.ApiClient;
import ClickSend.Configuration;
import ClickSend.auth.HttpBasicAuth;
import ClickSend.Api.SmsApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();
HttpBasicAuth basicAuth = (HttpBasicAuth) defaultClient.getAuthentication("basicAuth");
basicAuth.setUsername(System.getenv("CLICKSEND_USERNAME")); // placeholder: your ClickSend username
basicAuth.setPassword(System.getenv("CLICKSEND_API_KEY"));  // placeholder: your ClickSend API key

SmsApi smsApi = new SmsApi(defaultClient);

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

4. Send your first SMS

This is a complete, runnable example. Set the two environment variables from step 3, replace the to number with a real one, and run it.

import ClickSend.ApiClient;
import ClickSend.ApiException;
import ClickSend.Configuration;
import ClickSend.auth.HttpBasicAuth;
import ClickSend.Api.SmsApi;
import ClickSend.Model.SendSms;
import ClickSend.Model.SendSmsRequest;
import ClickSend.Model.SendSmsRequestMessagesInner;

public class SendSmsExample {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        HttpBasicAuth basicAuth = (HttpBasicAuth) defaultClient.getAuthentication("basicAuth");
        basicAuth.setUsername(System.getenv("CLICKSEND_USERNAME"));
        basicAuth.setPassword(System.getenv("CLICKSEND_API_KEY"));

        SmsApi smsApi = new SmsApi(defaultClient);

        SendSmsRequest sendSmsRequest = new SendSmsRequest()
            .addMessagesItem(new SendSmsRequestMessagesInner()
                .source("sdk")
                .from("YOUR_SENDER_ID")            // placeholder: e.g. a ClickSend number, or omit to use your default sender
                .body("Hello from ClickSend!")
                .to("+61411111111"));              // placeholder: recipient in E.164 format

        try {
            SendSms result = smsApi.sendSms(null, sendSmsRequest); // first arg is the optional contentType header — pass null for the default
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Failed to send SMS: " + e.getCode() + " " + e.getResponseBody());
        }
    }
}

5. Understand the response

smsApi.sendSms(...) returns a SendSms object. Its structure mirrors 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().get(0).getMessageId()`	The unique ID for this message. Quote this when contacting support or looking up delivery receipts.
Status	`result.getData().getMessages().get(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().get(0).getMessagePrice()`	Cost of this one message. `result.getData().getTotalPrice()` is the sum across every message in the request.

SmsSendSms message = result.getData().getMessages().get(0);
System.out.println("Message ID: " + message.getMessageId());
System.out.println("Status: " + message.getStatus());
System.out.println("Cost: " + message.getMessagePrice());

6. Common errors

smsApi.sendSms(...) throws a checked 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 getStatus(), not just whether the call threw.

try {
    SendSms result = smsApi.sendSms(null, sendSmsRequest);

    // Even on HTTP 200, check each message's own status
    for (SmsSendSms message : result.getData().getMessages()) {
        if (!"SUCCESS".equals(message.getStatus())) {
            System.err.println("Message to " + message.getTo() + " failed: " + message.getStatus());
        }
    }
} catch (ApiException e) {
    System.err.println(e.getCode() + " " + e.getResponseBody());
}

Error	How it shows up	What it means	Fix
Authentication failure	`ApiException` with `getCode() == 401` — thrown, caught in `catch`. Response body's `response_code` is `MISSING_CREDENTIALS` (no username/API key sent) or `INVALID_CREDENTIALS` (wrong username/API key).	Your `HttpBasicAuth` username/password doesn't match a valid ClickSend account, or was left `null` because 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 `ManagementApi.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-java-v2

Our Swift SDK has been deprecated.

This guide uses our v1 SDK. Swift isn’t supported in the current SDK, so this guide won’t receive updates.

Before you start

You need a ClickSend account with credit to start sending. If you don’t have an account, create one here.
If you need to add more credit to your account, you can top up here. You’ll be credited $2 AUD free credit when you sign up.

Installation

Install via Cocoapods

CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website.

To integrate ClickSendSwift into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'ClickSendSwift'

Update Swift Version

The ClickSend SDK was built using Swift Version 4.2.

To update the language version, select Pods within the project from the left panel > Targets > ClickSendSwift > Swift Compiler - Language > Choose Swift 4.2. Repeat these steps for Alamofire.

Send your first message

Below is the full snippet you can use to send an SMS. It includes placeholders that will need to be replaced when implementing the code in your project.

Placeholder	Replace with
`USERNAME`	Your ClickSend Username. Find it here.
`API_KEY`	Your ClickSend API key. Find it here.
`SOURCE`	The origin identifier for your API request, which could be the name of your application or the source location for the request.
`MESSAGE`	The content of your SMS message.
`TO_PHONE_NUMBER`	The phone number you're sending the message to, including the country code.

import ClickSendSwift
import Alamofire

if let authHeader = Request.authorizationHeader(user: "USERNAME", password: "API_KEY") {
    ClickSendClientAPI.customHeaders = [authHeader.key : authHeader.value]
}

let message = SmsMessage(
   source: "SOURCE",
   body: "MESSAGE",
   to: "TO_PHONE_NUMBER")

let smsCollection = SmsMessageCollection(messages: [message])

SMSAPI.smsSendPost(smsMessages: smsCollection) { (dataString, error) in
    guard let dataString = dataString else {
        print(error!)
        return
    }

    if let data = dataString.data(using: String.Encoding.utf8) {
        do {
            if let dictonary = try (JSONSerialization.jsonObject(with: data, options: []) as? NSDictionary) {
                print(dictonary)
            } else {
                print("bad json")
            }
        } catch let error as NSError {
            print(error)
        }
    }
}

The code explained

Import libraries

Prepare your environment to use the ClickSend API by importing the SDK and required libraries.

import ClickSendSwift
import Alamofire

Authorisation

Next, add your API credentials so you can use the ClickSend API in your project.

In the following snippet, simply replace the USERNAME and API_KEY placeholders with your own Username and API key. These can be found in your Dashboard here.

if let authHeader = Request.authorizationHeader(user: "USERNAME", password: "API_KEY") {
    ClickSendClientAPI.customHeaders = [authHeader.key : authHeader.value]
}

Configure your message

It’s time to configure the content of your message and specify who you’re sending to. This code includes everything you need to send an SMS message. To see what other parameters you can include, see our full API reference.

Now, it’s a simple matter of a few tweaks:

Replace SOURCE with your preferred source (eg. the name of your application). This is not seen by recipients, but will help you to identify messages sent from various applications.
Replace MESSAGE with your own message.
Replace TO_PHONE_NUMBER with your own mobile number, including country code. For example, if you have an Australian number, it will start with +61.

let message = SmsMessage(
   source: "SOURCE",
   body: "MESSAGE",
   to: "TO_PHONE_NUMBER")

Create an SMS message collection

Next, we’ll create a collection and add the SmsMessage that you created earlier.

let smsCollection = SmsMessageCollection(messages: [message])

Send SMS message

Finally, try to call the smsSendPost method using the smsCollection you created earlier. If everything works as expected then it will print the formatted response.

If an exception occurs during the API call, the completion handler will log the outputted details. This structure helps you handle both successful API calls and potential errors that might occur during the process.

SMSAPI.smsSendPost(smsMessages: smsCollection) { (dataString, error) in
    guard let dataString = dataString else {
        print(error!)
        return
    }

    if let data = dataString.data(using: String.Encoding.utf8) {
        do {
            if let dictonary = try (JSONSerialization.jsonObject(with: data, options: []) as? NSDictionary) {
                print(dictonary)
            } else {
                print("bad json")
            }
        } catch let error as NSError {
            print(error)
        }
    }
}

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

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

Send your first SMS with the official ClickSend Ruby SDK (the clicksend_client gem) 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.
Ruby 2.7 or newer	Check with `ruby -v`.
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

Add the gem to your Gemfile:

gem 'clicksend_client', '~> 6.0.2'

bundle install

Or install it directly:

gem install clicksend_client

3. Configure the client

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

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

require 'clicksend_client'

ClickSend.configure do |config|
  config.username = ENV['CLICKSEND_USERNAME'] # placeholder: your ClickSend username
  config.password = ENV['CLICKSEND_API_KEY']  # placeholder: your ClickSend API key
end

sms_api = ClickSend::SmsApi.new

sms_api is now an authenticated client for every SMS endpoint (send, history, templates, delivery receipts, etc.). Each ClickSend resource has its own API class (ClickSend::MmsApi, ClickSend::ManagementApi, ClickSend::ContactsApi, ...) — construct one per resource you need; they all share the configuration set via ClickSend.configure.

4. Send your first SMS

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

require 'clicksend_client'

ClickSend.configure do |config|
  config.username = ENV['CLICKSEND_USERNAME']
  config.password = ENV['CLICKSEND_API_KEY']
end

sms_api = ClickSend::SmsApi.new

message = ClickSend::SendSmsRequestMessagesInner.new(
  source: 'sdk',
  from: 'YOUR_SENDER_ID',      # placeholder: e.g. a ClickSend number, or omit to use your default sender
  body: 'Hello from ClickSend!',
  to: '+61411111111'           # placeholder: recipient in E.164 format
)
request = ClickSend::SendSmsRequest.new(messages: [message])

begin
  result = sms_api.send_sms(send_sms_request: request)
  puts result
rescue ClickSend::ApiError => e
  puts "Failed to send SMS: #{e.code} #{e.response_body}"
end

Run it:

ruby send_sms.rb

5. Understand the response

sms_api.send_sms(...) returns a ClickSend::SendSms object. Its attributes mirror the API's JSON response (native snake_case):

{
  "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:

Field	Where	Meaning
Message ID	`result.data.messages[0].message_id`	The unique ID for this message. Quote this when contacting support or looking up delivery receipts.
Status	`result.data.messages[0].status`	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.data.messages[0].message_price`	Cost of this one message. `result.data.total_price` is the sum across every message in the request.

message = result.data.messages.first
puts "Message ID: #{message.message_id}"
puts "Status: #{message.status}"
puts "Cost: #{message.message_price}"

6. Common errors

sms_api.send_sms(...) raises a ClickSend::ApiError on a non-2xx HTTP response — rescue it. But ClickSend also reports some failures — like an invalid recipient in an otherwise-valid batch — inside a 200 OK response, which won't raise at all. Always check each message's own status, not just whether the call raised.

begin
  result = sms_api.send_sms(send_sms_request: request)

  # Even on HTTP 200, check each message's own status
  result.data.messages.each do |message|
    unless message.status == 'SUCCESS'
      puts "Message to #{message.to} failed: #{message.status}"
    end
  end
rescue ClickSend::ApiError => e
  puts "#{e.code} #{e.response_body}"
end

Error	How it shows up	What it means	Fix
Authentication failure	`ClickSend::ApiError` with `.code == 401` — raised, rescued in `rescue`. `.response_body`'s `response_code` is `MISSING_CREDENTIALS` (no username/API key sent) or `INVALID_CREDENTIALS` (wrong username/API key).	Your `ClickSend.configure` 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: `message.status` is `INVALID_RECIPIENT`. This does not raise — 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 `status`) is `INSUFFICIENT_CREDIT`, typically alongside a `ClickSend::ApiError` with `.code == 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 `ClickSend::ManagementApi.new.view_account_details`.

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-ruby-v2

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

Our Perl SDK has been deprecated.

This guide uses our v1 SDK. Perl is no longer supported in the current SDK, so this guide won’t receive updates.

Before you start

You need a ClickSend account with credit to start sending. If you don’t have an account, create one here.
If you need to add more credit to your account, you can top up here. You’ll be credited $2 AUD free credit when you sign up.

Installation

Install via Github

Our Perl SDK is hosted on Github, and can be installed by downloading the repository and copying the contents of the lib directory to a location that perl searches.

Note: git needs to be installed first using your operating system’s usual method. e.g. “sudo apt update; sudo apt install git” for Debian/Ubuntu systems or “sudo yum install git” for RedHat/CentOS.

git clone https://github.com/ClickSend/clicksend-perl.git

Copy the WWW directory and contents from the lib directory created above to your project’s directory or to one of the system locations that Perl searches. To view the locations that Perl searches on your system, run:

perl -e 'for (@INC) { print "$_\n"; }'

Individual ClickSend modules can then be included in your code with the “use” directive. e.g.

use WWW::ClickSendClient::SMSApi;

Send your first message

Below is the full snippet you can use to send an SMS. It includes placeholders that will need to be replaced when implementing the code in your project.

Placeholder	Replace with
`USERNAME`	Your ClickSend Username. Find it here.
`API_KEY`	Your ClickSend API key. Find it here.
`SOURCE`	The origin identifier for your API request, which could be the name of your application or the source location for the request.
`MESSAGE`	The content of your SMS message.
`TO_PHONE_NUMBER`	The phone number you're sending the message to, including the country code.

#!/usr/bin/perl -w
use WWW::ClickSendClient::SMSApi;
use WWW::ClickSendClient::Object::SmsMessageCollection;

my $USERNAME = 'my-clicksend-username@example.com';
my $API_KEY = 'FEDC0123-0123-4567-89AB-CDEF01234567';
my $TO_PHONE_NUMBER = '+61411111111';
my $MESSAGE = "Test message from perl";

my $api = WWW::ClickSendClient::SMSApi->new(username => "$USERNAME",
password => "$API_KEY");

my $sms_messages = WWW::ClickSendClient::Object::SmsMessageCollection-
>new(
  messages => [{
    source => 'perl',
    to => "$TO_PHONE_NUMBER",
    body => "$MESSAGE"
  }]);
  
my $json_output = $api->sms_send_post(sms_messages => $sms_messages);

print $json_output;

The code: explained

Import functions

Start by preparing your environment to use the ClickSend API. Import the necessary modules, including the ClickSend SMS API and Message Collection object.

use WWW::ClickSendClient::SMSApi;
use WWW::ClickSendClient::Object::SmsMessageCollection;

Authorisation and create an instance of the API class

Next, set up your Username and API Key so you can use the ClickSend API in your project.

In the following snippet, simply replace the placeholders $USERNAME and $API_KEY with your own Username and API Key. These can be found in the Dashboard here.

This API instance returned from this call will allow you to interact with the ClickSend API's account-related functionality.

my $api = WWW::ClickSendClient::SMSApi->new(
username => "$USERNAME",
password => "$API_KEY");

Configure your message

Next, configure the content of your message and define who you’re sending to-and- from.

Here you will want to replace the placeholder ‘$SOURCE’ with your preferred source (eg. the name of your application). This is not seen by recipients but will help you to identify messages sent from various applications.

Replace “$MESSAGE” with a message of your choice, and replace “$TO_PHONE_NUMBER” with the number that you’ll be sending the message to.

For testing purposes, we recommend you start by sending to your own number.

The messages parameter is an array of hashes. Each hash makes up a single SMS message to be sent. In this example we only include a single SMS message.

For additional properties that you can use here, see the Full API Reference.

my $sms_messages = WWW::ClickSendClient::Object::SmsMessageCollection-
>new(
  messages => [{
    source => "$SOURCE",
    to => "$TO_PHONE_NUMBER",
    body => "$MESSAGE"
  }]);

Send SMS message

Finally, try to call the SMS_SEND_POST method using the API_INSTANCE you've created. If everything works as expected then it will print the response as raw JSON. The outcome of the call can be seen from the http_code and response_code attributes in the JSON response. There is also an array called ‘messages’ within the ‘data’ structure and each message within this array has a ‘status’ attribute.the formatted response.

my $json_output = $api->sms_send_post(sms_messages => $sms_messages);
print $json_output;

This guide is for the current version of the Node.js SDK.

Looking for v1? See our Quickstart guide for our Node.js v1 SDK.

Send your first SMS with the official clicksend npm package in under 5 minutes.

This guide covers the current v2 SDK (clicksend, built on axios). If you're upgrading from the legacy @clicksend/clicksend-nodejs package, see the migration guide instead.

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.
Node.js 14 or newer	Check with `node -v`. TypeScript is optional — the package ships plain JS + `.d.ts` types, so it works from a `.ts` or a plain `.js` file.
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 your package manager of choice:

npm install clicksend

# yarn
yarn add clicksend

# pnpm
pnpm add clicksend

3. Configure the client

Every API class in the SDK authenticates with HTTP Basic auth, using a Configuration object built from your ClickSend username and API key (not a bearer token). Never hard-code real credentials — load them from environment variables:

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

import { Configuration, SmsApi } from 'clicksend';

const configuration = new Configuration({
  username: process.env.CLICKSEND_USERNAME, // placeholder: your ClickSend username
  password: process.env.CLICKSEND_API_KEY,  // placeholder: your ClickSend API key
});

const smsApi = new SmsApi(configuration);

That's it — smsApi is now an authenticated client for every SMS endpoint (send, history, templates, delivery receipts, etc.). Each ClickSend resource has its own API class (MmsApi, ManagementApi, ContactsApi, ...); construct one per resource you need, reusing the same configuration.

4. Send your first SMS

This is a complete, runnable example. Save it as send-sms.ts (or .js, dropping the types), set the two environment variables from step 3, replace the to number with a real one, and run it.

import { Configuration, SmsApi } from 'clicksend';

async function main() {
  const configuration = new Configuration({
    username: process.env.CLICKSEND_USERNAME,
    password: process.env.CLICKSEND_API_KEY,
  });

  const smsApi = new SmsApi(configuration);

  const { data } = await smsApi.sendSms({
    sendSmsRequest: {
      messages: [
        {
          source: 'sdk',
          from: 'YOUR_SENDER_ID',        // placeholder: e.g. a ClickSend number, or omit to use your default sender
          body: 'Hello from ClickSend!',
          to: '+61411111111',            // placeholder: recipient in E.164 format
        },
      ],
    },
  });

  console.log(data);
}

main().catch((error) => {
  console.error('Failed to send SMS:', error.message);
  process.exit(1);
});

Run it:

npx tsx send-sms.ts      # TypeScript, no build step
# or: node send-sms.js   # if you dropped the types

Field names inside the request body are snake_case, not camelCase (from_email, list_id, etc. — to/from/body/source are single words so they look the same either way). Only the outer { sendSmsRequest: ... } wrapper key is camelCase. Getting this wrong doesn't throw — the server just silently ignores the misspelled field.

5. Understand the response

smsApi.sendSms(...) resolves to an axios response; the ClickSend payload is on .data. It looks like this:

{
  "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:

Field	Where	Meaning
Message ID	`data.data.messages[0].message_id`	The unique ID for this message. Quote this when contacting support or looking up delivery receipts.
Status	`data.data.messages[0].status`	The outcome for this specific message (`SUCCESS`, `INVALID_RECIPIENT`, ...). Check this per message — a batch send can return HTTP 200 overall while individual messages fail (see §6).
Cost	`data.data.messages[0].message_price`	Cost of this one message (string, in your account's currency). `data.data.total_price` is the sum across every message in the request.
`data.response_code` / `data.response_msg`	Top level	The outcome of the request as a whole (`SUCCESS` + a human-readable message), not of any individual message.

const { data } = await smsApi.sendSms({ sendSmsRequest });

const [message] = data.data?.messages ?? [];
console.log('Message ID:', message?.message_id);
console.log('Status:', message?.status);
console.log('Cost:', message?.message_price);

6. Common errors

The SDK is built on axios: a non-2xx HTTP response rejects the promise as an AxiosError, which you catch with try/catch. But ClickSend also reports some failures — like an invalid recipient in an otherwise-valid batch — inside a 200 OK response body, which won't throw at all. Always check status/response_code, not just whether the call threw.

import axios from 'axios';

try {
  const { data } = await smsApi.sendSms({ sendSmsRequest });

  // Even on HTTP 200, check each message's own status
  for (const message of data.data?.messages ?? []) {
    if (message.status !== 'SUCCESS') {
      console.warn(`Message to ${message.to} failed: ${message.status}`);
    }
  }
} catch (error) {
  if (axios.isAxiosError(error)) {
    console.error(error.response?.status, error.response?.data);
  } else {
    throw error;
  }
}

Error	How it shows up	What it means	Fix
Authentication failure	HTTP 401 Unauthorized — the promise rejects, caught in `catch`. Body's `response_code` is `MISSING_CREDENTIALS` (no username/API key sent) or `INVALID_CREDENTIALS` (wrong username/API key).	Your `Configuration({ username, password })` doesn't match a valid ClickSend account, or was left as `undefined` because 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: `data.data.messages[0].status` is `INVALID_RECIPIENT`. This does not throw — you must check the `status` field 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 `status`) is `INSUFFICIENT_CREDIT`, typically alongside an HTTP 400 Bad Request 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 `ManagementApi.viewAccountDetails()`.

Next steps

Full endpoint reference: developers.clicksend.com/docs/rest/v3
Every other message type (MMS, voice, campaigns) and account/contact management: the package README
Migrating from the legacy SDK: github.com/ClickSend/clicksend-nodejs-v2/blob/main/docs/MIGRATION.md
SDK source & issues: github.com/ClickSend/clicksend-nodejs-v2

This guide is for the current version of the C# SDK.

Looking for v1? See our Quickstart guide for our C# v1 SDK.

Send your first SMS with the official ClickSend .NET SDK (ClickSend on NuGet) 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.
.NET 10.0 or newer	This SDK targets `net10.0`. Check with `dotnet --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

dotnet add package ClickSend

Or add it directly to your .csproj:

<PackageReference Include="ClickSend" Version="6.0.2" />

3. Configure the client

The SDK is wired up through Microsoft.Extensions.Hosting dependency injection rather than a standalone client object. Authentication uses HTTP Basic auth via a BasicToken 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"

using ClickSend.Client;
using ClickSend.Api;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureApi((context, services, options) =>
    {
        BasicToken token = new(
            Environment.GetEnvironmentVariable("CLICKSEND_USERNAME"), // placeholder: your ClickSend username
            Environment.GetEnvironmentVariable("CLICKSEND_API_KEY")); // placeholder: your ClickSend API key
        options.AddTokens(token);
    })
    .Build();

var smsApi = host.Services.GetRequiredService<ISmsApi>();

smsApi is now an authenticated client for every SMS endpoint (send, history, templates, delivery receipts, etc.). Every other ClickSend resource has its own interface resolvable from the same host.Services (e.g. IMmsApi, IManagementApi, IContactsApi).

4. Send your first SMS

This is a complete, runnable example. Set the two environment variables from step 3, replace the to number with a real one, and run it.

using ClickSend.Client;
using ClickSend.Api;
using ClickSend.Model;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureApi((context, services, options) =>
    {
        BasicToken token = new(
            Environment.GetEnvironmentVariable("CLICKSEND_USERNAME"),
            Environment.GetEnvironmentVariable("CLICKSEND_API_KEY"));
        options.AddTokens(token);
    })
    .Build();

var smsApi = host.Services.GetRequiredService<ISmsApi>();

var sendSmsRequest = new SendSmsRequest(messages: new List<SendSmsRequestMessagesInner>
{
    new(
        source: "sdk",
        from: "YOUR_SENDER_ID",       // placeholder: e.g. a ClickSend number, or omit to use your default sender
        body: "Hello from ClickSend!",
        to: "+61411111111")           // placeholder: recipient in E.164 format
});

var response = await smsApi.SendSmsAsync(sendSmsRequest: sendSmsRequest);

if (response.IsSuccessStatusCode)
{
    var result = response.Ok();
    Console.WriteLine(result);
}
else
{
    Console.WriteLine($"Failed to send SMS: {response.StatusCode} {response.RawContent}");
}

5. Understand the response

smsApi.SendSmsAsync(...) returns an ISendSmsApiResponse. Call .Ok() to get the typed SendSms payload once you've confirmed IsSuccessStatusCode:

{
  "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 (PascalCase) properties:

Field	Where	Meaning
Message ID	`result.Data.Messages[0].MessageId`	The unique ID for this message. Quote this when contacting support or looking up delivery receipts.
Status	`result.Data.Messages[0].Status`	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.Data.Messages[0].MessagePrice`	Cost of this one message. `result.Data.TotalPrice` is the sum across every message in the request.

var message = result.Data.Messages[0];
Console.WriteLine($"Message ID: {message.MessageId}");
Console.WriteLine($"Status: {message.Status}");
Console.WriteLine($"Cost: {message.MessagePrice}");

6. Common errors

Unlike most other ClickSend SDKs, this one does not throw an exception on a non-2xx HTTP response — SendSmsAsync always completes successfully, and you inspect response.IsSuccessStatusCode / response.StatusCode / response.RawContent yourself. ClickSend also reports some failures — like an invalid recipient in an otherwise-valid batch — inside a 200 OK response, which is a separate check again. Always check both the HTTP-level status and each message's own Status.

var response = await smsApi.SendSmsAsync(sendSmsRequest: sendSmsRequest);

if (!response.IsSuccessStatusCode)
{
    Console.WriteLine($"HTTP error: {response.StatusCode} {response.RawContent}");
    return;
}

var result = response.Ok();
foreach (var message in result.Data.Messages)
{
    if (message.Status != "SUCCESS")
    {
        Console.WriteLine($"Message to {message.To} failed: {message.Status}");
    }
}

Error	How it shows up	What it means	Fix
Authentication failure	`response.StatusCode == HttpStatusCode.Unauthorized` (401) — `IsSuccessStatusCode` is `false`, no exception thrown. `response.RawContent`'s `response_code` is `MISSING_CREDENTIALS` (no username/API key sent) or `INVALID_CREDENTIALS` (wrong username/API key).	Your `BasicToken` 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 (`IsSuccessStatusCode` is `true`, `response_code: SUCCESS` at the top level) — the failure is on the individual message: `message.Status` is `INVALID_RECIPIENT`. This does not fail the HTTP call — 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 `Status`) is `INSUFFICIENT_CREDIT`, typically alongside `response.StatusCode == HttpStatusCode.BadRequest` (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 `IManagementApi.ViewAccountDetailsAsync()`.

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-csharp-v2

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

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

Send your first SMS with the official ClickSend Go 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.
Go 1.23 or newer	Check with `go 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

go get github.com/ClickSend/clicksend-go-v2/v6

3. Configure the client

The SDK authenticates with HTTP Basic auth, applied per-request via a context.Context carrying a BasicAuth value. Never hard-code real credentials — load them from environment variables:

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

package main

import (
    "context"
    "os"

    clicksend "github.com/ClickSend/clicksend-go-v2/v6"
)

func main() {
    cfg := clicksend.NewConfiguration()
    client := clicksend.NewAPIClient(cfg)

    auth := context.WithValue(context.Background(), clicksend.ContextBasicAuth, clicksend.BasicAuth{
        UserName: os.Getenv("CLICKSEND_USERNAME"), // placeholder: your ClickSend username
        Password: os.Getenv("CLICKSEND_API_KEY"),  // placeholder: your ClickSend API key
    })

    _ = auth
    _ = client
}

client is now an authenticated client for every ClickSend resource — each is a field on it (client.SmsAPI, client.MmsAPI, client.ManagementAPI, ...). Pass the same auth context to every call.

4. Send your first SMS

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

package main

import (
    "context"
    "fmt"
    "os"

    clicksend "github.com/ClickSend/clicksend-go-v2/v6"
)

func main() {
    cfg := clicksend.NewConfiguration()
    client := clicksend.NewAPIClient(cfg)

    auth := context.WithValue(context.Background(), clicksend.ContextBasicAuth, clicksend.BasicAuth{
        UserName: os.Getenv("CLICKSEND_USERNAME"),
        Password: os.Getenv("CLICKSEND_API_KEY"),
    })

    message := clicksend.NewSendSmsRequestMessagesInnerWithDefaults()   message.SetFrom("YOUR_SENDER_ID") // placeholder: e.g. a ClickSend number, or omit to use your default sender
    message.SetBody("Hello from ClickSend!")
    message.SetTo("+61411111111") // placeholder: recipient in E.164 format

    sendSmsRequest := clicksend.NewSendSmsRequestWithDefaults()
    sendSmsRequest.SetMessages([]clicksend.SendSmsRequestMessagesInner{*message})

    result, httpResp, err := client.SmsAPI.SendSms(auth).SendSmsRequest(*sendSmsRequest).Execute()
    if err != nil {
        status := 0
        if httpResp != nil {
            status = httpResp.StatusCode
        }
        fmt.Printf("Failed to send SMS: %d %v\n", status, err)
        return
    }

    fmt.Printf("%+v\n", result)
}

Run it:

go run send_sms.go

5. Understand the response

client.SmsAPI.SendSms(...).Execute() returns (*SendSms, *http.Response, error). Every model field is a pointer, so use the generated pointer-safe getters rather than dereferencing fields directly:

{
  "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:

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 (string). `result.GetData().GetTotalPrice()` is the sum across every message in the request.

message := result.GetData().GetMessages()[0]
fmt.Println("Message ID:", message.GetMessageId())
fmt.Println("Status:", message.GetStatus())
fmt.Println("Cost:", message.GetMessagePrice())

6. Common errors

client.SmsAPI.SendSms(...).Execute() returns a non-nil error on a non-2xx HTTP response — check it before touching result. But ClickSend also reports some failures — like an invalid recipient in an otherwise-valid batch — inside a 200 OK response, which won't produce an error at all. Always check each message's own GetStatus(), not just whether err is non-nil.

result, httpResp, err := client.SmsAPI.SendSms(auth).SendSmsRequest(*sendSmsRequest).Execute()
if err != nil {
    status := 0
    if httpResp != nil {
        status = httpResp.StatusCode
    }
    fmt.Printf("HTTP error: %d %v\n", status, err)
    return
}

// Even on HTTP 200, check each message's own status
for _, message := range result.GetData().GetMessages() {
    if message.GetStatus() != "SUCCESS" {
        fmt.Printf("Message to %s failed: %s\n", message.GetTo(), message.GetStatus())
    }
}

Error	How it shows up	What it means	Fix
Authentication failure	`err != nil`, `httpResp.StatusCode == 401` — the response body's `response_code` is `MISSING_CREDENTIALS` (no username/API key sent) or `INVALID_CREDENTIALS` (wrong username/API key).	Your `BasicAuth{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, `err` is `nil`) — the failure is on the individual message: `message.GetStatus()` is `INVALID_RECIPIENT`. This does not produce an error — 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 `httpResp.StatusCode == 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 `client.ManagementAPI.ViewAccountDetails(auth).Execute()`.

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-go-v2

Our Objective C SDK has been deprecated.

This guide uses our v1 SDK. Objective C isn’t supported in the current SDK, so this guide won’t receive updates.

Before you start

You need a ClickSend account with credit to start sending. If you don’t have an account, create one here.
If you need to add more credit to your account, you can top up here. You’ll be credited $2 AUD free credit when you sign up.

Installation

Install via Cocoapods

CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website.

To integrate ClickSendClient into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'ClickSendClient', :git => 'https://github.com/ClickSend/clicksend-objc'

Send your first message

Below is the full snippet you can use to send an SMS. It includes placeholders that will need to be replaced when implementing the code in your project.

Placeholder	Replace with
`USERNAME`	Your ClickSend Username. Find it here.
`API_KEY`	Your ClickSend API key. Find it here.
`SOURCE`	The origin identifier for your API request, which could be the name of your application or the source location for the request.
`MESSAGE`	The content of your SMS message.
`TO_PHONE_NUMBER`	The phone number you're sending the message to, including the country code.

#import <ClickSendClient/CSApiClient.h>
#import <ClickSendClient/CSDefaultConfiguration.h>
#import <ClickSendClient/CSSMSApi.h>

CSDefaultConfiguration *apiConfig = [CSDefaultConfiguration sharedConfig];
[apiConfig setUsername:"USERNAME""];
[apiConfig setPassword:"API_KEY""];

CSApiClient *apiClient = [[CSApiClient alloc] initWithConfiguration:apiConfig];

CSSmsMessage *message = [[CSSmsMessage alloc] init];
message.source = "SOURCE";
message.body = "MESSAGE";
message.to = "TO_PHONE_NUMBER";

CSSmsMessageCollection *smsCollection = [[CSSmsMessageCollection alloc] init];
[smsCollection setMessages:(NSArray<CSSmsMessage> *)@[message]];

CSSMSApi *smsApi = [[CSSMSApi alloc] initWithApiClient:apiClient];
[smsApi smsSendPostWithSmsMessages:smsCollection completionHandler:^(NSString *output, NSError *error) {
    if (error != nil) {
        NSLog(@"Error %@", error.description);
    } else {
        NSLog(@"Output %@", output);
    }
}];

The code explained

Import modules

Prepare your environment to use the ClickSend API by importing the SDK and required modules.

#import <ClickSendClient/CSApiClient.h>
#import <ClickSendClient/CSDefaultConfiguration.h>
#import <ClickSendClient/CSSMSApi.h>

Authorisation

Next, add your API credentials so you can use the ClickSend API in your project.

In the following snippet, simply replace the USERNAME and API_KEY placeholders with your own Username and API key. These can be found in your Dashboard here.

CSDefaultConfiguration *apiConfig = [CSDefaultConfiguration sharedConfig];
[apiConfig setUsername:"USERNAME""];
[apiConfig setPassword:"API_KEY""];

Create an instance of the API class

The following snippet of code will create an instance of the CSApiClient class. This instance will be called in the following steps, allowing you to interact with ClickSend’s SMS functionality.

CSApiClient *apiClient = [[CSApiClient alloc] initWithConfiguration:apiConfig];

Configure your message

It’s time to configure the content of your message and specify who you’re sending to. This code includes everything that you need to send an SMS message. To see what other parameters you can include, see our full API reference.

Now, it’s a simple matter of a few tweaks:

Replace SOURCE with your preferred source (eg. the name of your application). This is not seen by recipients, but will help you to identify messages sent from various applications.

Replace MESSAGE with your own message.

Replace TO_PHONE_NUMBER with your own mobile number, including country code. For example, if you have an Australian number, it will start with +61.

CSSmsMessage *message = [[CSSmsMessage alloc] init];
message.source = "SOURCE";
message.body = "MESSAGE";
message.to = "TO_PHONE_NUMBER";

Create an SMS message collection

Next, we’ll create a collection and add the CSSmsMessage that you created earlier.

CSSmsMessageCollection *smsCollection = [[CSSmsMessageCollection alloc] init];
[smsCollection setMessages:(NSArray<CSSmsMessage> *)@[message]];

Send SMS message

Finally, try to call the smsSendPostWithSmsMessages method using the smsCollection you created earlier. If everything works as expected then it will print the formatted response. If an exception occurs during the API call, the completion handler will log the outputted details. This structure helps you handle both successful API calls and potential errors that might occur during the process.

CSSMSApi *smsApi = [[CSSMSApi alloc] initWithApiClient:apiClient];
[smsApi smsSendPostWithSmsMessages:smsCollection completionHandler:^(NSString *output, NSError *error) {
    if (error != nil) {
        NSLog(@"Error %@", error.description);
    } else {
        NSLog(@"Output %@", output);
    }
}];

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

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

Send your first SMS with the official ClickSend Python 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.
Python 3.10 or newer	Check with `python3 --version`. (The repo's own build files disagree — `setup.py` requires 3.10+, `pyproject.toml` says 3.9+ — 3.10+ is the safer bound until that's reconciled.)
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

pip install clicksend-client

3. Configure the client

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

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

import os
import clicksend
from clicksend.api.sms_api import SmsApi

configuration = clicksend.Configuration(
    username=os.environ.get("CLICKSEND_USERNAME"),  # placeholder: your ClickSend username
    password=os.environ.get("CLICKSEND_API_KEY"),   # placeholder: your ClickSend API key
)

with clicksend.ApiClient(configuration) as api_client:
    sms_api = SmsApi(api_client)

sms_api 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.mms_api.MmsApi, clicksend.api.management_api.ManagementApi, ...) — construct one per resource you need, reusing the same api_client.

4. Send your first SMS

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

import os
import clicksend
from clicksend.api.sms_api import SmsApi
from clicksend.models.send_sms_request import SendSmsRequest
from clicksend.models.send_sms_request_messages_inner import SendSmsRequestMessagesInner
from clicksend.exceptions import ApiException

configuration = clicksend.Configuration(
    username=os.environ.get("CLICKSEND_USERNAME"),
    password=os.environ.get("CLICKSEND_API_KEY"),
)

with clicksend.ApiClient(configuration) as api_client:
    sms_api = SmsApi(api_client)

    message = SendSmsRequestMessagesInner(
        body="Hello from ClickSend!",
        to="+61411111111",         # placeholder: recipient in E.164 format
        **{"from": "YOUR_SENDER_ID"},  # placeholder: e.g. a ClickSend number, or omit to use your default sender
    )
    send_sms_request = SendSmsRequest(messages=[message])

    try:
        result = sms_api.send_sms(send_sms_request=send_sms_request)
        print(result)
    except ApiException as e:
        print(f"Failed to send SMS: {e.status} {e.body}")

Run it:

python3 send_sms.py

5. Understand the response

sms_api.send_sms(...) returns a SendSms object. Its attributes mirror the API's JSON response (native snake_case):

{
  "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:

Field	Where	Meaning
Message ID	`result.data.messages[0].message_id`	The unique ID for this message. Quote this when contacting support or looking up delivery receipts.
Status	`result.data.messages[0].status`	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.data.messages[0].message_price`	Cost of this one message (string). `result.data.total_price` is the sum across every message in the request.

message = result.data.messages[0]
print("Message ID:", message.message_id)
print("Status:", message.status)
print("Cost:", message.message_price)

6. Common errors

sms_api.send_sms(...) raises an ApiException (or a status-specific subclass like UnauthorizedException) on a non-2xx HTTP response — catch it with try/except. But ClickSend also reports some failures — like an invalid recipient in an otherwise-valid batch — inside a 200 OK response, which won't raise at all. Always check each message's own status, not just whether the call raised.

Error	How it shows up	What it means	Fix
Authentication failure	`UnauthorizedException` (a subclass of `ApiException` with `.status == 401`) — raised, caught in `except`. `.body`'s `response_code` is `MISSING_CREDENTIALS` (no username/API key sent) or `INVALID_CREDENTIALS` (wrong username/API key).	Your `Configuration(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: `message.status` is `INVALID_RECIPIENT`. This does not raise — 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 `status`) is `INSUFFICIENT_CREDIT`, typically alongside a `BadRequestException` (`.status == 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 `ManagementApi(api_client).view_account_details()`.

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-python-v2

Start sprinting with our API docs

Get all the detail you'll ever need in our full API docs. Learn how to launch your own features or integrate with others.

Full API Reference

SMS Quickstart

On this page:

Resources:

Resources:

Resources:

Resources:

Resources:

Resources:

Resources:

Resources:

Resources:

Resources:

1. Prerequisites

2. Install

3. Configure the client

4. Send your first SMS

5. Understand the response

6. Common errors

Next steps

Before you start

Installation

Install via Cocoapods

Update Swift Version

Send your first message

The code explained

Import libraries

Authorisation

Configure your message

Create an SMS message collection

Send SMS message

1. Prerequisites

2. Install

3. Configure the client

4. Send your first SMS

5. Understand the response

6. Common errors

Next steps

1. Prerequisites

2. Install

3. Configure the client

4. Send your first SMS

5. Understand the response

6. Common errors

Next steps

Before you start

Installation

Install via Github

Send your first message

The code: explained

Import functions

Authorisation and create an instance of the API class

Configure your message

Send SMS message

1. Prerequisites

2. Install

3. Configure the client

4. Send your first SMS

5. Understand the response

6. Common errors

Next steps

1. Prerequisites

2. Install

3. Configure the client

4. Send your first SMS

5. Understand the response

6. Common errors

Next steps

1. Prerequisites

2. Install

3. Configure the client

4. Send your first SMS

5. Understand the response

6. Common errors

Next steps

Before you start

Installation

Install via Cocoapods

Send your first message

The code explained

Import modules