You can send MMS messages within your RedwoodJS application by integrating the Vonage Messages API and Node.js SDK. This involves setting up your Vonage account, configuring the necessary environment variables, creating a RedwoodJS service, and implementing a GraphQL mutation to handle the sending logic.

The Vonage Messages API allows your RedwoodJS backend to send rich media messages like images with captions (MMS). It's useful for various application features such as sending notifications, alerts, or engaging with users using multimedia content.

Storing sensitive information like API keys and secrets in environment variables (`.env` file) is crucial for security. It keeps them separate from your codebase, preventing accidental exposure in version control. RedwoodJS supports loading these variables automatically.

In the Vonage API Dashboard, create a new application, enable the "Messages" capability, configure webhooks (even placeholder URLs for basic sending), generate public/private keys (place `private.key` in your `api/` folder), and obtain the Application ID. Link your Vonage number to the Application.

The private key path (`VONAGE_PRIVATE_KEY_PATH` in `.env` and your service code) should be relative to the `api` directory (e.g., `./private.key`). Use `path.resolve` in the `mms.ts` service file to ensure the correct path resolution during development and production builds where folder structures might change.

Initialize the `Messages` client *once* outside the handler function (resolver) to avoid unnecessary setup overhead on every MMS request. Declare it globally within the service file after importing `@vonage/messages`.

The standard setup outlined in the guide primarily focuses on sending MMS *to* US phone numbers. For international MMS, consult the Vonage documentation as different APIs or configurations might be required.

Use a `try...catch` block around the `vonageClient.send()` call in your RedwoodJS service to handle errors. Log error details using Redwood's `logger` and either throw a new `Error` for the GraphQL layer to handle or return a structured error object if you modify the `SendMmsResponse` type.

Double-check all Vonage credentials (API Key/Secret, App ID, Private Key content/path) in your `.env` file. Verify that the correct Vonage number is linked to your application and the application has the Messages capability enabled and is configured for JWT authentication (implicit when using Application ID and Private Key pair).

Vonage MMS supports `.jpg`, `.jpeg`, and `.png` image formats. The image URL you provide must be publicly accessible—private URLs or those requiring authentication will not work.

Use the RedwoodJS GraphQL Playground (`http://localhost:8911/graphql`) to execute the `sendMms` mutation with test data. Replace placeholder values with a valid US recipient number, a public image URL, and an optional caption. Monitor server logs and check your phone for the MMS.

Never commit API keys, secrets, or the private key to version control. Always use environment variables (`.env`) and ensure the `.env` file is added to your `.gitignore`. In production environments, further restrict access to the private key file.

RedwoodJS provides a built-in logger. Use `logger.info` for informational messages and `logger.error` for logging errors, including the full error object for detailed diagnostics. Consider integrating with a centralized logging service for production.

The standard Vonage Messages API and the guide focus on US numbers due to regulatory requirements and specific features like 10DLC for compliance. The sender number (`VONAGE_SENDER_NUMBER`) needs to be a US number linked to your Vonage application, and typically, sending is restricted to US recipients using this setup.

While not covered directly in this guide, consider using the Vonage Dispatch API for fallback strategies. If an MMS fails to send (e.g., due to carrier issues or unsupported device), Vonage Dispatch can automatically retry the message as an SMS for improved reliability.