SMS - Tutorial: Send an SMS in Java using the Telesign SDK

This tutorial teaches you how to use the Telesign Java SDK to send an SMS. The complete sample code for this tutorial is available on GitHub here.

Before you begin

Make sure you have the following before you start:

  • Authentication credentials: Your Customer ID and API Key. If you need help finding these items, go to the support article How do I find my Customer ID and API Key.
  • Testing device: A mobile phone on which you can receive SMS.
  • Gradle: This package manager isn't required to use the SDK, but it is required for this tutorial.



This tutorial uses the following:

  • MacOS
  • Java OpenJDK v19.0.2
  • Gradle 8.0.2

Please modify accordingly if your developer environment differs from these details.

Set up your project

  1. Follow the Telesign Self-service Java SDK install instructions on GitHub here, incorporating the following details:
  • Use sms as the project directory name.
  • Use JUnit 4 as the test framework.
  • Use sendSMS as the project name.
  • Use sendSMS as the source package name.

You should end up in the top-level directory (sms) for your project in the Terminal. This directory should contain an initialized Gradle project with the Telesign Self-service SDK included in its dependencies.

  1. From the top level of your project, delete the folder app/src/test/. No tests are included in this tutorial.
rm -r app/src/test/

Create code to send an SMS

  1. Open the file "app/src/main/java/sendSMS/".
  2. Add the imports below between the package declaration and the App class declaration:
import com.telesign.RestClient;
import com.telesign.MessagingClient;

These imports reference selected functionality from the Telesign self-service SDK.

  1. Replace the contents of the default App class with the following basic structure.
public class App {
    public static void main(String[] args) {


In the next step, you will begin adding statements to the main function in the App class.

  1. Define variables in the main function to store your authentication credentials. For testing purposes, you can just overwrite the default values below rather than use environment variables.
String customerId = System.getenv().getOrDefault("CUSTOMER_ID", "FFFFFFFF-EEEE-DDDD-1234-AB1234567890");
String apiKey = System.getenv().getOrDefault("API_KEY", "ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==");
  1. Define a variable to hold the recipient's phone number. For this tutorial, hardcode your testing device's phone number.
String phoneNumber = System.getenv().getOrDefault("PHONE_NUMBER", "1234567890");
  1. Define variables for the message text and the Telesign abbreviation describing the message type. For purposes of this tutorial, use the "ARN" abbreviation (alerts, reminders, and notifications).
String message = "Hello world";
String messageType = "ARN";
  1. Create a try-catch structure.
try {

} catch (Exception e) {
  1. In the try block, add code to instantiate a Telesign messaging client object with your authentication credentials.
MessagingClient messagingClient = new MessagingClient(customerId, apiKey);
  1. Next in the try block, make the request and capture the response.
RestClient.TelesignResponse telesignResponse = messagingClient.message(phoneNumber, message, messageType, null);
  1. In the catch block, add code to print any error that might occur.
  1. Display the HTTP status code and body of the response in the console for debugging purposes. In your production code, you would likely remove this.

Sample code

The complete sample code for this tutorial can be found on GitHub.