Build RedwoodJS Marketing Campaigns with MessageBird and Node.js

Build a comprehensive SMS marketing campaign system using RedwoodJS, MessageBird SMS API, and Node.js GraphQL backend. This step-by-step guide covers RedwoodJS SMS integration from initial project setup through production deployment and verification. You'll learn how to create a marketing automation system that sends bulk SMS campaigns, tracks delivery status, and handles errors gracefully.

Important Platform Update (2025): MessageBird rebranded as Bird in February 2024. The legacy MessageBird platform (dashboard.messagebird.com) shuts down March 31, 2025. For new implementations after this date, use the Bird next-gen platform (app.bird.com), though the MessageBird API and Node.js SDK remain functional during the transition. See Bird's migration documentation for details.

By the end of this tutorial, you'll have a RedwoodJS application with a GraphQL API endpoint that accepts campaign details (message content, recipient list) and uses the MessageBird SDK to dispatch SMS messages. This solves the common need to programmatically send bulk or targeted SMS campaigns for marketing or notifications.

Project Overview and Goals

Create a robust system within a RedwoodJS application that sends SMS marketing messages through MessageBird.

Key Goals:

1. Setup: Initialize a RedwoodJS project configured for MessageBird integration
2. API Layer: Create a GraphQL mutation to trigger SMS campaigns
3. Integration: Integrate the MessageBird Node.js SDK into a RedwoodJS service
4. Data Handling: Define a basic data model to track campaigns (optional but recommended)
5. Security: Secure the API endpoint and handle API keys properly
6. Error Handling: Implement basic error handling for API calls
7. Deployment: Outline steps to deploy the application
8. Verification: Provide methods to test and verify the implementation

Technologies Used:

• RedwoodJS: A full-stack, serverless-friendly framework for React frontends and GraphQL backends (using Node.js and Prisma). Chosen for its integrated structure, developer experience, and opinionated defaults that accelerate development.
• Node.js: The runtime environment for the RedwoodJS API side
• MessageBird: The third-party SMS API provider. Chosen for its reliable messaging services and developer-friendly APIs/SDKs.
• Prisma: The ORM used by RedwoodJS for database interactions
• GraphQL: The query language for the API layer, intrinsic to RedwoodJS
• Jest: The testing framework integrated with RedwoodJS

System Architecture:

graph LR
    A[User/Client Web App (React)] -- GraphQL Mutation --> B(RedwoodJS GraphQL API);
    B -- Calls Service --> C{RedwoodJS Service (Node.js)};
    C -- Uses SDK --> D[MessageBird API];
    C -- CRUD Ops --> E[(Database via Prisma)];
    D -- Sends SMS --> F[Recipient Phone];
    E -- Stores Campaign Data --> C;

Prerequisites:

• Node.js (v20 or v22 LTS): Node.js v18 reaches end-of-life in April 2025. Use v20 LTS ("Iron", maintenance until April 2026) or v22 LTS ("Jod", active support until April 2027). RedwoodJS v8+ requires Node.js v20.x minimum. Check your version: node -v. Install from nodejs.org.
• Yarn (v1.15 or later, or Yarn v4): RedwoodJS supports both Yarn Classic and Yarn Berry. Check installation: yarn -v.
• MessageBird/Bird Account: Sign up at messagebird.com or bird.com. For new projects after March 31, 2025, use the Bird next-gen platform.
• Access to a terminal or command prompt
• Basic understanding of RedwoodJS, GraphQL, and JavaScript/TypeScript

What You'll Build:

You'll create a functional RedwoodJS application endpoint that receives recipient numbers and a message, sends SMS messages via MessageBird, and provides feedback on the operation's success or failure.

How to Set Up Your RedwoodJS Project for SMS Integration

Initialize your project, install dependencies, and set up the basic structure.

1. Create RedwoodJS App: Open your terminal and run the RedwoodJS create command:

   bash

   yarn create redwood-app ./redwood-messagebird-campaigns
   

   Follow the prompts (choosing JavaScript or TypeScript). For this guide, we'll assume JavaScript, but the steps are very similar for TypeScript.

2. Navigate to Project Directory:

   bash

   cd redwood-messagebird-campaigns
   

3. Install MessageBird SDK: Install the MessageBird Node.js SDK specifically in the api workspace.

   bash

   yarn workspace api add messagebird
   

