Java SDK

The Java SDK provides blocking and CompletableFuture clients for Torpedo’s email and SMS API.

Install

<dependency>
  <groupId>mz.co.torpedo</groupId>
  <artifactId>torpedo-java</artifactId>
  <version>0.2.0</version>
</dependency>

implementation("mz.co.torpedo:torpedo-java:0.2.0")

Java 17 or newer is required.

Create a client

import mz.co.torpedo.TorpedoClient;

var torpedo = TorpedoClient.builder()
    .apiKey(System.getenv("TORPEDO_API_KEY"))
    .build();

Create one client and reuse it. Clients and resource objects are thread-safe.

Send email

import mz.co.torpedo.models.SendEmailRequest;

var email = torpedo.emails().send(
    SendEmailRequest.builder()
        .from("Acme <hello@myapp.com>")
        .to("user@example.com")
        .subject("Welcome")
        .html("<h1>Welcome!</h1>")
        .text("Welcome!")
        .build()
);

System.out.println(email.id());

Send a batch

import mz.co.torpedo.models.SendEmailBatchRequest;

var queued = torpedo.emails().sendBatch(
    SendEmailBatchRequest.builder()
        .addEmail(firstEmail)
        .addEmail(secondEmail)
        .idempotencyKey("customer-import-2026-07-31")
        .build()
);

Send SMS

import mz.co.torpedo.models.SendSmsRequest;

var sms = torpedo.sms().send(
    SendSmsRequest.builder()
        .to("+258841234567")
        .body("Your code is 482910.")
        .build()
);

If your workspace has an approved sender ID, pass it with .from(...). It must match exactly, including capitalization:

var sms = torpedo.sms().send(
    SendSmsRequest.builder()
        .to("+258841234567")
        .from("AcmePay")
        .body("Your AcmePay code is 482910.")
        .build()
);

Omit from to use your default sender ID. See Sender ID for the full rules.

Verify a phone number

Send a one-time code over WhatsApp, then check what the user types:

import mz.co.torpedo.models.StartVerificationRequest;

var verification = torpedo.verify().start(
    StartVerificationRequest.builder()
        .to("+258841234567")
        .fallbackToSms()
        .build()
);

var result = torpedo.verify().check(verification.id(), "482910");

if (result.valid()) {
  // the number is verified
}

torpedo.verify() also has resend(id, channel), report(id), cancel(id), get(id) and list(ListVerificationsOptions). See Verify phone numbers on WhatsApp.

Async calls

import mz.co.torpedo.TorpedoAsyncClient;

var asyncTorpedo = TorpedoAsyncClient.builder()
    .apiKey(System.getenv("TORPEDO_API_KEY"))
    .build();

asyncTorpedo.emails().send(request)
    .thenAccept(message -> System.out.println(message.id()));

Cancelling the returned future cancels the active HTTP request and prevents later retries.

Pagination

var page = torpedo.emails().list(
    ListOptions.builder().limit(25).build()
);

if (page.meta().hasMore()) {
  var next = torpedo.emails().list(
      ListOptions.builder()
          .cursor(page.meta().nextCursor().orElseThrow())
          .limit(25)
          .build()
  );
}

Errors and retries

try {
  torpedo.emails().send(request);
} catch (TorpedoApiException error) {
  System.err.println(error.statusCode());
  error.errors().forEach(item ->
      System.err.println(item.code() + ": " + item.message()));
}

The SDK retries network errors, 429, and 5xx responses three times by default. Every send has one idempotency key that is reused across retry attempts. Configure .timeout(Duration) and .maxRetries(int) on the client builder.

Verify webhooks

boolean valid = WebhookVerifier.verify(rawRequestBody, signingSecret, signatureHeader);

Always pass the raw request bytes before JSON parsing.

Getting started

SDKs

Email

SMS

WhatsApp

Install

Create a client

Send email

Send a batch

Send SMS

Verify a phone number

Async calls

Errors and retries

Verify webhooks

​Install

​Create a client

​Send email

​Send a batch

​Send SMS

​Verify a phone number

​Async calls

​Pagination

​Errors and retries

​Verify webhooks

Install

Create a client

Send email

Send a batch

Send SMS

Verify a phone number

Async calls

Pagination

Errors and retries

Verify webhooks