In Context

The next-generation communications blog from Nexmo

< Back

How to Send SMS Messages with Java

May 3, 2017 Published by

This is the first in a series of “Getting Started with Nexmo and Java” tutorials.

The Nexmo SMS API is a service that allows you to send and receive SMS messages anywhere in the world. Nexmo provides REST APIs, but it’s much easier to use the Java client library we’ve written for you.

In this tutorial we’ll cover how to send SMS messages with Java!

View the source code on GitHub


Before starting, there are a few things you’re going to need to have installed on your development machine. Hopefully you already have a basic understanding of Java programming – we’re not going to be doing any very complicated programming, but it’ll help you to get up and running. As well as a basic understanding of Java, you’ll also need:

Getting Your API Keys

First, sign up for a Nexmo account. Then go to the Dashboard, buy a phone number from Numbers and download your API keys from the Settings page.

Buy a phone number

Using the Nexmo Client Library for Java

Now we’re going to set up your Gradle project and download the Nexmo Client Library for Java.

First, create a directory to contain your project. Inside this directory, run gradle init. If you haven’t used Gradle before, don’t worry – we’re not going to do anything too complicated! Open the file build.gradle and change the contents to the following:

Now, if you open your console in the directory that contains this build.gradle file, you can run:

This command will download the Nexmo client library and store it for later. If you had any source code, it would also compile that – but you haven’t written any yet – so let’s fix that!

Because of the mainClassName we set in your Gradle build file, you’re going to need to create a class called SendSMS in the package getstarted. 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’re going to 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:

Inside the getstarted directory, create a file called, open it in your favourite text editor, and we’ll start with some boiler-plate code:

All this does is import the necessary parts of the Nexmo client library, and create a method to contain our code. It’s worth running gradle run now, which should run your main method. It won’t do anything yet, but this is where we get to the interesting bit.

Send SMS Messages with Java

Put the following in your main method:

Fill in API_KEY and API_SECRET with the values you copied from the Nexmo Dashboard. This code creates a NexmoClient object that can be used to send SMS messages. You will need to provide other AuthMethods to be able to make voice calls, but I’ll cover that in another blog post. Now we have a configured client object, we can send an SMS message:

Again, you’ll want to replace FROM_NUMBER and TO_NUMBER with strings containing the Nexmo number you bought, and your own mobile phone number. Once you’ve done that, save and run gradle run again. You should see something like this printed to the screen:

SMS-SUBMIT-RESULT -- STATUS:0 ERR:null DEST:4412341234 MSG-ID:0C0000002D9C9A89 CLIENT-REF:null PRICE:0.0333000

… and you should receive a text message! If it didn’t work, check out if something was printed after ERR: in the line above, and maybe wait a few more seconds for the message to appear.

So you just learned how to send an SMS message with Nexmo! You can either stop there, or for bonus points, we can build a Web service around it, which will be useful in the next post where we’ll be writing a webhook to receieve SMS messages sent to your Nexmo number.

Building a Web Service to Send SMS

We’re going to build a tiny HTTP service and then test it with Postman. Fortunately Gradle makes this quite easy. Open your build.gradle and add the following to the top:

The first line tells Gradle it should build a war file, using source files in src/main/java and src/main/webapp. The second line adds the ability to fire up your webapp straight from Gradle using the Jetty servlet container!

I’m going to suggest you run gradle appRun now (note that you use appRun and not run to run the web server!) It’ll take a while the first time, while it downloads some dependencies.

Eventually, you should see something like this:

This means Jetty is now running your (empty) web service. Fire up the URL you see, to check it’s running OK. It should look a bit like this:

Empty web page

Now let’s write a servlet! Create a file called src/main/java/getstarted/ It’s going to look similar to our last class:

And then we need to configure the servlet in our servlet container by creating the following at src/main/webapp/WEB-INF/web.xml:

Replace the placeholders with your own values, and then run gradle appRun. If everything builds correctly, let’s fire up Postman and make a POST request, like this:

Making a request with Postman

I hope it worked! So now you’ve built a REST Web service for sending SMS messages! In reality, there’s lots more things you’d want to do before deploying this, like adding authentication (otherwise anyone could send a message using your Nexmo account!), a nice Web form for posting to the service, and improving the error handling – but this is a good start!

So far we’ve learned how to send SMS messages with Java. In the next post, we’ll extend this service to receive SMS messages sent to your Nexmo number.


Nexmo Logo

Tags: ,

Categorised in: , , ,

This post was written by