Send SMS with Node.js, Express, and Vonage Messages API

This guide provides a complete walkthrough for building a Node.js application using the Express framework to send SMS messages via the Vonage Messages API. We'll cover everything from project setup and configuration to sending your first message and handling potential issues.

By the end of this tutorial, you'll have a functional Express API endpoint capable of accepting a phone number and message content, then using Vonage to deliver that message as an SMS.

Project Overview and Goals

What We're Building: A simple REST API endpoint built with Node.js and Express. This endpoint will accept POST requests containing a recipient phone number and a message text, and it will use the Vonage Messages API to send the SMS.

Problem Solved: This provides a programmatic way to send SMS messages, essential for applications needing notifications, alerts, verification codes, or direct user communication via SMS.

Technologies Used:

• Node.js: A JavaScript runtime environment for building server-side applications. Chosen for its asynchronous nature, large ecosystem (npm), and popularity.
• Express: A minimal and flexible Node.js web application framework. Chosen for its simplicity in setting up API endpoints and handling HTTP requests.
• Vonage Messages API: A unified API from Vonage for sending messages across various channels (SMS, MMS, WhatsApp, etc.). Chosen for its versatility and robust delivery features. We'll specifically use its SMS capability.
• Vonage Node.js SDK (@vonage/server-sdk): Simplifies interaction with the Vonage APIs within a Node.js environment.
• dotenv: A module to load environment variables from a .env file into process.env, keeping sensitive credentials out of source code.

System Architecture:

The flow is straightforward:

1. A client (like Postman, cURL, or another application) sends a POST request to our Express API endpoint (/send-sms).
2. The Express application receives the request, validates the input (recipient number, message).
3. The application uses the Vonage Node.js SDK, configured with your Vonage Application credentials, to make a request to the Vonage Messages API.
4. Vonage handles the SMS delivery to the recipient's phone number via the carrier networks.
5. Vonage returns a response (e.g., message UUID) to our application, which then relays a success or error response back to the original client.

[Client] ---- HTTP POST ----> [Node.js/Express App] ---- Vonage SDK ----> [Vonage Messages API] ---- SMS ----> [Recipient Phone]
   ^                                |
   |------------ HTTP Response ------|

Expected Outcome: A running Node.js server with a /send-sms endpoint that successfully sends an SMS when called with valid parameters.

Prerequisites:

• Node.js and npm (or yarn): Installed on your system. You can download them from nodejs.org. Using Node Version Manager (nvm) is recommended for managing Node.js versions.
• Vonage API Account: A free account is sufficient to start. Sign up at Vonage API Dashboard. You'll receive some free credits for testing.
• Vonage Application ID and Private Key: You'll generate these within your Vonage account.
• A Vonage Phone Number: You need to rent a virtual number from Vonage to use as the sender (FROM) number. You can do this through the Vonage dashboard.
• (Optional but Recommended) ngrok: If you plan to extend this to receive SMS later, ngrok (ngrok.com) is essential for exposing your local server to the internet for webhooks. It's not strictly needed just for sending.
• (Optional but Recommended) Vonage CLI: Can be helpful for managing applications and numbers. Install with npm install -g @vonage/cli.

1. Setting up the Project

Let's initialize our Node.js project and install the necessary dependencies.

1. Create Project Directory: Open your terminal or command prompt and create a new directory for the project, then navigate into it.

   bash

   mkdir vonage-send-sms-guide
   cd vonage-send-sms-guide
   

2. Initialize Node.js Project: This command creates a package.json file to manage your project's dependencies and scripts. Assuming you'll use ES Modules (import), you might want to add ""type"": ""module"" to your package.json later, or ensure your Node.js version supports it natively for .js files.

   bash

   npm init -y
   

3. Install Dependencies: We need Express for the web server, the Vonage Server SDK to interact with the API, and dotenv for managing environment variables.

   bash

   npm install express @vonage/server-sdk dotenv
   

4. Create Project Files: Create the main application file and a file for environment variables.

   bash

   touch index.js .env .gitignore
   