4. Environment Variables: RedwoodJS uses .env files for environment variables. The .env.defaults file is committed to git and holds default (non-sensitive) values. The .env file (which should be in your .gitignore) holds sensitive keys.

   • Create the .env file in the project root:

     bash

     touch .env
     

   • Add your MessageBird API Key and optionally a default originator to .env. You'll retrieve the API key in Section 4.

     plaintext

     # .env
     # For projects created after March 31, 2025, obtain from Bird platform (app.bird.com > Settings > API Keys)
     # For legacy projects, obtain from MessageBird Dashboard (dashboard.messagebird.com > Developers > API access)
     MESSAGEBIRD_API_KEY=YOUR_LIVE_API_KEY
     MESSAGEBIRD_DEFAULT_ORIGINATOR=YourSenderID # Optional: Your registered sender ID or number
     

   • Add placeholders to .env.defaults so others know what's needed:

     plaintext

     # .env.defaults
     MESSAGEBIRD_API_KEY=replace_with_live_api_key_in_env
     MESSAGEBIRD_DEFAULT_ORIGINATOR= # Optional: Default sender ID or number
     

   • Ensure .env is listed in your root .gitignore file (Redwood typically adds this by default). The MESSAGEBIRD_API_KEY is your secret credential. The MESSAGEBIRD_DEFAULT_ORIGINATOR is the default sender ID or number if not provided in the request (see Section 4.3).

5. Project Structure: RedwoodJS has a specific structure:

   • api/: Backend code (GraphQL API, services, database schema).
   • web/: Frontend React code.
   • scripts/: Utility scripts.

   Focus primarily on the api/ directory, specifically api/src/graphql, api/src/services, and potentially api/db. This structure separates concerns, making the application easier to manage.

How to Implement the MessageBird Service Layer

Implement the core logic for interacting with MessageBird within a RedwoodJS service. Services contain your business logic on the API side.

1. Generate Service: Use the RedwoodJS CLI to generate a service file for handling marketing campaigns.

   bash

   yarn rw g service marketingCampaigns
   

   This creates api/src/services/marketingCampaigns/marketingCampaigns.js (and related files like tests).

2. Implement Sending Logic: Open api/src/services/marketingCampaigns/marketingCampaigns.js and add the logic to send messages.

   javascript

   // api/src/services/marketingCampaigns/marketingCampaigns.js
   import { requireAuth } from 'src/lib/auth' // Import Redwood's auth
   import { logger } from 'src/lib/logger'
   import { UserInputError } from '@redwoodjs/graphql-server'
   
   // Import and initialize the MessageBird client
   // Automatically reads the API key from process.env.MESSAGEBIRD_API_KEY
   const messagebird = require('messagebird').initClient(process.env.MESSAGEBIRD_API_KEY)
   
   export const sendMarketingCampaign = async ({ input }) => {
     // Ensure the user is authenticated (optional but recommended)
     // requireAuth() // Uncomment if you have auth setup
   
     const { recipients, message, originator } = input
   
     // Basic Validation
     if (!recipients || recipients.length === 0) {
       throw new UserInputError('Recipients list cannot be empty.')
     }
     if (!message || message.trim() === '') {
       throw new UserInputError('Message content cannot be empty.')
     }
   
     // Determine the originator: use input, fallback to env var, then to a generic default
     const effectiveOriginator = originator || process.env.MESSAGEBIRD_DEFAULT_ORIGINATOR || 'Campaign'
     if (!originator && !process.env.MESSAGEBIRD_DEFAULT_ORIGINATOR) {
       logger.warn('Originator not provided in input or environment, using generic default "Campaign". This may affect deliverability.')
     } else if (!originator && process.env.MESSAGEBIRD_DEFAULT_ORIGINATOR) {
       logger.info(`Using default originator from environment: ${process.env.MESSAGEBIRD_DEFAULT_ORIGINATOR}`)
     }
   
     const params = {
       originator: effectiveOriginator,
       recipients: recipients, // Array of phone numbers (E.164 format recommended)
       body: message,
     }
   
     logger.info({ recipients: params.recipients, originator: params.originator }, 'Attempting to send campaign via MessageBird')
   
     try {
       // Use the MessageBird SDK to send the message(s)
       // The current MessageBird SDK returns a Promise directly
       const result = await messagebird.messages.create(params)
   
       logger.info({ response: result }, 'MessageBird response received')
   
       // You can process the response further
       // e.g., check individual message statuses if needed, store results, etc.
       // The 'result' object contains details about the batch submission
       // Individual message statuses arrive later via webhooks (advanced setup)
   
       return {
         success: true,
         messageBirdId: result.id, // ID of the message batch
         status: `Campaign submitted to MessageBird with ${result.recipients.totalSentCount} messages.`,
       }
   
     } catch (error) {
       logger.error({ error }, 'Failed to send marketing campaign')
       // Extract a more specific error message if available
       const errorMessage = error.errors ? error.errors[0].description : error.message
       // Return a structured error response for the GraphQL layer
       return {
         success: false,
         messageBirdId: null,
         status: `Failed to send campaign: MessageBird API Error: ${errorMessage}`,
       }
       // Or re-throw a GraphQL-friendly error
       // throw new Error(`Failed to send campaign: MessageBird API Error: ${errorMessage}`)
     }
   }
   
   // Add other service functions here later (e.g., getCampaignStatus)
   

   Why this approach?

   • Service Layer: Encapsulates business logic, making the code modular and testable
   • Environment Variables: Securely handles the API key and allows a default originator
   • SDK Usage: Leverages the official MessageBird SDK for easier API interaction
   • Async/Await: Uses modern JavaScript for handling the asynchronous SDK call
   • Basic Validation: Prevents sending empty requests
   • Logging: Uses Redwood's built-in logger for visibility
   • Error Handling: Includes try...catch for robustness and provides informative error messages based on the SDK's potential error structure

