SMS API

Nexmo's SMS API enables you to send and receive text messages to and from users worldwide, using simple REST APIs.

  • Programmatically send and receive high volumes of SMS globally.
  • Send SMS with low latency and high delivery rates.
  • Receive SMS using local numbers.
  • Scale your applications with familiar web technologies.
  • Pay only for what you use, nothing more.

Getting Started

Send an SMS

This example shows you how to send an SMS to your chosen number.

First, sign up for a Nexmo account if you don't already have one, and make a note of your API key and secret on the dashboard getting started page.

Replace the following placeholder values in the sample code:

Key Description
NEXMO_API_KEY Your Nexmo API key.
NEXMO_API_SECRET Your Nexmo API secret.

Write the code

Add the following to send-sms.sh:

Copy to Clipboard
curl -X "POST" "https://rest.nexmo.com/sms/json" \
  -d "from=AcmeInc" \
  -d "text=A text message sent using the Nexmo SMS API" \
  -d "to=$TO_NUMBER" \
  -d "api_key=$NEXMO_API_KEY" \
  -d "api_secret=$NEXMO_API_SECRET"

View full source

Run your code

Save this file to your machine and run it:

sh send-sms.sh

Prerequisites

Install dependencies

npm install nexmo
Initialize your dependencies

Create a file named send.js and add the following code:

Copy to Clipboard
const Nexmo = require('nexmo')

const nexmo = new Nexmo({
  apiKey: NEXMO_API_KEY,
  apiSecret: NEXMO_API_SECRET
})

View full source

Write the code

Add the following to send.js:

Copy to Clipboard
const from = FROM_NUMBER
const to = TO_NUMBER
const text = 'A text message sent using the Nexmo SMS API'

nexmo.message.sendSms(from, to, text, (err, responseData) => {
    if (err) {
        console.log(err);
    } else {
        if(responseData.messages[0]['status'] === "0") {
            console.log("Message sent successfully.");
        } else {
            console.log(`Message failed with error: ${responseData.messages[0]['error-text']}`);
        }
    }
})

View full source

Run your code

Save this file to your machine and run it:

node send.js

Prerequisites

Install dependencies

Add the following to build.gradle:

compile 'com.nexmo:client:5.1.0'
Initialize your dependencies

Create a class named SendMessage and add the following code to the main method:

Copy to Clipboard
NexmoClient client = NexmoClient.builder().apiKey(NEXMO_API_KEY).apiSecret(NEXMO_API_SECRET).build();

View full source

Write the code

Add the following to the main method of the SendMessage class:

Copy to Clipboard
TextMessage message = new TextMessage(NEXMO_BRAND_NAME,
        TO_NUMBER,
        "A text message sent using the Nexmo SMS API"
);

SmsSubmissionResponse response = client.getSmsClient().submitMessage(message);

if (response.getMessages().get(0).getStatus() == MessageStatus.OK) {
    System.out.println("Message sent successfully.");
} else {
    System.out.println("Message failed with error: " + response.getMessages().get(0).getErrorText());
}

View full source

Run your code

We can use the application plugin for Gradle to simplify the running of our application. Update your build.gradle with the following:

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Run the following gradle command to execute your application, replacing com.nexmo.quickstart.sms with the package containing SendMessage:

gradle run -Pmain=com.nexmo.quickstart.sms.SendMessage

Prerequisites

Install dependencies

Install-Package Nexmo.Csharp.Client
Initialize your dependencies

Create a file named SMSSender.cs and add the following code:

Copy to Clipboard
const string API_KEY = "NEXMO_API_KEY";
const string API_SECRET = "NEXMO_API_SECRET";

var client = new Client(creds: new Nexmo.Api.Request.Credentials(
    nexmoApiKey: API_KEY, nexmoApiSecret: API_SECRET));

View full source

Write the code

Add the following to SMSSender.cs:

Copy to Clipboard
var results = client.SMS.Send(new SMS.SMSRequest
{
    from = NEXMO_BRAND_NAME,
    to = TO_NUMBER,
    text = message
});

View full source

Prerequisites

Install dependencies

composer require nexmo/client
Initialize your dependencies

Create a file named send-sms.php and add the following code:

Copy to Clipboard
$basic  = new \Nexmo\Client\Credentials\Basic(NEXMO_API_KEY, NEXMO_API_SECRET);
$client = new \Nexmo\Client($basic);

View full source

Write the code

Add the following to send-sms.php:

Copy to Clipboard
try {
    $message = $client->message()->send([
        'to' => TO_NUMBER,
        'from' => 'Acme Inc',
        'text' => 'A text message sent using the Nexmo SMS API'
    ]);
    $response = $message->getResponseData();

    if($response['messages'][0]['status'] == 0) {
        echo "The message was sent successfully\n";
    } else {
        echo "The message failed with status: " . $response['messages'][0]['status'] . "\n";
    }
} catch (Exception $e) {
    echo "The message was not sent. Error: " . $e->getMessage() . "\n";
}

View full source

Run your code

Save this file to your machine and run it:

php send-sms.php

Prerequisites

Install dependencies

pip install nexmo
Initialize your dependencies

Create a file named send-an-sms.py and add the following code:

Copy to Clipboard
import nexmo

client = nexmo.Client(key=NEXMO_API_KEY, secret=NEXMO_API_SECRET)

View full source

Write the code

Add the following to send-an-sms.py:

Copy to Clipboard
responseData = client.send_message(
    {
        "from": "Acme Inc",
        "to": TO_NUMBER,
        "text": "A text message sent using the Nexmo SMS API",
    }
)

if responseData["messages"][0]["status"] == "0":
    print("Message sent successfully.")
else:
    print(f"Message failed with error: {responseData['messages'][0]['error-text']}")

View full source

Run your code

Save this file to your machine and run it:

python send-an-sms.py

Prerequisites

Install dependencies

gem install nexmo
Initialize your dependencies

Create a file named send.rb and add the following code:

Copy to Clipboard
client = Nexmo::Client.new(
  api_key: NEXMO_API_KEY,
  api_secret: NEXMO_API_SECRET
)

View full source

Write the code

Add the following to send.rb:

Copy to Clipboard
client.sms.send(
  from: 'Acme Inc',
  to: TO_NUMBER,
  text: 'A text message sent using the Nexmo SMS API'
)

View full source

Run your code

Save this file to your machine and run it:

ruby send.rb

Contents

The rest of this document contains the following information:

Concepts

Before using the Nexmo SMS API, familiarize yourself with the following:

  • Number format - The SMS API requires phone numbers in E.164 format.

  • Authentication - The SMS API authenticates using your account API key and secret.

  • Webhooks - The SMS API makes HTTP requests to your application web server so that you can act upon them. For example: inbound SMS and delivery receipts.

Guides

Code Snippets

Use Cases

Reference