5. Configure .gitignore: It's crucial to prevent sensitive information and unnecessary files from being committed to version control. Add the following lines to your .gitignore file:

   # Dependencies
   node_modules/
   
   # Environment variables
   .env
   
   # Private key file
   private.key
   
   # OS generated files
   .DS_Store
   Thumbs.db
   
   # Log files
   *.log
   npm-debug.log*
   yarn-debug.log*
   yarn-error.log*
   

   Why .gitignore? It tells Git which files or directories to ignore, preventing accidental exposure of API secrets, private keys, or large dependency folders.

6. Set up Environment Variables (.env): Open the .env file and define placeholders for your Vonage credentials and server configuration. We will obtain these values in the next section.

   bash

   # Vonage Credentials (Messages API - Application ID & Private Key)
   VONAGE_APPLICATION_ID=YOUR_APPLICATION_ID
   VONAGE_PRIVATE_KEY_PATH=./private.key # Path to your downloaded private key
   
   # Vonage Number (Sender ID)
   VONAGE_NUMBER=YOUR_VONAGE_NUMBER # Must be in E.164 format (e.g., 14155550100)
   
   # Server Configuration
   PORT=3000
   

   Why .env? It separates configuration and secrets from your code, making it more secure and easier to manage different environments (development, staging, production). The dotenv library loads these variables into process.env when the application starts.

2. Vonage Account and Application Setup

Before writing code, we need to configure our Vonage account and generate the necessary credentials.

1. Sign Up/Log In: Go to the Vonage API Dashboard and log in or create a new account.

2. Find API Key and Secret (For Reference): On the main dashboard page after logging in, you'll see your API key and API secret. While we are primarily using the Application ID/Private Key method for the Messages API (as configured in .env), it's good to know where these are as other Vonage APIs or older examples might use them. Do not share these publicly.