How to Build the GraphQL API for SMS Campaigns

Expose the service function via a GraphQL mutation.

1. Define GraphQL Schema (SDL): Create/edit the GraphQL schema definition file for marketing campaigns.

   bash

   yarn rw g sdl marketingCampaigns
   

   Open api/src/graphql/marketingCampaigns.sdl.js and define the input type and mutation.

   graphql

   # api/src/graphql/marketingCampaigns.sdl.js
   export const schema = gql`
     """
     Input required to send a marketing campaign.
     """
     input SendCampaignInput {
       "List of recipient phone numbers in E.164 format (e.g., +14155552671)."
       recipients: [String!]!
       "The content of the SMS message."
       message: String!
       "Sender ID or phone number registered with MessageBird (optional, falls back to env default)."
       originator: String
     }
   
     """
     Response after attempting to send a campaign.
     """
     type CampaignStatus {
       "Indicates if the submission to MessageBird was successful."
       success: Boolean!
       "The ID assigned by MessageBird to this message batch (if successful)."
       messageBirdId: String
       "A status message describing the outcome."
       status: String!
     }
   
     type Mutation {
       """
       Sends an SMS marketing campaign via MessageBird.
       """
       sendMarketingCampaign(input: SendCampaignInput!): CampaignStatus! @skipAuth
       # Use @requireAuth instead of @skipAuth if authentication is set up and required
       # @requireAuth
     }
   `
   

   Explanation:

   • SendCampaignInput: Defines the structure of the data needed to call the mutation. Using input types keeps mutations clean.
   • CampaignStatus: Defines the structure of the response returned by the mutation.
   • sendMarketingCampaign: The mutation itself, linking to the sendMarketingCampaign function in your service (Redwood maps this automatically by name convention). It takes the input and returns the status.
   • @skipAuth/@requireAuth: Redwood's directive for controlling access. Use @requireAuth once you have authentication implemented. @skipAuth makes it publicly accessible (use with caution in production).

2. Testing the Endpoint (GraphQL Playground): RedwoodJS includes a GraphQL Playground.

   • Start the development server:

     bash

     yarn rw dev
     

   • Navigate to http://localhost:8910/graphql.

   • Use the following mutation (replace placeholders):

     graphql

     mutation SendTestCampaign {
       sendMarketingCampaign(input: {
         recipients: ["+1XXXXXXXXXX", "+44YYYYYYYYYY"] # Use valid E.164 numbers
         message: "Hello from our RedwoodJS Campaign!"
         # originator: "YourSenderID" # Optional: Provide here or set MESSAGEBIRD_DEFAULT_ORIGINATOR in .env
       }) {
         success
         messageBirdId
         status
       }
     }
     

   • Execute the mutation. You should see a response like:

     json

     {
       "data": {
         "sendMarketingCampaign": {
           "success": true,
           "messageBirdId": "mbid_xxxxxxxxxxxxxxxxxxxx",
           "status": "Campaign submitted to MessageBird with 2 messages."
         }
       }
     }
     

     Or an error response if something went wrong:

     json

     {
       "data": {
         "sendMarketingCampaign": {
           "success": false,
           "messageBirdId": null,
           "status": "Failed to send campaign: MessageBird API Error: authentication failed"
         }
       }
     }
     

