SMS Quickstart Guide for Java

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

Products

Developers

Resources

SMS Quickstart

On this page:

Resources: