This guide provides a step-by-step walkthrough for integrating the Vonage SMS API into a RedwoodJS application to send SMS messages programmatically. We'll build a simple interface to trigger messages, focusing on a robust backend implementation suitable for marketing campaigns, notifications, or other communication needs.

By the end of this tutorial, you will have a functional RedwoodJS application capable of sending SMS messages via Vonage, complete with essential configurations, error handling, and security considerations. This serves as a solid foundation for building more complex SMS campaign features.

Project Overview and Goals

What We're Building:

1. A backend API (GraphQL) endpoint to accept SMS details (recipient number(s), message text).
2. A service function that uses the Vonage Server SDK for Node.js to send the SMS.
3. Basic frontend elements (using Redwood Forms) to input message details and trigger the API call.
4. Secure handling of Vonage API credentials using environment variables.
5. Basic error handling and logging.

Problem Solved:

This project enables developers to programmatically send targeted SMS messages directly from their web application, facilitating communication for:

• Marketing promotions
• Appointment reminders
• Order confirmations
• Security notifications (e.g., OTPs, alerts)
• User engagement campaigns

Technologies Used:

• RedwoodJS: A full-stack, serverless-first web application framework built on React, GraphQL, and Prisma. Chosen for its integrated structure (API and web sides), opinionated defaults, and developer experience features (generators, cells, forms).
• Vonage SMS API: A robust Communications Platform as a Service (CPaaS) API for sending and receiving SMS messages globally. Chosen for its reliability, scalability, and developer-friendly SDKs.
• Node.js: The runtime environment for the RedwoodJS API side.
• GraphQL: Query language for the API layer, tightly integrated into RedwoodJS.
• Prisma: Node.js & TypeScript ORM used by RedwoodJS for database interactions (though we won't implement complex DB logic in this initial guide, Prisma is part of the stack).
• Yarn: Package manager used by RedwoodJS.

System Architecture:

The flow is straightforward:

+-----------------+      +-----------------------+      +----------------+      +--------------+
| RedwoodJS Web   | ---> | RedwoodJS API (GraphQL)| ---> | Vonage Service | ---> | Vonage SMS API|
| (React Frontend)|      | (Node.js Backend)     |      | (Node.js SDK)  |      | (External API)|
+-----------------+      +-----------------------+      +----------------+      +--------------+
      | User Inputs           | Handles Request           | Sends SMS             | Delivers SMS
      | Message Details       | & Business Logic          | via API               | to Recipient

1. The user interacts with the RedwoodJS frontend (Web side) to provide recipient number(s) and message text.
2. The frontend triggers a GraphQL mutation on the RedwoodJS backend (API side).
3. The GraphQL resolver calls a RedwoodJS service function.
4. The service function initializes the Vonage Node.js SDK client using API keys from environment variables.
5. The service function calls the Vonage SDK's send method to dispatch the SMS message via the Vonage platform.
6. Vonage handles the delivery of the SMS to the recipient's phone.
7. The service function returns a success or error status to the frontend.

Prerequisites:

• Node.js: Version 18.x or 20.x recommended.
• Yarn: Version 1.x (Classic). RedwoodJS uses Yarn 1 by default.
• RedwoodJS CLI: Installed globally (npm install -g @redwoodjs/cli or yarn global add @redwoodjs/cli).
• Vonage API Account:
  • Sign up for a free account at Vonage API Dashboard.
  • Note your API Key and API Secret found on the dashboard homepage after signup.
  • You will also need a Vonage phone number (virtual number) to send messages from. You can purchase one in the dashboard under ""Numbers"" > ""Buy numbers"".
  • Important for Trial Accounts: When using a Vonage trial account, you typically need to verify the phone numbers you intend to send messages to within the Vonage dashboard. Sending may fail for unverified numbers on a trial.
• Basic understanding of JavaScript, React, and command-line interfaces.

Expected Outcome:

A running RedwoodJS application where you can enter a phone number and message text into a form, click ""Send"", and have an SMS delivered to that number via your Vonage account.

1. Setting up the Project

Let's create the RedwoodJS project and install necessary dependencies.

Step 1: Create RedwoodJS Application

Open your terminal and run the RedwoodJS create command. We'll name our project redwood-vonage-sms.

yarn create redwood-app redwood-vonage-sms

Follow the prompts. Choose TypeScript if you prefer, but this guide will use JavaScript for broader accessibility.

Step 2: Navigate to Project Directory

cd redwood-vonage-sms

Step 3: Install Vonage Server SDK

The Vonage SDK needs to be installed in the API workspace of your Redwood project.

yarn workspace api add @vonage/server-sdk

This command specifically adds the @vonage/server-sdk package to the api/package.json file and installs it within the api/node_modules directory.

Step 4: Configure Environment Variables

RedwoodJS uses .env files for environment variables. The .env file is gitignored by default for security.

Create a .env file in the root of your project:

touch .env

Add your Vonage API credentials and your Vonage sending number to this file.

# .env
VONAGE_API_KEY=YOUR_VONAGE_API_KEY
VONAGE_API_SECRET=YOUR_VONAGE_API_SECRET
VONAGE_SENDER_ID=YOUR_VONAGE_PHONE_NUMBER # Use E.164 format, e.g., 14155550100

• VONAGE_API_KEY: Found on your Vonage Dashboard. Purpose: Authenticates your application with Vonage.
• VONAGE_API_SECRET: Found on your Vonage Dashboard. Purpose: Authenticates your application with Vonage.
• VONAGE_SENDER_ID: One of your purchased Vonage virtual numbers in E.164 format (e.g., 14155550100). Purpose: The 'From' number displayed to the recipient. In some countries, you might use an Alphanumeric Sender ID if registered and approved by Vonage.

Explanation: Using environment variables keeps sensitive credentials out of your source code, which is crucial for security. RedwoodJS automatically loads variables from .env during development. For deployment, you'll need to configure these variables in your hosting provider's environment settings.

2. Defining the API Layer (GraphQL)

Now, let's define the backend API endpoint using GraphQL.

Step 1: Generate SDL and Service Files

Use the Redwood generator to create the Schema Definition Language (SDL) and service files for SMS functionality:

yarn rw g sdl sms --no-crud

This command creates:

• api/src/graphql/sms.sdl.ts (or .js)
• api/src/services/sms/sms.ts (or .js)
• api/src/services/sms/sms.test.ts (or .js)

Step 2: Define the GraphQL Schema

Edit api/src/graphql/sms.sdl.ts (or .js) to define the sendSms mutation:

# api/src/graphql/sms.sdl.ts (or .js)

export const schema = gql`
  type Mutation {
    """"""Sends an SMS message via Vonage.""""""
    sendSms(input: SendSmsInput!): SendSmsResponse! @skipAuth # Allow unauthenticated access for now
  }

  input SendSmsInput {
    """"""Recipient phone number in E.164 format (e.g., +14155550100).""""""
    to: String!
    """"""The text content of the SMS message.""""""
    text: String!
  }

  type SendSmsResponse {
    """"""Indicates if the message was queued successfully by Vonage.""""""
    success: Boolean!
    """"""Optional message ID provided by Vonage on success.""""""
    messageId: String
    """"""Optional error message if sending failed.""""""
    error: String
  }
`

Explanation:

• We define a Mutation type with one field: sendSms.
• sendSms takes a required input argument of type SendSmsInput.
• SendSmsInput defines the required fields: to (recipient) and text (message body). Using an input type keeps the mutation arguments organized.
• sendSms returns a SendSmsResponse type.
• SendSmsResponse indicates success (boolean) and provides optional messageId or error details.
• @skipAuth: For simplicity in this guide, we disable authentication for this mutation. In a real application, you would implement authentication (@requireAuth) to ensure only authorized users can send SMS.

3. Implementing the Service Logic

Now, implement the logic within the service file generated earlier. This function will initialize the Vonage client and call its API.

Edit api/src/services/sms/sms.ts (or .js):

// api/src/services/sms/sms.ts (or .js)
import { Vonage } from '@vonage/server-sdk'
import { logger } from 'src/lib/logger' // Redwood's built-in logger

export const sendSms = async ({ input }: { input: { to: string; text: string } }) => {
  const { to, text } = input

  // Validate input (basic example)
  if (!to || !text) {
    // Consider using more specific error types in production
    throw new Error('Recipient number (to) and message text are required.')
  }
  // Add more robust validation (e.g., using zod, E.164 format check) here if needed

  const apiKey = process.env.VONAGE_API_KEY
  const apiSecret = process.env.VONAGE_API_SECRET
  const senderId = process.env.VONAGE_SENDER_ID

  if (!apiKey || !apiSecret || !senderId) {
    logger.error('Vonage API credentials or Sender ID missing in environment variables.')
    // Consider using a specific configuration error type
    throw new Error('Server configuration error: Vonage credentials not set.')
  }

  try {
    // Initialize Vonage Client
    const vonage = new Vonage({
      apiKey: apiKey,
      apiSecret: apiSecret,
    })

    logger.info(`Attempting to send SMS to ${to} from ${senderId}`)

    // Send the SMS using Vonage SDK
    const responseData = await vonage.sms.send({
      to: to,
      from: senderId, // Your Vonage number or registered Sender ID
      text: text,
    })

    // Robustly check Vonage response
    // Check if messages array exists and has at least one message
    if (responseData?.messages?.length > 0 && responseData.messages[0].status === '0') {
      const messageId = responseData.messages[0]['message-id']
      logger.info(`SMS submitted successfully to ${to}, messageId: ${messageId}`)
      return {
        success: true,
        messageId: messageId,
        error: null,
      }
    } else {
      // Handle potential partial success or specific errors reported by Vonage
      // Safely access error details if they exist
      const messageInfo = responseData?.messages?.[0];
      const status = messageInfo?.status || 'N/A';
      const errorCode = messageInfo?.['error-text'] || 'Unknown Vonage Error or Malformed Response';
      logger.error(`Vonage failed to send SMS to ${to}. Status: ${status}, Error: ${errorCode}`)
      return {
        success: false,
        messageId: messageInfo?.['message-id'] || null, // Include message ID even on failure if available
        error: `Vonage error (Status: ${status}): ${errorCode}`,
      }
    }
  } catch (error) {
    logger.error({ error }, `Failed to send SMS via Vonage to ${to}`)
    // Catch SDK-level errors (e.g., network issues, authentication failure)
    return {
      success: false,
      messageId: null,
      // Consider returning a more structured error object
      error: error.message || 'An unexpected error occurred while sending SMS.',
    }
  }
}

Explanation:

1. Import: We import the Vonage class from the SDK and Redwood's logger.
2. Function Signature: The sendSms function receives the input object matching our SendSmsInput GraphQL type.
3. Input Validation: Basic check for missing to or text. Production apps should have more robust validation (e.g., using zod or checking phone number format). Added a comment about considering more specific error types.
4. Credentials Check: Retrieve Vonage credentials and Sender ID from process.env. Crucially, it checks if they exist and throws an error if not, preventing the app from trying to operate without proper configuration.
5. Vonage Client Initialization: Create a Vonage instance using the API key and secret.
6. Logging: Use logger.info and logger.error to record actions and potential issues. This is invaluable for debugging.
7. vonage.sms.send(): Call the core SDK function:
   • to: Recipient number from the input.
   • from: Your configured Vonage Sender ID from .env.
   • text: Message content from the input.
8. Response Handling (Improved):
   • The send method returns a response object. We now check responseData?.messages?.length > 0 before accessing responseData.messages[0] to prevent runtime errors if the messages array is missing or empty.
   • If status is '0', log success and return { success: true, messageId }.
   • If Vonage reports an error (non-'0' status or unexpected response structure), safely access the status and error text, log the details, and return { success: false, error }.
9. Error Handling (try...catch): Wrap the Vonage call in a try...catch block. This catches errors thrown by the SDK itself (e.g., invalid credentials recognized by the SDK, network problems connecting to Vonage). Log the error and return { success: false, error }.
10. Return Value: The function returns an object matching the SendSmsResponse GraphQL type.

4. Building the Frontend

Now, let's create a simple page on the web side to interact with our API.

Step 1: Generate the Page

Use the Redwood generator to create a page:

yarn rw g page SmsSender

This creates web/src/pages/SmsSenderPage/SmsSenderPage.js (or .tsx) and adds a route in web/src/Routes.js (or .tsx).

Step 2: Implement the Page Component

Edit web/src/pages/SmsSenderPage/SmsSenderPage.js (or .tsx):

// web/src/pages/SmsSenderPage/SmsSenderPage.js (or .tsx)
import { useState } from 'react'
import { MetaTags, useMutation } from '@redwoodjs/web'
import { Form, TextField, TextAreaField, Submit, FieldError, Label, useForm } from '@redwoodjs/forms'
import { toast, Toaster } from '@redwoodjs/web/toast'
import { logger } from 'src/lib/logger' // Import logger for frontend if needed

// Define the GraphQL Mutation
const SEND_SMS_MUTATION = gql`
  mutation SendSmsMutation($input: SendSmsInput!) {
    sendSms(input: $input) {
      success
      messageId
      error
    }
  }
`

const SmsSenderPage = () => {
  const formMethods = useForm()
  const [loading, setLoading] = useState(false) // Track loading state

  // useMutation hook to interact with the GraphQL API
  const [sendSms, { error: mutationError }] = useMutation(SEND_SMS_MUTATION, {
    onCompleted: (data) => {
      setLoading(false) // Stop loading indicator
      if (data.sendSms.success) {
        toast.success(`SMS sent successfully! Message ID: ${data.sendSms.messageId}`)
        formMethods.reset() // Clear the form on success
      } else {
        toast.error(`Failed to send SMS: ${data.sendSms.error || 'Unknown error'}`)
      }
    },
    onError: (error) => {
      // Catch network/GraphQL level errors not caught by the service's try/catch
      setLoading(false) // Stop loading indicator
      logger.error(error) // Use Redwood logger on the web side if desired
      toast.error(`Mutation Error: ${error.message}`)
    }
  })

  // Form submission handler
  const onSubmit = async (data) => {
    setLoading(true) // Start loading indicator
    try {
      await sendSms({ variables: { input: data } })
    } catch (e) {
      // This catch might be redundant due to onError, but good practice
      setLoading(false)
      logger.error(e)
      toast.error(`Submission Error: ${e.message}`)
    }
  }

  return (
    <>
      <MetaTags title=""SMS Sender"" description=""Send SMS messages via Vonage"" /&gt;
      <Toaster toastOptions={{ className: 'rw-toast'_ duration: 6000 }} /&gt;

      <h1&gt;Send SMS via Vonage</h1&gt;

      <Form onSubmit={onSubmit} formMethods={formMethods} className=""rw-form-wrapper""&gt;
        <Label name=""to"" className=""rw-label"" errorClassName=""rw-label rw-label-error""&gt;
          Recipient Number (E.164 format, e.g., +14155550100)
        </Label&gt;
        <TextField
          name=""to""
          className=""rw-input""
          errorClassName=""rw-input rw-input-error""
          validation={{
            required: { value: true_ message: 'Recipient number is required' }_
            pattern: {
              value: /^\+[1-9]\d{1_14}$/_ // Basic E.164 format check
              message: 'Please enter a valid E.164 phone number (e.g._ +14155550100)'
            }
           }}
        /&gt;
        <FieldError name=""to"" className=""rw-field-error"" /&gt;

        <Label name=""text"" className=""rw-label"" errorClassName=""rw-label rw-label-error""&gt;
          Message Text
        </Label&gt;
        <TextAreaField
          name=""text""
          className=""rw-input""
          errorClassName=""rw-input rw-input-error""
          validation={{
             required: { value: true_ message: 'Message text is required' }_
             maxLength: { value: 1600_ message: 'Message is too long' } // Generous limit
          }}
        /&gt;
        <FieldError name=""text"" className=""rw-field-error"" /&gt;

        {mutationError && (
           <div className=""rw-form-error""&gt;
             <p&gt;API Error: {mutationError.message}</p&gt;
           </div&gt;
         )}

        <div className=""rw-button-group""&gt;
          <Submit disabled={loading} className=""rw-button rw-button-blue""&gt;
            {loading ? 'Sending...' : 'Send SMS'}
          </Submit&gt;
        </div&gt;
      </Form&gt;
    </&gt;
  )
}

export default SmsSenderPage

Explanation:

1. Imports: Import necessary components from React, RedwoodJS (MetaTags, useMutation, @redwoodjs/forms, @redwoodjs/web/toast). Optionally import logger.
2. SEND_SMS_MUTATION: Define the GraphQL mutation string that matches the one defined in the SDL.
3. useForm: Initialize Redwood Forms for handling form state and validation.
4. useState: Track a loading state for user feedback during submission.
5. useMutation Hook:
   • Takes the GraphQL mutation string (SEND_SMS_MUTATION) as the first argument.
   • Takes an options object with callbacks:
     • onCompleted: Called when the mutation successfully executes on the server (even if the service logic returns success: false). It receives the data returned by the mutation (data.sendSms). We check data.sendSms.success here to show appropriate success/error toasts and reset the form on success.
     • onError: Called if there's a GraphQL or network-level error preventing the mutation from even reaching the service resolver.
   • Returns an array: [sendSmsFunction, { data, loading, error }]. We primarily use the sendSmsFunction to trigger the mutation and the error object for displaying API-level errors.
6. onSubmit Handler:
   • This function is passed to the <Form&gt; component's onSubmit prop.
   • It receives the validated form data.
   • Sets loading to true.
   • Calls the sendSms function returned by useMutation, passing the form data wrapped in the expected { variables: { input: data } } structure.
   • Includes a try...catch as a fallback, though onError usually handles mutation execution errors.
7. <Toaster&gt;: Component required by toast to display notifications.
8. <Form&gt; Component: Redwood's form wrapper. Takes the onSubmit handler and formMethods.
9. Form Fields: Uses Redwood's Label, TextField, TextAreaField, and FieldError components for easy form creation and validation display.
   • Validation: Includes required checks and a basic pattern check for the E.164 format on the to field. maxLength is added to the text field. Redwood Forms handles displaying errors defined here using FieldError.
10. <Submit&gt; Button: Redwood's submit button component. disabled={loading} prevents multiple submissions.
11. Error Display: Shows mutationError if there's a GraphQL/network error. Service-level errors are handled via toasts in onCompleted.

5. Implementing Proper Error Handling, Logging, and Retry Mechanisms

Error Handling (Covered Above):

• Frontend: Redwood Forms validation catches input errors. useMutation's onError catches GraphQL/network errors. onCompleted checks the success flag from the service response for Vonage-specific errors. Toasts provide user feedback.
• Backend (Service):
  • Input validation prevents processing invalid data.
  • try...catch blocks handle SDK exceptions (auth, network).
  • Checking the Vonage API response status (responseData.messages[0].status) handles errors reported by Vonage itself (e.g., invalid number format recognized by Vonage, insufficient funds). The logic was improved for safety (Section 3).
  • Clear separation of success/error states in the return object ({ success, messageId, error }).
  • (Minor - Best Practice) Consider defining and using more specific error classes (e.g., ValidationError, ConfigurationError, VonageApiError) instead of generic Error objects for clearer error handling upstream.

Logging (Covered Above):

• Redwood's built-in Pino logger (logger from src/lib/logger) is used in the service (api/src/services/sms/sms.ts).
• logger.info logs successful attempts and outcomes.
• logger.error logs configuration issues, SDK errors, and Vonage API errors, often including the error object itself for detailed stack traces.
• Logs automatically output to the console during development (yarn rw dev). In production deployments, configure your hosting provider or logging service (e.g., Logflare, Datadog) to capture these logs.

Retry Mechanisms:

Implementing retries adds complexity. For SMS, retries should be handled carefully to avoid duplicate messages.

• Client-Side Retries: Generally not recommended for actions like sending SMS, as network hiccups could lead to multiple successful submissions if the user retries manually after the first request actually succeeded but the response was lost. Disabling the submit button while loading helps prevent this.

• Server-Side Retries: If the vonage.sms.send() call fails due to potentially transient issues (e.g., temporary network error, Vonage rate limit), you could implement a retry strategy within the service function.

  • Identify Retryable Errors: Only retry on specific error codes or types (e.g., network timeouts, 429 Too Many Requests from Vonage, which might manifest as status code '1' or '8' depending on context). Do not retry on errors like invalid credentials ('4') or invalid phone numbers ('15'). Consult the Vonage SMS API documentation for the specific meaning of status codes to determine which are truly transient and safe to retry.
  • Use a Library: Libraries like async-retry or p-retry can simplify implementing exponential backoff (waiting progressively longer between retries).
  • Idempotency: Ensure your retry logic doesn't accidentally send duplicates if the first request did succeed but the response failed. Vonage doesn't inherently support idempotency keys for the standard SMS API in the same way some REST APIs do. Careful status checking is needed.
  • Example Sketch (Conceptual - requires async-retry):
  typescript

  // api/src/services/sms/sms.ts (Conceptual Retry Snippet)
  import retry from 'async-retry';
  import { Vonage } from '@vonage/server-sdk';
  import { logger } from 'src/lib/logger';
  import { db } from 'src/lib/db'; // Assuming DB logging
  
  // ... inside sendSms function, replace the direct call and response handling ...
  
  let finalResult: { success: boolean; messageId?: string; error?: string } | null = null;
  
  try {
    finalResult = await retry(
      async (bail, attempt) => {
        logger.info(`Attempt ${attempt} to send SMS to ${to}`);
        const responseData = await vonage.sms.send({ to, from: senderId, text });
        const messageInfo = responseData?.messages?.[0];
        const messageStatus = messageInfo?.status;
        const errorText = messageInfo?.['error-text'];
        const messageId = messageInfo?.['message-id'];
  
        if (messageStatus === '0') {
          logger.info(`SMS submitted successfully to ${to}, messageId: ${messageId}`);
          // Resolve successfully, exiting retry loop
          return { success: true, messageId: messageId, error: null };
        } else {
          const errorMessage = `Vonage error (Status: ${messageStatus}): ${errorText || 'Unknown Vonage Error'}`;
          logger.warn(`Attempt ${attempt} failed: ${errorMessage}`);
  
          // Check if error is potentially retryable (e.g., throttling '1', internal error '5')
          // CONSULT VONAGE DOCS FOR RETRYABLE STATUS CODES
          if (messageStatus === '1' || messageStatus === '5') {
             throw new Error(errorMessage); // Throw to trigger retry
          } else {
             // Non-retryable error, bail out of retry loop
             // The error passed to bail will be thrown by the retry function
             bail(new Error(errorMessage));
             // This return is technically unreachable due to bail, but satisfies TS
             return { success: false, messageId: messageId, error: errorMessage };
          }
        }
      },
      {
        retries: 3, // Number of retries
        factor: 2, // Exponential backoff factor
        minTimeout: 1000, // Initial delay 1 second
        onRetry: (error, attempt) => {
          logger.warn(`Retrying SMS send to ${to} (attempt ${attempt}) due to: ${error.message}`);
        },
      }
    );
  
    // If retry was successful, finalResult is already set correctly.
    // If retry bailed with a non-retryable error, the error is caught below.
    // If all retries failed with retryable errors, the last error is caught below.
  
  } catch (error) {
    // This catches errors from the last retry attempt OR the error passed to bail()
    logger.error({ error }, `Failed to send SMS via Vonage to ${to} after all retries or due to non-retryable error`);
    finalResult = { success: false, error: error.message || 'Failed after retries' };
  }
  
  // Now, handle logging to DB based on the finalResult
  if (finalResult.success) {
      // Log success to DB (if using DB logging)
      await db.smsLog.create({ data: { /* ... success data ... */ vonageMessageId: finalResult.messageId } });
  } else {
      // Log failure to DB (if using DB logging)
      await db.smsLog.create({ data: { /* ... failure data ... */ errorMessage: finalResult.error } });
  }
  
  return finalResult; // Return the final outcome after retry logic
  
  // The original single catch block for SDK errors outside retry is now less necessary
  // if the retry block wraps the entire vonage.sms.send call.
  
  • Recommendation: Start without automatic retries. Add them only if you observe frequent transient failures in production and have carefully considered the idempotency implications. Logging and monitoring are key to identifying the need for retries.

6. Creating a Database Schema and Data Layer (Optional Extension)

While not strictly required for sending a single SMS, storing campaign details or message logs is often necessary. RedwoodJS uses Prisma for database interactions.

Step 1: Define Schema

Edit api/db/schema.prisma:

// api/db/schema.prisma

datasource db {
  provider = ""postgresql"" // Or ""sqlite"", ""mysql""
  url      = env(""DATABASE_URL"")
}

generator client {
  provider      = ""prisma-client-js""
}

model SmsLog {
  id           String    @id @default(cuid())
  createdAt    DateTime  @default(now())
  recipient    String
  sender       String
  messageText  String
  status       String    // e.g., ""SUBMITTED"", ""FAILED"", ""DELIVERED"" (via webhooks)
  vonageMessageId String?   @unique
  errorMessage String?
  // Add campaign relations, user relations etc. if needed
  // campaignId   String?
  // campaign     Campaign? @relation(fields: [campaignId], references: [id])
}

// Example: Add a Campaign model
// model Campaign {
//   id        String   @id @default(cuid())
//   name      String
//   createdAt DateTime @default(now())
//   messages  SmsLog[]
// }

Step 2: Create Migration

Generate the SQL migration file and apply it to your database:

# Make sure your DATABASE_URL is set in .env (e.g., for SQLite: DATABASE_URL=""file:./dev.db"")
yarn rw prisma migrate dev --name add_sms_log

This creates a migration file in api/db/migrations and updates your database schema.

Step 3: Update Service to Log

Modify api/src/services/sms/sms.ts to use the Prisma client (db is auto-imported/available in Redwood services) to save a log entry:

// api/src/services/sms/sms.ts (Additions for DB logging)
import { Vonage } from '@vonage/server-sdk'
import { logger } from 'src/lib/logger'
import { db } from 'src/lib/db' // Import Redwood's Prisma client instance

export const sendSms = async ({ input }: { input: { to: string; text: string } }) => {
  const { to, text } = input
  // ... Input validation and credential checks ...
  const apiKey = process.env.VONAGE_API_KEY! // Add non-null assertion or handle possibility of undefined if check isn't exhaustive
  const apiSecret = process.env.VONAGE_API_SECRET!
  const senderId = process.env.VONAGE_SENDER_ID!

  let response: { success: boolean; messageId?: string; error?: string } | null = null;

  try {
    const vonage = new Vonage({ apiKey, apiSecret });
    logger.info(`Attempting to send SMS to ${to} from ${senderId}`);
    const responseData = await vonage.sms.send({ to, from: senderId, text });

    if (responseData?.messages?.length > 0 && responseData.messages[0].status === '0') {
        const messageId = responseData.messages[0]['message-id'];
        logger.info(`SMS submitted successfully to ${to}, messageId: ${messageId}`);
        response = { success: true, messageId: messageId, error: null };
        // Log to DB on success
        await db.smsLog.create({
          data: {
            recipient: to,
            sender: senderId,
            messageText: text,
            status: 'SUBMITTED', // Initial status
            vonageMessageId: messageId,
          },
        });
    } else {
        const messageInfo = responseData?.messages?.[0];
        const status = messageInfo?.status || 'N/A';
        const errorCode = messageInfo?.['error-text'] || 'Unknown Vonage Error or Malformed Response';
        const messageId = messageInfo?.['message-id'];
        const errorMessage = `Vonage error (Status: ${status}): ${errorCode}`;
        logger.error(`Vonage failed to send SMS to ${to}. Status: ${status}, Error: ${errorCode}`);
        response = { success: false, messageId: messageId, error: errorMessage };
        // Log to DB on Vonage-reported failure
        await db.smsLog.create({
          data: {
            recipient: to,
            sender: senderId,
            messageText: text,
            status: 'FAILED',
            errorMessage: errorMessage,
            vonageMessageId: messageId, // Log ID even if failed if available
          },
        });
    }
  } catch (error) {
    const errorMessage = error.message || 'An unexpected error occurred while sending SMS.';
    logger.error({ error }, `Failed to send SMS via Vonage to ${to}`);
    response = { success: false, messageId: null, error: errorMessage };
    // Log to DB on SDK/network failure
    await db.smsLog.create({
      data: {
        recipient: to,
        sender: senderId,
        messageText: text, // Log text even on SDK failure
        status: 'FAILED',
        errorMessage: errorMessage,
      },
    });
  }

  // Ensure response is not null before returning
  if (!response) {
    // This should ideally not happen if the try/catch logic is correct,
    // but provides a fallback.
    logger.error('SMS service function reached end without setting a response.');
    return { success: false, error: 'Internal server error: Failed to determine SMS outcome.' };
  }

  return response;
}