How to Configure MessageBird API Credentials

Configure the MessageBird SDK correctly to ensure proper functionality.

1. Obtaining the API Key:

   • Log in to your MessageBird Dashboard (or Bird platform after March 31, 2025).
   • Navigate to the "Developers" section in the left-hand menu.
   • Click on "API access".
   • You'll see your Live API Key. This is the key you need. Don't use the Test API Key unless you're specifically testing features that support it (basic SMS sending usually requires the Live key).
   • Click the "Copy" icon next to the Live API Key.

2. Storing the API Key Securely:

   • As done in Step 1.4, paste the copied Live API Key into your .env file in the project root:

     plaintext

     # .env
     MESSAGEBIRD_API_KEY=YOUR_COPIED_LIVE_API_KEY
     # MESSAGEBIRD_DEFAULT_ORIGINATOR=YourSenderID # Optional
     

   • Never commit your .env file or your API key directly into your code or version control (Git). Redwood's default .gitignore already includes .env.

3. Understanding Environment Variables:

   • MESSAGEBIRD_API_KEY: (Required) Your secret credential for authenticating with the MessageBird API. The SDK (require('messagebird').initClient()) automatically looks for this environment variable. Format: A string like live_xxxxxxxxxxxxxxxxxxxx. Obtain from: MessageBird Dashboard > Developers > API access (or Bird platform > Settings > API Keys after March 31, 2025).
   • MESSAGEBIRD_DEFAULT_ORIGINATOR: (Optional) Set a default sender ID or phone number here if you don't want to specify it in every API call. If not set here and not provided in the mutation input, a generic default like "Campaign" might be used, which could impact deliverability. Format: A string (e.g., "MyCompany", "+15551234567"). Obtain/Configure in: MessageBird Dashboard > Numbers or Sender IDs.

4. Fallback Mechanisms: The current code doesn't explicitly implement complex fallback mechanisms for MessageBird outages. For critical systems, consider:

   • Retries: Implement retry logic (see next section)
   • Alternative Providers: Abstract the messaging service and have the ability to switch to another provider if MessageBird experiences significant downtime (more complex setup)
   • Monitoring: Closely monitor MessageBird's status page and API error rates

How to Handle Errors and Implement Retry Logic

Handle failures gracefully in your application.

1. Error Handling Strategy:

   • Service Layer: Catch errors from the MessageBird SDK (try...catch). Log detailed errors using logger.error(). Return structured error information or throw specific GraphQL errors (UserInputError, AuthenticationError, etc.) for the API layer. The current implementation returns a structured error within the CampaignStatus object.
   • API Layer (GraphQL): Redwood automatically handles errors thrown from services and formats them for the GraphQL response. If the service returns a structured error object (like CampaignStatus), that object returns in the data field. If the service throws an error, it appears in the errors field of the GraphQL response.
   • MessageBird Errors: The SDK passes error objects. Inspect error.errors (an array) for specific API validation issues (e.g., invalid recipient number, insufficient balance). Log these details. The current error handling extracts the first error description.

2. Logging:

   • RedwoodJS uses pino for logging. Use logger.info(), logger.warn(), logger.error(), etc., within your service.
   • Log key events: initiation of a campaign send, parameters used (excluding sensitive data if necessary), success responses from MessageBird, and detailed error information.
   • In production, configure log levels and destinations appropriately (e.g., send logs to a log aggregation service). Customize Redwood's api/src/lib/logger.js as needed.

3. Retry Mechanisms (Basic Example): For transient network issues or temporary MessageBird problems, a simple retry can help. Use libraries like async-retry or implement a basic loop.

   • Install async-retry:

     bash

     yarn workspace api add async-retry
     

   • Modify the service function:

     javascript

     // api/src/services/marketingCampaigns/marketingCampaigns.js
     import { requireAuth } from 'src/lib/auth'
     import { logger } from 'src/lib/logger'
     import { UserInputError } from '@redwoodjs/graphql-server'
     import retry from 'async-retry' // Import retry
     
     const messagebird = require('messagebird').initClient(process.env.MESSAGEBIRD_API_KEY)
     
     export const sendMarketingCampaign = async ({ input }) => {
       // ... (input validation and originator logic) ...
     
       const params = {
         originator: effectiveOriginator,
         recipients: recipients,
         body: message,
       }
     
       logger.info({ recipients: params.recipients, originator: params.originator }, 'Attempting to send campaign via MessageBird')
     
       try {
         // Wrap the SDK call in the retry logic
         const result = await retry(
           async (bail, attempt) => {
             // bail stops retrying immediately (e.g., for auth errors)
             logger.info(`Attempt ${attempt} to send campaign via MessageBird`)
     
             try {
               // The SDK call returns a promise
               const response = await messagebird.messages.create(params)
               logger.info({ response, attempt }, 'MessageBird response received on attempt')
               return response // Resolve the promise for retry logic
             } catch (err) {
               logger.error({ err, attempt }, 'MessageBird API error on attempt')
     
               // Check for specific non-retryable errors
               // Error structure might vary – check SDK docs or log the error object
               // This checks common patterns for authentication issues
               const isAuthError = (err.statusCode === 401) ||
                                   (err.message && err.message.toLowerCase().includes('authentication failed')) ||
                                   (err.errors && err.errors.some(e => e.code === 20 /* auth error code */));
     
               if (isAuthError) {
                 // Don't retry on authentication failure
                 bail(new Error('Authentication failed with MessageBird. Check API Key.'))
                 return // Important: return after calling bail
               }
     
               // For other errors, throw to trigger retry
               throw err; // Re-throw the original error to let async-retry handle it
             }
           },
           {
             retries: 2, // Number of retries (total attempts = retries + 1)
             factor: 2, // Exponential backoff factor
             minTimeout: 1000, // Initial timeout in ms
             onRetry: (error, attempt) => {
               logger.warn(`Retrying campaign send (attempt ${attempt}) due to error: ${error.message}`)
             },
           }
         )
     
         // Process result and return success
         logger.info({ response: result }, 'MessageBird response received after retries')
         return {
           success: true,
           messageBirdId: result.id,
           status: `Campaign submitted to MessageBird with ${result.recipients.totalSentCount} messages.`,
         };
     
       } catch (error) {
         logger.error({ error }, 'Failed to send marketing campaign after retries')
         const errorMessage = error.errors ? error.errors[0].description : error.message
         return {
            success: false,
            messageBirdId: null,
            status: `Failed to send campaign after retries: MessageBird API Error: ${errorMessage}`,
          };
       }
     }
     

   Testing Errors:

   • Temporarily provide an invalid MESSAGEBIRD_API_KEY in .env to test authentication errors (and the bail condition).
   • Pass invalid recipient numbers in the GraphQL mutation input to test MessageBird validation errors (which should likely trigger retries unless the error is immediate/non-transient).
   • Simulate network issues if possible (less straightforward in local dev).

How to Track Campaign Data with Prisma Database

Store campaign information to track history and status.

1. Define Prisma Schema: Open api/db/schema.prisma and add a Campaign model.

   sql

   // api/db/schema.prisma
   
   datasource db {
     provider = "sqlite" // Or "postgresql", "mysql"
     url      = env("DATABASE_URL")
   }
   
   generator client {
     provider      = "prisma-client-js"
   }
   
   // Add this Campaign model
   model Campaign {
     id              Int       @id @default(autoincrement())
     messageContent  String
     originator      String?   // Sender ID used
     recipientCount  Int
     messageBirdId   String?   @unique // Store the ID from MessageBird response
     status          String    // e.g., "Submitting", "Submitted", "Failed", "Completed" (if using webhooks)
     submittedAt     DateTime  @default(now())
     // Add relation to User model if you have authentication
     // userId          Int?
     // user            User?     @relation(fields: [userId], references: [id])
   }
   
   // Example User model (if using dbAuth)
   // model User {
   //   id             Int @id @default(autoincrement())
   //   email          String @unique
   //   hashedPassword String
   //   salt           String
   //   resetToken     String?
   //   resetTokenExpiresAt DateTime?
   //   campaigns      Campaign[] // Relation to campaigns
   // }
   

   Database Provider Requirements: Prisma v6.x (included with RedwoodJS v8+) requires PostgreSQL 9.6 minimum if using PostgreSQL. For production deployments, use PostgreSQL 12+ for security patches and performance improvements. SQLite is suitable for development only.

   • ERD: This simple schema has one model, Campaign. If linked to a User, it would be a one-to-many relationship (one User can have many Campaigns).

2. Database Migration: Apply the schema changes to your database.

   bash

   yarn rw prisma migrate dev
   

   Enter a name for the migration when prompted (e.g., add campaign model). This creates/updates your database tables.

3. Update Service to Save Campaign: Modify the sendMarketingCampaign service to create a Campaign record.

   javascript

   // api/src/services/marketingCampaigns/marketingCampaigns.js
   import { db } from 'src/lib/db' // Import Redwood's Prisma client
   import { requireAuth } from 'src/lib/auth'
   import { logger } from 'src/lib/logger'
   import { UserInputError } from '@redwoodjs/graphql-server'
   import retry from 'async-retry'
   
   const messagebird = require('messagebird').initClient(process.env.MESSAGEBIRD_API_KEY)
   
   export const sendMarketingCampaign = async ({ input }) => {
     // ... validation and originator logic ...
   
     const params = {
       originator: effectiveOriginator,
       recipients: recipients,
       body: message,
     }
     let campaignRecord = null
   
     try {
       // Create initial campaign record before attempting to send
       campaignRecord = await db.campaign.create({
         data: {
           messageContent: params.body,
           originator: params.originator,
           recipientCount: params.recipients.length,
           status: 'Submitting',
           // userId: context.currentUser?.id // Add if using auth and relation
         },
       })
       logger.info({ campaignId: campaignRecord.id }, 'Created initial campaign record')
   
       // Retry logic wrapping the MessageBird call
       const result = await retry(
           async (bail, attempt) => {
             logger.info(`Attempt ${attempt} to send campaign via MessageBird`)
             try {
               const response = await messagebird.messages.create(params)
               logger.info({ response, attempt }, 'MessageBird response received on attempt')
               return response
             } catch (err) {
               logger.error({ err, attempt }, 'MessageBird API error on attempt')
               const isAuthError = (err.statusCode === 401) ||
                                   (err.message && err.message.toLowerCase().includes('authentication failed')) ||
                                   (err.errors && err.errors.some(e => e.code === 20));
               if (isAuthError) {
                 bail(new Error('Authentication failed with MessageBird. Check API Key.'))
                 return
               }
               throw err;
             }
           },
           {
             retries: 2,
             factor: 2,
             minTimeout: 1000,
             onRetry: (error, attempt) => {
               logger.warn(`Retrying campaign send (attempt ${attempt}) due to error: ${error.message}`)
             },
           }
       );
   
       // Update campaign record on success
       const updatedCampaign = await db.campaign.update({
         where: { id: campaignRecord.id },
         data: {
           status: 'Submitted',
           messageBirdId: result.id,
         },
       })
       logger.info({ campaignId: updatedCampaign.id, messageBirdId: result.id }, 'Updated campaign record to Submitted')
   
       return {
         success: true,
         messageBirdId: result.id,
         status: `Campaign submitted to MessageBird with ${result.recipients.totalSentCount} messages.`,
         campaignId: campaignRecord.id, // Return internal ID too
       }
   
     } catch (error) {
       logger.error({ error, campaignId: campaignRecord?.id }, 'Failed to send marketing campaign')
   
       // Update campaign record on failure (if it was created)
       if (campaignRecord) {
         try {
             await db.campaign.update({
               where: { id: campaignRecord.id },
               data: { status: 'Failed' },
             })
             logger.info({ campaignId: campaignRecord.id }, 'Updated campaign record to Failed')
         } catch (dbError) {
             logger.error({ dbError, campaignId: campaignRecord.id }, 'Failed to update campaign status to Failed after send error')
         }
       }
   
       const errorMessage = error.errors ? error.errors[0].description : error.message
       return {
         success: false,
         messageBirdId: null,
         status: `Failed to send campaign: MessageBird API Error: ${errorMessage}`,
         campaignId: campaignRecord?.id,
       }
     }
   }
   
   • Data Access: Redwood's db object is the Prisma client instance, used for all database operations. This approach logs campaign attempts even if the MessageBird call fails.

How to Secure Your SMS Campaign API

Implement security measures for APIs and user data.

1. Input Validation & Sanitization:

   • The service already includes basic validation (checking for empty recipients/message).
   • Phone Numbers: Ensure recipients are in a valid format (E.164 is recommended: + followed by country code and number). Add a regex check or use a library (like libphonenumber-js) for stricter validation.
   • Message Content: Be mindful of message length limits (standard SMS is 160 GSM-7 characters, longer messages are split). Consider sanitizing input to prevent injection attacks if the message content could ever be displayed elsewhere, though this is less critical for SMS sending itself.
   • Originator: If allowing user input, validate against allowed sender IDs/numbers in your MessageBird account or a predefined list.

2. Authentication & Authorization:

   • Uncomment requireAuth() in the service (marketingCampaigns.js) once you have RedwoodJS authentication set up (e.g., yarn rw setup auth dbAuth). This ensures only logged-in users can trigger campaigns.
   • Add @requireAuth to the GraphQL mutation definition (marketingCampaigns.sdl.js) instead of @skipAuth.
   • Add role-based access control if needed (e.g., only 'admin' or 'marketer' roles can send campaigns, checking context.currentUser.roles).

3. API Key Security:

   • Never commit API keys. Use environment variables (.env) and ensure .env is in .gitignore.
   • Use distinct, restrictive API keys per environment (development, staging, production) if possible via MessageBird settings.

4. Rate Limiting:

   • Prevent abuse by limiting how often a user or IP address can call the sendMarketingCampaign mutation.
   • Consider using Redwood Shield (yarn rw setup graphql-shield) or a middleware approach (if using custom server file) to implement rate limiting (e.g., using rate-limiter-flexible). MessageBird also has its own API rate limits.

5. Common Vulnerabilities:

   • Insecure Direct Object References (IDOR): If you add features to view campaign status by ID, ensure users can only view their own campaigns (check userId against context.currentUser.id in the service logic).
   • Denial of Service (DoS): Rate limiting helps mitigate this. Avoid overly complex operations triggered by a single API call. Be mindful of costs associated with sending large numbers of messages.

How to Handle SMS Special Cases and Compliance

Address real-world messaging nuances.

1. Phone Number Formatting (E.164):

   • MessageBird strongly recommends the E.164 format (+14155551234). While it might correctly interpret local formats for some regions, relying on E.164 is safer for international delivery.
   • Consider adding a pre-processing step in your service or frontend to normalize numbers to E.164 using libraries like libphonenumber-js.

2. Character Limits & Encoding:

   • Standard SMS: 160 characters (GSM-7 encoding)
   • Unicode SMS (e.g., emojis): 70 characters (UCS-2 encoding)
   • Longer messages are automatically split (concatenated SMS) by carriers/MessageBird, consuming more credits per effective message sent. Inform users about potential costs. MessageBird's API response (result.recipients.totalSentCount vs result.recipients.totalCount) might provide clues, and webhooks provide more detail.

3. Opt-Out Handling / Compliance:

   • Crucial for Marketing: Provide recipients an easy way to opt out (e.g., reply STOP). MessageBird can manage opt-out lists automatically for specific numbers/sender IDs. Check their documentation on compliance features (like STOP keyword handling).
   • Your application logic should respect opt-outs. Before sending campaigns, check an internal suppression list or query MessageBird's opt-out list if using their feature. Failure to handle opt-outs can lead to legal issues (e.g., TCPA, GDPR) and carrier filtering.

4. Sender ID (Originator):

   • Alphanumeric Sender IDs (e.g., "MyCompany") are supported in many countries but not all (e.g., US/Canada typically require pre-registered 10DLC, Toll-Free, or Short Codes). Check MessageBird's country-specific regulations. Using unregistered Alphanumeric IDs where not permitted will likely lead to filtering or failure.
   • Using a phone number (VMN, TFN, etc.) as the originator often allows two-way communication and is required in some regions.

5. Delivery Status (Webhooks – Advanced):

   • The basic API call confirms submission to MessageBird, not final delivery to the handset. Statuses like delivered, failed, expired arrive later.
   • For detailed, real-time delivery statuses, configure MessageBird webhooks (DLR – Delivery Reports). This involves:
     • Creating a new webhook endpoint in your RedwoodJS app (using a Function: yarn rw g function messageStatus). This function needs to handle POST requests from MessageBird, validate them, and update your database (e.g., update the Campaign status).
     • Configuring the webhook URL in your MessageBird dashboard.
     • Securing the webhook endpoint (e.g., checking MessageBird's signature).

Frequently Asked Questions About RedwoodJS SMS Integration

What's the difference between MessageBird and Bird platforms?

MessageBird rebranded to Bird in February 2024. The legacy MessageBird platform (dashboard.messagebird.com) shuts down March 31, 2025. For new implementations after this date, use the Bird next-gen platform (app.bird.com) to access enhanced features and consolidated APIs. The MessageBird Node.js SDK and API endpoints remain compatible during the transition, but you should migrate your account and obtain new API keys from Bird's platform before the deadline.

What Node.js and RedwoodJS versions do I need?

RedwoodJS v8+ requires Node.js v20.x minimum. Node.js v18 reached end-of-life in April 2025. Use Node.js v20 LTS ("Iron", maintenance until April 2026) or v22 LTS ("Jod", active support until April 2027) for production deployments. Check your version with node -v and upgrade if necessary. RedwoodJS v8+ includes Prisma v6.x, which requires PostgreSQL 9.6+ (12+ recommended for production).

How do I send bulk SMS campaigns with RedwoodJS?

Create a GraphQL mutation (sendMarketingCampaign) that accepts an array of phone numbers and message content. Use the MessageBird Node.js SDK in your RedwoodJS service layer to send messages via messagebird.messages.create(). Pass recipients as an array in E.164 format (e.g., ["+14155551234", "+442071234567"]). Store campaign metadata in your Prisma database to track status and delivery. Implement rate limiting to prevent abuse and control costs.

How do I handle failed SMS deliveries in RedwoodJS?

Implement retry logic using the async-retry library in your RedwoodJS service. Configure exponential backoff (2-3 retries with increasing delays). Check MessageBird error codes to distinguish between retryable errors (network issues) and non-retryable errors (authentication failures, invalid numbers). Store delivery attempts in your database with status tracking ("Submitting", "Submitted", "Failed"). Configure MessageBird webhooks for real-time delivery status updates beyond the initial submission confirmation.

Can I track SMS campaign analytics in my RedwoodJS app?

Yes, create a Prisma Campaign model to store campaign metadata (message content, recipient count, submission time, MessageBird ID, status). Update the status field based on MessageBird webhook callbacks for detailed delivery tracking. Query your database using RedwoodJS services to generate analytics reports. Track metrics like total sent, delivery rate, failure reasons, and campaign performance over time. Use GraphQL queries to expose analytics data to your React frontend.

How much does MessageBird SMS cost for marketing campaigns?

MessageBird (now Bird) SMS pricing varies by destination country. US SMS typically costs $0.0075 – $0.0125 per message. International rates range from $0.02 – $0.15+ per message depending on the destination. Longer messages exceeding 160 characters (GSM-7) or 70 characters (Unicode) are split into multiple segments, consuming more credits. Check Bird's pricing page for current rates and consider enterprise pricing for high-volume campaigns (10,000+ messages/month).

How do I secure MessageBird API keys in RedwoodJS?

Store API keys in the .env file at your project root and add .env to your .gitignore. RedwoodJS uses @fastify/env for environment validation – define required keys in your envSchema.js. Never commit API keys to version control. Use distinct keys per environment (development, staging, production). For production, use secret management services like AWS Secrets Manager or HashiCorp Vault. Rotate API keys periodically (every 90 days) through Bird's dashboard.

Can I schedule SMS campaigns for future delivery with MessageBird?

Yes, MessageBird supports scheduling messages up to 30 days in advance using the scheduledDatetime parameter in the messages.create() call. Pass an ISO 8601 timestamp (e.g., "2025-12-25T10:00:00Z"). For campaigns beyond 24 hours, implement a two-stage system: store the scheduled time in your Prisma database immediately, then use a cron job or background worker to send the actual SMS when the time approaches. This reduces API load and allows for cancellations or updates before sending.

How do I comply with SMS marketing regulations (TCPA, GDPR)?

Provide recipients an easy opt-out mechanism (e.g., reply STOP). MessageBird can manage opt-out lists automatically – check their compliance documentation. Before sending campaigns, query your internal suppression list or MessageBird's opt-out list. Store user consent records in your database with timestamps and consent method. For US campaigns, register sender IDs through 10DLC or Toll-Free numbers. For EU campaigns under GDPR, obtain explicit consent and honor data deletion requests. Failure to comply can result in legal penalties and carrier filtering.

How do I test MessageBird integration locally in RedwoodJS?

Use MessageBird's Test API key for local development (obtain from dashboard.messagebird.com > Developers > API access). The Test key allows API testing without sending actual SMS or incurring charges. Start your RedwoodJS dev server with yarn rw dev and access the GraphQL Playground at http://localhost:8910/graphql. Execute test mutations with sample phone numbers. MessageBird returns simulated responses for testing. For production testing, use your own verified phone numbers with the Live API key to confirm actual SMS delivery before launching campaigns.