How to Send SMS Messages with Java and the Vonage API

This article was updated in April 2025

The Vonage SMS API is a service that allows you to send and receive SMS messages. If you’re a Java developer, you can use the Vonage API to send SMS messages from Java applications.

In this tutorial, we'll show you how to send SMS messages with Java using the Vonage API.

Prerequisites

Using Java to send SMS messages is relatively simple. Once you have the Vonage SMS API, it only requires a few additional tools and a working knowledge of Java.

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

You'll also need the following:

• JDK (17 or higher) or its open-source equivalent OpenJDK

• Gradle

Instructions

Below, we’ll walk you through each of the steps you need to take to send an SMS message in Java with the Vonage API.

1. Create your Java application

2. Configure the Vonage Java SDK

3. Send your SMS message in Java

1. Create Your Java Application

To begin, set up your Gradle project and download the Vonage Java SDK.

Create a directory for your project. Go inside your directory and run gradle init. If you're unfamiliar with Gradle, fret not - we won't be delving into anything overly complex!

Select 1: basic as the type of project to generate. 1: Groovy as build script DSL. At this point, name your project—or press Enter for the default option.

Once that's complete, open the build.gradle file. Then, replace the contents of the file with the following code snippet:

// We're creating a Java Application:
    plugins {
        id 'application'
        id 'java'
    }
    
    // Download dependencies from Maven Central:
    repositories {
        mavenCentral()
    }
    
    // Install the Vonage Java SDK
    dependencies {
        implementation 'com.vonage:client:7.7.0'
    }
    
    // We'll create this class to contain our code:
    application {
        mainClass = 'getstarted.SendSMS'
    }

Next, open your console in the directory that contains your build.gradle file. Then, run the following command:

gradle build

This command will download the Vonage Java SDK and store it for later. If you had any source code, it would also compile that—but you haven't written any yet. Let's fix that!

2. Configure the Vonage Java SDK

Because of the mainClass we set in the Gradle build file, you're going to need to create a class called SendSMS in the package getstarted.

(Note: In production code, you'd want the package to be something like com.mycoolcompany.smstool, but this isn't production code, so getstarted will do.)

Gradle uses the same directory structure as Maven, so you need to create the following directory structure inside your project directory: src/main/java/getstarted.

On macOS and Linux, you can create this path by running:

mkdir -p src/main/java/getstarted

Inside the getstarted directory, create a file called SendSMS.java. Once you have it opened in your favorite IDE, add this code:

package getstarted;

import com.vonage.client.VonageClient;
import com.vonage.client.sms.MessageStatus;
import com.vonage.client.sms.SmsSubmissionResponse;
import com.vonage.client.sms.messages.TextMessage;

static String API_KEY = "YOUR_API_KEY";
static String API_SECRET = "YOUR_API_SECRET";

public class SendSMS {

    public static void main(String[] args) throws Exception {
    // Our code will go here!
    }
}

This imports the necessary parts of the Vonage SDK and creates a method for our code.

We then store our API Key and API secret as variables. Fill in YOUR_API_KEY and YOUR_API_SECRET with the values you copied from the Vonage API Dashboard.

If you run gradle run, it should run your main method. However, since we don't have anything there yet, it won't do anything. Let's change that!

3. Send Your SMS Message in Java

Now, we’re almost ready to send an SMS message with our Java application!

First, add this snippet to your main method:

VonageClient client = VonageClient.builder()
    
    .apiKey(YOUR_API_KEY)
    .apiSecret(YOUR_API_SECRET)
    .build();

The following code creates a VonageClient object that can be used to send SMS messages. Now that your client object is configured, you can send an SMS message:

TextMessage message = new TextMessage(VONAGE_BRAND_NAME,
                    TO_NUMBER,
                    "A text message sent using the Vonage SMS API"
            );
    
            SmsSubmissionResponse response = client.getSmsClient().submitMessage(message);
    
            if (response.getMessages().get(0).getStatus() == MessageStatus.OK) {
                System.out.println("Message sent successfully. " + response.getMessages());
            } else {
                System.out.println("Message failed with error: " + response.getMessages().get(0).getErrorText());
            }

Again, you'll want to replace VONAGE_BRAND_NAME with the virtual number you purchased and TO_NUMBER with your own mobile phone number. They should both be written as strings. Make sure to provide the TO_NUMBER in E.164 format—for example, 447401234567.

Finally, save and run gradle run. If you’ve followed the steps in this tutorial correctly, this will send an SMS message from Java using the Vonage SMS API.

At this point, you should see something like this:

Message sent successfully.[com.vonage.client.sms.SmsSubmissionResponseMessage@f0f0675[to=447401234567,id=13000001CA6CCC59,status=OK,remainingBalance=27.16903818,messagePrice=0.03330000,network=23420,errorText=<null>,clientRef=<null>]]

...and a text message sent to your phone!

If it didn't work, there may be some text after ERR:. Correct the issue and try again.

NOTE

In some countries (US), VONAGE_BRAND_NAME has to be one of your Vonage virtual numbers. In other countries (UK), you're free to pick an alphanumeric string value—for example, your brand name like AcmeInc. Read about country-specific SMS features on the dev portal.

Conclusion

You now know how to send an SMS in Java using Vonage's API! For further information, please refer to the documentation links provided below.

Further Reading

• General information about the SMS API

• SMS API Documentation

• Send an SMS Documentation