Send SMS with Node.js, Express, and Vonage

This guide provides a step-by-step walkthrough for building a simple but functional Node.js application using the Express framework to send SMS messages via the Vonage SMS API. We will create a basic API endpoint that accepts a destination phone number and a message body, then utilizes the Vonage Node.js SDK to dispatch the SMS.

This tutorial focuses specifically on sending SMS messages using the Vonage SMS API with API Key and Secret authentication, which is a straightforward method for this task.

Project Overview and Goals

Goal: To create a simple REST API endpoint using Node.js and Express that allows sending SMS messages through the Vonage platform.

Problem Solved: Provides a basic programmatic way to send SMS notifications or messages from a backend application without complex setup.

Technologies Used:

Node.js: A JavaScript runtime environment for executing server-side code.
Express: A minimal and flexible Node.js web application framework used to create the API endpoint.
Vonage Node.js SDK (@vonage/server-sdk): Simplifies interaction with the Vonage APIs.
dotenv: A module to load environment variables from a .env file, keeping sensitive credentials out of the codebase.
Vonage SMS API: The specific Vonage service used for sending SMS messages.

System Architecture:

+-------------+        +---------------------+        +-----------------+        +--------------+
| HTTP Client | -- HTTP Request --&gt; | Express Server      | -- API Call --&gt; | Vonage SMS API  | -- SMS --&gt; | User's Phone |
| (e.g. cURL, |        | (Node.js App)       |                 | (External)      |              |
|  Postman)   |        |                     |                 |                 |              |
+-------------+        +---------------------+        +-----------------+        +--------------+
    |  POST /send-sms    |  1. Receives Request                  |                 |
    |  { to, text }      |  2. Validates Input                 |                 |
    +------------------&gt; |  3. Initializes Vonage SDK          |                 |
                         |  4. Calls vonage.sms.send({to,from,text}) +-----------------&gt;
                         |  5. Handles Response/Error          |                 |
                         |  &lt;-- JSON Response -----------------+                 |
                         +-------------------------------------------------------+

Expected Outcome: A running Node.js Express server with a single POST endpoint (/send-sms). Sending a valid request to this endpoint will trigger an SMS message to the specified recipient via Vonage.

Prerequisites:

Node.js and npm (or yarn): Installed on your development machine. You can download them from nodejs.org.
Vonage API Account: Sign up for free at Vonage API Dashboard. Note the initial free credit and trial limitations.
Vonage API Key and Secret: Obtainable from your Vonage Dashboard after signing up.
Vonage Virtual Number: You need a Vonage phone number (in E.164 format_ e.g._ +14155550100) to send SMS from. You can get one in the dashboard (Numbers > Buy numbers). For trial accounts, you might need to use the number provided or purchase one if allowed.
Test Recipient Phone Number: During the trial period, Vonage requires you to whitelist recipient phone numbers. You can manage these in your dashboard (usually under Account > Test Numbers or similar). Ensure the number you want to send to is added here.
Text Editor or IDE: Such as VS Code, Sublime Text, Atom, etc.
HTTP Client (Optional but Recommended): Tools like Postman or curl for testing the API endpoint.

1. Setting up the project

Let's start by creating our project directory and installing the necessary dependencies.

Create Project Directory: Open your terminal or command prompt and create a new directory for your project. Navigate into it.
```
mkdir vonage-sms-sender
cd vonage-sms-sender
```
Initialize Node.js Project: Initialize the project using npm. The -y flag accepts default settings.
```
npm init -y
```
This creates a package.json file.
Install Dependencies: Install Express for the web server, the Vonage SDK for interacting with the API, and dotenv for managing environment variables.
```
npm install express @vonage/server-sdk dotenv
```
Your package.json dependencies section should now look similar to this (versions might vary):
```
""dependencies"": {
  ""@vonage/server-sdk"": ""^3.x.x"",
  ""dotenv"": ""^16.x.x"",
  ""express"": ""^4.x.x""
}
```
Create Core Files: Create the main application file and the environment configuration file.
- index.js: This will contain our Express server and API logic.
- .env: This file will store sensitive credentials like API keys (it should not be committed to version control).
- .gitignore: To prevent committing sensitive files (.env) and generated files (node_modules).
You can create these using your editor or via the terminal:
```
# On Linux/macOS:
touch index.js .env .gitignore

# On Windows Command Prompt:
# type nul &gt; index.js && type nul &gt; .env && type nul &gt; .gitignore
# Or use your text editor / IDE to create empty files.
```
Configure .gitignore: Add node_modules and .env to your .gitignore file to ensure they aren't tracked by Git.
```
# .gitignore

# Dependencies
node_modules/

# Environment variables
.env
```

Project Structure: Your basic project structure should now be:

vonage-sms-sender/
├── .env
├── .gitignore
├── index.js
├── package.json
├── package-lock.json
└── node_modules/

2. Configuring Vonage Credentials

Before writing code, securely store your Vonage API credentials and virtual number.

