SMS Quickstart Guide for Python

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

Products

Developers

Resources

SMS Quickstart

On this page:

Resources: