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 or 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 or pull it from an environment variable.
String phoneNumber = System.getenv().getOrDefault("PHONE_NUMBER", "11234567890");
  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 = "Your package has shipped! Follow your delivery at";
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. Next in the try block, display the response for debugging purposes. In your production code, you would likely remove this.
  1. In the catch block, add code to print any error that might occur.
System.out.println((char)27 + "[31m" + "\nAn exception occurred.\nERROR: " + e.getMessage());

Sample code

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