Obtain Vonage Credentials:
- Log in to your Vonage API Dashboard.
- Your API Key and API Secret are usually displayed prominently on the main dashboard page or under ""API settings"". Copy these values.
- Navigate to ""Numbers"" > ""Your numbers"". Find the Vonage virtual number you want to use as the sender (FROM_NUMBER). Copy this number (ensure it's in E.164 format, e.g., +14155552671). If you don't have one, you may need to buy one via ""Buy numbers"".
Add Credentials to .env: Open the .env file and add your credentials. Replace the placeholder values with your actual key, secret, and Vonage number.
```
# .env
# Vonage Credentials
VONAGE_API_KEY=YOUR_API_KEY
VONAGE_API_SECRET=YOUR_API_SECRET
VONAGE_VIRTUAL_NUMBER=YOUR_VONAGE_NUMBER_IN_E164_FORMAT

# Server Port (Optional)
PORT=3000
```
- VONAGE_API_KEY: Your API key from the Vonage dashboard.
- VONAGE_API_SECRET: Your API secret from the Vonage dashboard.
- VONAGE_VIRTUAL_NUMBER: The Vonage number you will send SMS from (e.g., +14155552671).
- PORT: The port your Express server will listen on (defaulting to 3000 if not set).
Whitelist Test Number (Trial Accounts): If you are using a trial account, ensure the phone number you intend to send SMS to is added to your list of approved test numbers in the Vonage dashboard. Failure to do this will result in a ""Non-Whitelisted Destination"" error. Look for sections like ""Test Numbers"" or similar under your account settings.

3. Implementing the SMS Sending Endpoint

Now, let's write the Node.js/Express code to create the server and the API endpoint.

Open index.js and add the following code:

// index.js

// 1. Import necessary modules
require('dotenv').config(); // Load environment variables from .env file
const express = require('express');
const { Vonage } = require('@vonage/server-sdk');

// 2. Initialize Express app
const app = express();
const port = process.env.PORT || 3000; // Use port from .env or default to 3000

// 3. Initialize Vonage SDK
// Ensure API Key and Secret are loaded correctly from .env
if (!process.env.VONAGE_API_KEY || !process.env.VONAGE_API_SECRET) {
  console.error('Error: Vonage API Key or Secret not found in .env file.');
  process.exit(1); // Exit if credentials are missing
}
const vonage = new Vonage({
  apiKey: process.env.VONAGE_API_KEY,
  apiSecret: process.env.VONAGE_API_SECRET
});

// 4. Add Middleware
// Enable Express to parse JSON request bodies
app.use(express.json());
// Enable Express to parse URL-encoded request bodies
app.use(express.urlencoded({ extended: true }));

// 5. Define the SMS Sending Endpoint
app.post('/send-sms', async (req, res) =&gt; {
  console.log('Received request on /send-sms:', req.body);

  // Basic input validation
  const { to, text } = req.body;
  if (!to || !text) {
    console.error('Validation Error: Missing ""to"" or ""text"" in request body.');
    return res.status(400).json({ success: false, message: 'Missing ""to"" or ""text"" parameter.' });
  }

  // Get the sender number from environment variables
  const from = process.env.VONAGE_VIRTUAL_NUMBER;
  if (!from) {
      console.error('Configuration Error: VONAGE_VIRTUAL_NUMBER not set in .env file.');
      return res.status(500).json({ success: false, message: 'Server configuration error: Sender number not set.' });
  }

  console.log(`Attempting to send SMS from ${from} to ${to}`);

  try {
    // Use vonage.sms.send() which is asynchronous and returns a promise
    const responseData = await vonage.sms.send({ to, from, text });

    // Check the response status from Vonage
    // Note: The exact structure might vary slightly; consult SDK docs if needed.
    // Typically, status '0' means success for the first message in the batch.
    if (responseData.messages[0]['status'] === '0') {
      console.log('SMS submitted successfully:', responseData.messages[0]);
      res.status(200).json({
        success: true,
        message: 'SMS submitted successfully.',
        messageId: responseData.messages[0]['message-id']
      });
    } else {
      // Log the specific error from Vonage
      const errorCode = responseData.messages[0]['status'];
      const errorText = responseData.messages[0]['error-text'];
      console.error(`Message failed with error code ${errorCode}: ${errorText}`);
      res.status(400).json({ // Use 400 Bad Request as it's often client-side (e.g., invalid number, permissions)
        success: false,
        message: `Failed to send SMS. Vonage Error: ${errorText}`,
        errorCode: errorCode
      });
    }
  } catch (error) {
    // Handle SDK or network errors
    console.error('Error sending SMS:', error);
    res.status(500).json({
      success: false,
      message: 'An unexpected error occurred while sending the SMS.',
      error: error.message // Include specific error message for debugging
    });
  }
});

// 6. Basic Root Route (Optional)
app.get('/', (req, res) =&gt; {
  res.send('Vonage SMS Sender API is running!');
});

// 7. Start the Server
app.listen(port, () =&gt; {
  console.log(`Server listening at http://localhost:${port}`);
});

Code Explanation:

Imports: We import dotenv to load variables, express to create the server, and the Vonage class from the SDK.
Express Init: We create an Express application instance and determine the port.
Vonage Init: We instantiate the Vonage SDK using the apiKey and apiSecret loaded from .env. Basic checks ensure these environment variables are present.
Middleware: express.json() and express.urlencoded() are essential middleware functions that parse incoming request bodies, making req.body available in our route handler.
/send-sms Endpoint:
- Defines a POST route at /send-sms.
- Performs basic validation to ensure to (recipient number) and text (message content) are present in the request body.
- Retrieves the from number (your Vonage virtual number) from environment variables.
- Uses an async/await structure with a try...catch block for cleaner asynchronous code handling and error management.
- Calls vonage.sms.send({ to, from, text }). Note: We use the send method of the vonage.sms object here, passing the required parameters (to, from, text). This method is suitable for API Key/Secret authentication. This method is asynchronous and returns a promise.
- Checks the status field in the response from Vonage. A status of '0' indicates successful submission.
- Sends a JSON response back to the client indicating success (200 OK) or failure (400 Bad Request for Vonage errors, 500 Internal Server Error for SDK/network errors). Includes relevant details like message ID or error text.
Root Route: A simple GET route at / to confirm the server is running.
Server Start: Starts the Express server, listening on the specified port.

4. Basic Error Handling and Logging

The code above includes basic error handling:

Input Validation: Checks for missing to and text parameters, returning a 400 Bad Request.
Configuration Check: Checks for missing Vonage credentials and sender number, returning 500 Internal Server Error or exiting.
Vonage API Errors: Catches errors reported by the Vonage API (e.g., invalid number, insufficient funds, whitelisting issues) by checking responseData.messages[0]['status'] and returns a 400 Bad Request with the Vonage error message.
SDK/Network Errors: Uses a try...catch block to handle exceptions during the API call (e.g., network timeouts, SDK issues) and returns a 500 Internal Server Error.
Logging: Uses console.log and console.error to output information about requests, successful submissions, and errors to the server console. For production, consider using a more robust logging library (like Winston or Pino).

5. Testing the API Endpoint

Now, let's run the server and test the endpoint.

Run the Server: Open your terminal in the project directory (vonage-sms-sender) and run:
```
node index.js
```
You should see the output: Server listening at http://localhost:3000
Test with curl: Open another terminal window and use curl to send a POST request. Replace +12345678900 with the whitelisted recipient phone number (in E.164 format) and customize the message text.
```
curl -X POST http://localhost:3000/send-sms \
-H ""Content-Type: application/json"" \
-d '{
  ""to"": ""+12345678900"",
  ""text"": ""Hello from Node.js and Vonage!""
}'
```
Test with Postman (Alternative):
- Open Postman.
- Create a new request.
- Set the method to POST.
- Enter the URL: http://localhost:3000/send-sms
- Go to the ""Body"" tab, select ""raw"", and choose ""JSON"" from the dropdown.
- Enter the JSON payload:
```
{
  ""to"": ""+12345678900"",
  ""text"": ""Hello from Node.js and Vonage via Postman!""
}
```
- Click ""Send"".

Expected Responses:

Success: You should receive the SMS on the recipient phone shortly. The API will respond with:
```
{
  ""success"": true,
  ""message"": ""SMS submitted successfully."",
  ""messageId"": ""SOME_MESSAGE_ID_FROM_VONAGE""
}
```
Your server console will show logs indicating the request and successful submission.

Validation Error (Missing Field):

{
  ""success"": false,
  ""message"": ""Missing \""to\"" or \""text\"" parameter.""
}

Vonage Error (e.g., Non-Whitelisted Number):

{
    ""success"": false,
    ""message"": ""Failed to send SMS. Vonage Error: Non White-listed Destination - rejected"",
    ""errorCode"": ""15""
}

Check your server console logs for more detailed error information.

Server Error (e.g., Bad Credentials):

{
    ""success"": false,
    ""message"": ""An unexpected error occurred while sending the SMS."",
    ""error"": ""Authentication failed""
}

6. Security Considerations (Basic)

Credential Management: Never commit your .env file or hardcode API keys/secrets directly in your source code. Use environment variables for all sensitive data. Ensure .env is listed in your .gitignore.
Input Validation: The current validation is minimal. In a production application, you should implement more robust validation:
- Check if the to number is a valid phone number format (e.g., using a library like libphonenumber-js).
- Sanitize the text input to prevent potential injection attacks if the text is ever displayed elsewhere (though less critical for SMS sending itself).
- Limit the length of the text message.
Rate Limiting: To prevent abuse (intentional or accidental), implement rate limiting on your API endpoint. Libraries like express-rate-limit can easily add this functionality.
Authentication/Authorization: This basic example has no authentication. In a real application, you would secure this endpoint so only authorized users or systems can trigger SMS messages. This could involve API keys, JWT tokens, or other authentication strategies.

7. Troubleshooting and Caveats

Non White-listed Destination Error (Status Code 15): This is the most common issue for trial accounts. Ensure the recipient number (to) is added to your Test Numbers list in the Vonage Dashboard.
Invalid Credentials Error (Status Code might vary, e.g., 1, 2, 4, 5, or SDK-level auth errors): Double-check that VONAGE_API_KEY and VONAGE_API_SECRET in your .env file are correct and that the .env file is being loaded (check for typos, ensure require('dotenv').config() is called early). The specific error code returned by Vonage might differ based on the exact issue.
Invalid Sender Number: Ensure VONAGE_VIRTUAL_NUMBER is a valid number associated with your Vonage account and is in the correct E.164 format.
Incorrect Phone Number Format: Both from and to numbers should ideally be in E.164 format (e.g., +14155552671).
Insufficient Funds (Status Code 9): If you've used your trial credit or are on a paid account, ensure you have enough balance.
Network Issues: Ensure your server has outbound internet connectivity to reach the Vonage API endpoints.
SDK Version Compatibility: While usually stable, major SDK updates could introduce breaking changes. Refer to the @vonage/server-sdk documentation if you encounter unexpected behavior after updates.
SMS API vs. Messages API: This guide uses the simpler SMS API (vonage.sms.send). Vonage also offers a more versatile Messages API (vonage.messages.send) which handles multiple channels (SMS, MMS, WhatsApp, etc.) but uses Application ID and Private Key authentication, requiring different setup steps (creating a Vonage Application, generating keys). Choose the API that best suits your needs.

8. Deployment (Conceptual)

Deploying this application involves hosting it on a server or platform-as-a-service (PaaS) and managing environment variables securely.

Hosting Options: Heroku, Vercel, AWS (EC2, Lambda, Elastic Beanstalk), Google Cloud Platform, Azure App Service, DigitalOcean App Platform.
Environment Variables: Do not upload your .env file. All hosting platforms provide a secure way to configure environment variables for your deployed application (e.g., Heroku Config Vars, Vercel Environment Variables). Configure VONAGE_API_KEY, VONAGE_API_SECRET, VONAGE_VIRTUAL_NUMBER, and PORT in your chosen platform's settings.

package.json Scripts: Add a start script to your package.json if you don't have one, which hosting platforms often use:

""scripts"": {
  ""start"": ""node index.js"",
  ""test"": ""echo \""Error: no test specified\"" && exit 1""
},

Procfile (Heroku): If deploying to Heroku, you might need a Procfile:
```
web: node index.js
```

Detailed deployment instructions vary significantly between platforms. Consult the documentation for your chosen hosting provider.

9. Verification and Testing

Server Starts: Run node index.js. Does the server start without errors and log the listening message?
Endpoint Accessible: Can you reach http://localhost:3000/ in a browser or via curl?
POST Request Accepted: Does the /send-sms endpoint accept POST requests?
Valid Request - Success: Send a valid request with a whitelisted number.
- Do you get a 200 OK response with success: true and a messageId?
- Do you receive the SMS on the target device?
- Does the server log show the request and successful submission?
Invalid Request - Missing Field: Send a request without to or text. Do you get a 400 Bad Request with the correct error message?
Invalid Request - Non-Whitelisted Number: Send a request to a non-whitelisted number (on a trial account). Do you get a 400 Bad Request indicating the whitelisting error (Non White-listed Destination)?
Error Handling - Bad Credentials: Temporarily put incorrect values in .env and restart. Does the server fail to start or does the API call return an authentication error (e.g., 401 Unauthorized or similar in the 500 response)? Remember to restore correct credentials afterward.

Conclusion

You have successfully built a basic Node.js Express application capable of sending SMS messages using the Vonage SMS API. This involved setting up the project, managing API credentials securely, implementing an API endpoint using the Vonage Node.js SDK, performing basic error handling, and testing the functionality.

Next Steps:

Receiving SMS: Explore handling inbound SMS messages using Vonage webhooks (requires setting up webhook URLs in Vonage and potentially using ngrok for local development).
Robust Error Handling/Logging: Integrate a dedicated logging library (e.g., Winston) and implement more specific error handling and potentially retry mechanisms for transient network issues.
Input Validation: Add stricter validation for phone numbers and message content.
Use the Messages API: If you need multi-channel support (MMS, WhatsApp) or prefer Application ID/Private Key authentication, adapt the code to use vonage.messages.send().
Add Authentication: Secure your API endpoint.
Build a Frontend: Create a user interface to interact with this API.
Deployment: Deploy the application to a hosting provider.

This foundation provides a starting point for integrating SMS capabilities into your Node.js applications.