3. Create a Vonage Application: The Messages API typically uses an Application context for authentication and configuration (like webhooks, though we don't need them just for sending).

   • Navigate to Applications in the left-hand menu.
   • Click Create a new application.
   • Give your application a name (e.g., ""Node Send SMS Guide App"").
   • Click Generate public and private key. This will automatically download the private.key file. Save this file securely in your project directory (or another location you specify in VONAGE_PRIVATE_KEY_PATH). Vonage does not store this private key, so keep it safe!
   • Note the Application ID displayed on the page.
   • Enable the Messages capability. You'll see fields for Inbound URL and Status URL. While not strictly required only for sending, it's good practice to fill these if you might add receiving capabilities later. If using ngrok, you might put something like https://<your-ngrok-url&gt;/webhooks/inbound and https://<your-ngrok-url&gt;/webhooks/status. For now, you can enter placeholder URLs like https://example.com/inbound.
   • Click Generate new application.

4. Rent a Vonage Number: You need a Vonage virtual number to send SMS from.

   • Navigate to Numbers > Buy numbers.
   • Search for numbers using country, features (SMS), and type (Mobile recommended).
   • Choose a number and click Buy. Confirm the purchase (it will likely use your initial free credits).

5. Link Number to Application: Associate the number you just rented with the application you created.

   • Go back to Applications and select the application you created (""Node Send SMS Guide App"").
   • Scroll down to the Link virtual numbers section.
   • Find the number you rented and click the Link button next to it.

6. Update .env File: Now, open your .env file again and replace the placeholders with your actual credentials:

   • VONAGE_APPLICATION_ID: The Application ID you noted in step 3.
   • VONAGE_PRIVATE_KEY_PATH: The path to where you saved the private.key file (e.g., ./private.key if it's in the root of your project).
   • VONAGE_NUMBER: The Vonage virtual number you rented in step 4 (use E.164 format, e.g., 14155550100).

3. Implementing the Core SMS Sending Logic

Now, let's write the Node.js code using Express and the Vonage SDK.

Open index.js and add the following code:

// index.js
import express from 'express';
import { Vonage } from '@vonage/server-sdk';
// Load environment variables from .env file
import 'dotenv/config';

// --- Basic Input Validation ---
// Very simple check for E.164 format (starts with +, followed by digits)
// Production apps should use a more robust library like 'libphonenumber-js'
const isValidE164 = (phoneNumber) => /^\+[1-9]\d{1,14}$/.test(phoneNumber);

// --- Initialize Express App ---
const app = express();
app.use(express.json()); // Middleware to parse JSON request bodies
app.use(express.urlencoded({ extended: true })); // Middleware to parse URL-encoded bodies

// --- Initialize Vonage Client ---
// Ensure required environment variables are set
if (!process.env.VONAGE_APPLICATION_ID || !process.env.VONAGE_PRIVATE_KEY_PATH || !process.env.VONAGE_NUMBER) {
    console.error(""Error: Vonage environment variables (Application ID, Private Key Path, Vonage Number) are not set."");
    process.exit(1); // Exit if configuration is missing
}

const vonage = new Vonage({
    applicationId: process.env.VONAGE_APPLICATION_ID,
    privateKey: process.env.VONAGE_PRIVATE_KEY_PATH,
});

// --- Define API Endpoint ---
app.post('/send-sms', async (req, res) => {
    console.log('Received request to /send-sms:', req.body);

    // 1. Extract data from request body
    const { to, text } = req.body;

    // 2. Basic Input Validation
    if (!to || !text) {
        console.error('Validation Error: Missing ""to"" or ""text"" in request body');
        return res.status(400).json({ success: false, message: 'Missing required fields: ""to"" and ""text"".' });
    }

    if (!isValidE164(to)) {
        console.error(`Validation Error: Invalid ""to"" number format: ${to}. Must be E.164.`);
        return res.status(400).json({ success: false, message: 'Invalid recipient phone number format. Use E.164 (e.g., +14155550100).' });
    }

    // 3. Prepare message parameters
    const from = process.env.VONAGE_NUMBER;

    // 4. Send the SMS using Vonage Messages API
    try {
        console.log(`Attempting to send SMS from ${from} to ${to}`);
        const resp = await vonage.messages.send({
            message_type: ""text"",
            text: text,
            to: to,
            from: from,
            channel: ""sms""
        });

        console.log('Vonage API Response:', resp);
        console.log(`SMS submitted successfully to ${to}. Message UUID: ${resp.message_uuid}`);

        // 5. Send success response to client
        res.status(200).json({
            success: true,
            message: 'SMS sent successfully!',
            message_uuid: resp.message_uuid
        });

    } catch (err) {
        // 6. Handle errors from Vonage API
        console.error('Error sending SMS via Vonage:', err);

        // Provide more specific feedback if possible
        let statusCode = 500;
        let errorMessage = 'Failed to send SMS.';

        if (err.response) {
            // Error response from Vonage server
            statusCode = err.response.status || 500;
            errorMessage = `Vonage API Error (${statusCode}): ${err.response.data?.title || err.message}`;
            console.error('Vonage Error Details:', err.response.data);
        } else if (err.request) {
            // Request made but no response received
            errorMessage = 'Error sending SMS: No response received from Vonage.';
        } else {
            // Setup error or other issue
            errorMessage = `Error sending SMS: ${err.message}`;
        }

        res.status(statusCode).json({
            success: false,
            message: errorMessage,
            error_details: err.response?.data // Include details if available
        });
    }
});

// --- Basic Health Check Endpoint ---
app.get('/health', (req, res) => {
    res.status(200).json({ status: 'UP', timestamp: new Date().toISOString() });
});

// --- Start the Server ---
const port = process.env.PORT || 3000;
app.listen(port, () => {
    console.log(`Server listening on port ${port}`);
    console.log(`API endpoint available at http://localhost:${port}/send-sms`);
});

// Export the app instance (useful for testing, requires restructuring if server start is here)
// export default app; // Uncomment and potentially move app definition/server start if needed for tests

Code Explanation:

1. Imports: We import express, the Vonage class from the SDK, and configure dotenv.
2. Input Validation: A simple isValidE164 function is included. For production, use a dedicated library like libphonenumber-js for robust phone number validation.
3. Express Setup: An Express app instance is created, and middleware (express.json, express.urlencoded) is added to parse incoming request bodies.
4. Vonage Client Initialization: We create an instance of the Vonage client, passing the applicationId and privateKey path read from process.env. Basic checks ensure these variables are present.
5. /send-sms Endpoint (POST):
   • Defines an asynchronous POST route handler.
   • Extracts to (recipient number) and text (message content) from req.body.
   • Performs validation checks for missing fields and E.164 format.
   • Retrieves the from number (your Vonage number) from environment variables.
   • Calls vonage.messages.send() with the required parameters:
     • message_type: ""text"": Specifies a plain text SMS.
     • text: The message content.
     • to: The recipient's E.164 phone number.
     • from: Your Vonage E.164 phone number.
     • channel: ""sms"": Explicitly tells the Messages API to use SMS.
   • Uses a try...catch block to handle potential errors during the API call.
   • Success: Logs the response from Vonage (containing the message_uuid) and sends a 200 JSON response to the client.
   • Error: Logs the detailed error and sends an appropriate HTTP status code (400 for validation, 500 or specific Vonage error code) and JSON error message back to the client.
6. /health Endpoint (GET): A simple endpoint useful for monitoring services to check if the application is running.
7. Server Start: Starts the Express server, listening on the port defined in .env (or 3000 by default).

Why async/await? The vonage.messages.send() method is asynchronous (it makes a network request). Using async/await makes the code cleaner and easier to read compared to traditional Promise .then()/.catch() chaining, especially when handling responses and errors.

4. Building and Testing the API Endpoint

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

1. Run the Application: Open your terminal in the project directory and run:

   bash

   node index.js
   

   You should see output like:

   Server listening on port 3000
   API endpoint available at http://localhost:3000/send-sms
   

2. Test with cURL: Open another terminal window and use curl to send a POST request. Remember to replace +1xxxxxxxxxx with a phone number you have verified in your Vonage account, especially if using a free trial account (see Section 7 for details on whitelisting). Update the message text if desired.

   bash

   curl -X POST http://localhost:3000/send-sms \
   -H ""Content-Type: application/json"" \
   -d '{
     ""to"": ""+1xxxxxxxxxx"",
     ""text"": ""Hello from Node.js and Vonage!""
   }'
   

3. Test with Postman (or similar API client):

   • Create a new request.

   • Set the method to POST.

   • Set the URL to http://localhost:3000/send-sms.

   • Go to the ""Body"" tab, select ""raw"", and choose ""JSON"" from the dropdown.

   • Enter the JSON payload (again, replace +1xxxxxxxxxx with a verified test number):

     json

     {
       ""to"": ""+1xxxxxxxxxx"",
       ""text"": ""Hello from Node.js and Vonage via Postman!""
     }
     

   • Click ""Send"".

Expected Success Response (JSON):

{
  ""success"": true,
  ""message"": ""SMS sent successfully!"",
  ""message_uuid"": ""aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"" // Example UUID
}

You should also receive the SMS on the phone number specified in the to field shortly after. Check the console where node index.js is running for detailed logs.

Example Error Response (JSON - Invalid Number Format):

{
  ""success"": false,
  ""message"": ""Invalid recipient phone number format. Use E.164 (e.g., +14155550100).""
}

5. Error Handling and Logging

Our current implementation includes basic try...catch and console.log/console.error. For production, consider:

• Structured Logging: Use libraries like winston or pino for structured JSON logs, which are easier to parse and analyze with log management tools (e.g., Datadog, Splunk, ELK stack). Include request IDs for tracing.
• Centralized Error Tracking: Integrate services like Sentry or Bugsnag to automatically capture and report unhandled exceptions and errors.
• More Granular Error Handling: Analyze specific error codes or messages returned by the Vonage API (accessible in err.response.data in the catch block) to provide more specific feedback or trigger different retry logic. Common Vonage errors include authentication issues, insufficient funds, invalid numbers, or rate limiting.
• Retry Mechanisms: For transient network errors or specific Vonage rate limit responses, implement a retry strategy, potentially with exponential backoff (e.g., using libraries like async-retry). Be cautious not to retry errors that indicate a permanent failure (like an invalid number).

6. Security Considerations

While this is a basic example, security is paramount:

• Input Validation: We added basic E.164 validation. Robust validation using libraries like libphonenumber-js is crucial to prevent errors and potential injection issues if numbers are constructed dynamically. Sanitize the text input if it comes from potentially untrusted sources to prevent cross-site scripting (XSS) if the message content is ever displayed in a web context elsewhere.
• Rate Limiting: Protect your API endpoint from abuse and excessive cost by implementing rate limiting. Libraries like express-rate-limit can restrict the number of requests allowed from a single IP address or user within a specific time window.
• Authentication/Authorization: This guide creates an open endpoint. In a real application, you must protect this endpoint. Implement authentication (e.g., API Keys, JWT tokens, OAuth) to ensure only authorized clients can trigger SMS sending.
• Secrets Management: Never commit your .env file or private.key to Git. Use environment variables provided by your deployment platform or a dedicated secrets management service (like AWS Secrets Manager, Google Secret Manager, HashiCorp Vault).
• HTTPS: Always run your Express application behind a reverse proxy (like Nginx or Caddy) configured with TLS/SSL certificates (HTTPS) in production to encrypt traffic.

7. Troubleshooting and Caveats

• Non-Whitelisted Destination Error: If you are using a new Vonage free trial account, you can typically only send SMS messages to numbers you have verified and added to your account's test number list. Go to your Vonage Dashboard -> Settings -> Customer Details (or similar section) to add and verify test numbers until you upgrade your account by adding payment details. This is the most common issue when starting out.
• Authentication Errors: Double-check that VONAGE_APPLICATION_ID is correct and VONAGE_PRIVATE_KEY_PATH points to the valid private.key file downloaded when creating the application. Ensure the file has the correct read permissions for the Node.js process.
• Invalid FROM Number: Ensure VONAGE_NUMBER in your .env file is a valid number you have rented from Vonage, is linked to your Application, and is in E.164 format.
• Invalid TO Number Format: The recipient number must be in E.164 format (e.g., +14155550100).
• Insufficient Funds: Check your Vonage account balance. Sending SMS costs money (even if small amounts). Free trial credits eventually run out.
• Private Key Format/Path: Ensure the private.key file content hasn't been accidentally modified (it should start with -----BEGIN PRIVATE KEY-----). Verify the path in .env is correct relative to where you run node index.js.
• SDK/API Version Issues: Ensure you're using a compatible version of the @vonage/server-sdk. Check the Vonage documentation if errors seem related to API changes.
• Firewall Issues: If running on a server, ensure outbound connections on port 443 (HTTPS) are allowed, as the SDK communicates with the Vonage API over HTTPS.

8. Deployment and CI/CD

• Deployment Platforms: You can deploy this Node.js application to various platforms like Heroku, Vercel, AWS (EC2, Lambda, Elastic Beanstalk), Google Cloud (App Engine, Cloud Run), Azure App Service, etc.
• Environment Variables: Configure your production environment variables (VONAGE_APPLICATION_ID, VONAGE_PRIVATE_KEY_PATH, VONAGE_NUMBER, PORT, etc.) securely through the platform's interface or configuration files. Do not deploy your .env file.
• Deploying the Private Key: Securely transfer the private.key file to your server or, preferably, store its content in a secure environment variable or secrets manager and configure your application to read it from there instead of a file path.
• Process Management: Use a process manager like pm2 or nodemon (for development) to keep your Node.js application running reliably and handle restarts.
• CI/CD: Set up a Continuous Integration/Continuous Deployment pipeline (e.g., using GitHub Actions, GitLab CI, Jenkins) to automate testing, building, and deploying your application whenever you push changes to your repository. Typical steps include: install dependencies, run linters, run automated tests, build (if necessary), deploy to staging/production.

9. Verification and Testing

• Manual Verification:
  • Run the server locally (node index.js).
  • Use curl or Postman to hit the /send-sms endpoint with valid data (using a whitelisted number).
  • Verify the SMS is received on the target phone.
  • Check the server logs for success messages (SMS submitted successfully...).
  • Test with invalid data (missing fields, incorrect number format) and verify appropriate error responses (400 Bad Request) and logs.
  • Test the /health endpoint.
• Automated Testing:
  • Unit Tests: Use frameworks like Jest or Mocha/Chai. Mock the @vonage/server-sdk to test your endpoint logic (/send-sms handler) without actually calling the Vonage API. Verify input validation, correct parameter passing to the mocked SDK function, and appropriate success/error responses.
  • Integration Tests: You could write tests that do interact with the Vonage API (potentially using dedicated test credentials or numbers if available), but this is often slower, costs money, and can be less reliable. Mocking is generally preferred for CI pipelines. Use libraries like supertest to make HTTP requests to your running Express app during tests.

Example Unit Test Snippet (using Jest - Conceptual Structure):

Important Note: The following Jest example demonstrates the structure and concept of unit testing the endpoint with mocking. Setting up Jest to correctly mock dependencies and load an Express app defined and started in the same file (index.js) can be complex. Often, separating the Express app definition (app.js) from the server start logic (server.js) makes testing significantly easier. This example uses placeholder assertions and assumes a setup where the app can be tested, which might require additional configuration or code restructuring not covered here. It uses import syntax for consistency with the main application code.

// __tests__/index.test.js (Conceptual Example)
import request from 'supertest';
import express from 'express'; // Used for manual app setup in this example

// Assuming your express app instance might be exported or you re-define routes for test
// import app from '../index'; // Adjust path/export as needed for your structure

// Mock the Vonage SDK before any application code is potentially imported
jest.mock('@vonage/server-sdk', () => ({
  Vonage: jest.fn().mockImplementation(() => ({
    messages: {
      send: jest.fn().mockResolvedValue({ message_uuid: 'mock-uuid-12345' }) // Mock success case
      // Example for mocking failure:
      // send: jest.fn().mockRejectedValue(new Error('Mock Vonage Error'))
    }
  }))
}));

describe('POST /send-sms endpoint', () => {
  let app;

  beforeAll(() => {
      // --- Complex Setup Area ---
      // This is where the challenge lies if app/server aren't separated.
      // Option 1: Dynamically import app after mocks (needs jest.resetModules() etc.)
      // Option 2: Re-create a minimal express app and attach the route handler
      //           (assuming handler logic can be imported separately).
      // Option 3: Restructure main code (app.js exports app, index.js imports and starts)

      // Using Option 2 for demonstration (requires handler export):
      app = express();
      app.use(express.json());
      // You would need to import the actual route handler function from your index.js
      // e.g., import { handleSendSmsRoute } from '../index';
      // app.post('/send-sms', handleSendSmsRoute);

      // If the handler isn't easily exportable, this test setup won't work as shown.
      console.warn(""Jest test setup is conceptual and may require code restructuring (separating Express app from server start) to function correctly."");
  });


  it('should conceptually demonstrate testing a successful SMS send', async () => {
      // This assertion is a placeholder because the app setup above is incomplete.
      // The real test would look like this if 'app' was correctly configured:
      /*
      const response = await request(app)
          .post('/send-sms')
          .send({ to: '+14155550100', text: 'Test message' });

      expect(response.statusCode).toBe(200);
      expect(response.body).toEqual({
          success: true,
          message: 'SMS sent successfully!',
          message_uuid: 'mock-uuid-12345' // From the mock
      });
      // Optionally verify the mock was called:
      // const { Vonage } = require('@vonage/server-sdk'); // Re-require to access mock instance
      // const mockVonageInstance = Vonage.mock.instances[0];
      // expect(mockVonageInstance.messages.send).toHaveBeenCalledWith(expect.objectContaining({
      //     to: '+14155550100',
      //     text: 'Test message'
      // }));
      */
     expect(true).toBe(true); // Placeholder assertion
  });

  it('should conceptually demonstrate testing for missing ""to"" field', async () => {
     // Placeholder assertion. Real test structure:
     /*
     const response = await request(app)
          .post('/send-sms')
          .send({ text: 'Test message' }); // Missing 'to'

     expect(response.statusCode).toBe(400);
     expect(response.body).toEqual(expect.objectContaining({
          success: false,
          message: 'Missing required fields: ""to"" and ""text"".'
     }));
     */
    expect(true).toBe(true); // Placeholder assertion
  });

  // Add more conceptual tests for other validation rules (invalid E.164)
  // and for cases where the mocked vonage.messages.send rejects.

});

10. Complete Code Repository

A complete, working example of this project can be found on GitHub:

https://github.com/sent-dev/nodejs-vonage-send-sms-guide

This repository contains the index.js, package.json, .env.example, and .gitignore files described in this guide.

You now have a solid foundation for sending SMS messages using Node.js, Express, and the Vonage Messages API. Remember to prioritize security, robust error handling, and thorough testing as you integrate this functionality into larger applications. You can extend this further by adding features like receiving SMS messages, managing contacts, or scheduling messages. Refer to the Vonage Messages API documentation for more advanced capabilities.