Java SDK

The official Java SDK for Sendexa. One package, one client, every API — SMS, OTP, WhatsApp, Email, Voice, and Webhook verification.

Minimal Dependencies

One dependency — jackson-databind for JSON. Uses Java 11 built-in HttpClient for networking.

Framework Agnostic

Works in Spring Boot, Quarkus, Micronaut, Jakarta EE, and plain Java 11+.

Thread-Safe

One client instance per application — safe for concurrent use across threads.

Fluent Builder API

Immutable request objects with compile-time safety and IDE auto-complete.

Installation

XML

<dependency>
  <groupId>co.sendexa</groupId>
  <artifactId>sdk</artifactId>
  <version>0.1.0</version>
</dependency>

Requirements

Java 11 or later. Uses java.net.http.HttpClient (built-in since Java 11) and jackson-databind for JSON serialisation.

Initialise the Client

Create one client at startup (e.g. as a Spring bean) and reuse it — it is thread-safe and manages its own connection pool.

Java

import co.sendexa.sdk.Sendexa;

Sendexa client = Sendexa.builder()
    .apiKey(System.getenv("SENDEXA_API_KEY"))
    .apiSecret(System.getenv("SENDEXA_API_SECRET"))
    .build();

API Examples

Send single and bulk SMS messages with delivery tracking.

Java

import co.sendexa.sdk.resources.SmsResource;

// Send a single SMS
SmsResource.SendResponse resp = client.sms().send(
    SmsResource.SendRequest.builder()
        .to("0244123456")
        .from("MyBrand")
        .message("Your order #1234 has been confirmed!")
        .build()
);
System.out.println(resp.data.messageId + " " + resp.data.status);

// Send bulk SMS
client.sms().sendBulk(
    SmsResource.SendBulkRequest.builder()
        .from("MyBrand")
        .message("Hello from MyBrand!")     // shared fallback
        .messages(List.of(
            new SmsResource.BulkMessage("0244123456", "Hi Alice!"),
            new SmsResource.BulkMessage("0555987654")  // uses shared message
        ))
        .build()
);

// Check delivery status
SmsResource.SendResponse status = client.sms().getStatus(resp.data.messageId);
System.out.println(status.data.status); // "delivered"

// Resend a failed message
client.sms().resend(resp.data.messageId);

Error Handling

All API errors throw a SendexaException (unchecked) with structured fields for easy branching.

Java

import co.sendexa.sdk.SendexaException;

try {
    client.sms().send(
        SmsResource.SendRequest.builder()
            .to("0244123456").from("MyBrand").message("Hi!").build()
    );
} catch (SendexaException e) {
    System.out.println(e.getStatus());     // HTTP status  e.g. 403
    System.out.println(e.getCode());       // API code     e.g. "SENDER_ID_NOT_APPROVED"
    System.out.println(e.getMessage());    // Human text   e.g. "Sender ID not approved"
    System.out.println(e.getRequestId()); // Trace ID for Sendexa support
}

Method	Return type	Description
getStatus()	int	HTTP status code (400, 401, 403, 429…)
getCode()	String	Machine-readable error code from the API
getMessage()	String	Human-readable description of the error
getRequestId()	String	Sendexa trace ID — include when contacting support
getRaw()	Map<String,Object>	Full raw error payload from the API

Best Practices

Register Sendexa as a singleton bean in Spring / Quarkus — do not instantiate per request
Store credentials in environment variables or a secrets manager, never in source code
Always call client.webhooks().verify() before processing any webhook event
Catch SendexaException separately from Exception so you can branch on getCode()
Use .timeoutMs() on the builder to override the default 30 s timeout