Integrate AWS SNS into your RedwoodJS application by setting up AWS credentials, creating a RedwoodJS service to interact with the AWS SNS API, defining a GraphQL mutation, and implementing error handling. This allows you to send SMS messages via the AWS SDK for JavaScript v3.

The AWS SDK for JavaScript v3, specifically the @aws-sdk/client-sns package, is the official AWS library used to interact with the Simple Notification Service (SNS) from your RedwoodJS Node.js backend. It handles the API calls for sending SMS messages.

RedwoodJS uses GraphQL as its query language for API interactions. This allows you to define a sendSms mutation in your schema, which then automatically connects to your backend service function, providing a structured and type-safe way to trigger SMS sending.

Use 'Transactional' for critical messages like one-time passcodes (OTPs) due to higher delivery reliability, although it might be slightly more expensive. 'Promotional' is suitable for marketing messages to optimize costs. Set this using the messageType parameter in your sendSms mutation.

New AWS accounts are in a sandbox and may only send to verified numbers. To send to unverified numbers globally, request removal from the sandbox via an AWS Support case. Refer to the AWS SNS SMS Sandbox documentation for details.

Create an IAM user in the AWS Management Console with the necessary permissions (ideally a custom policy with just sns:Publish). Store the access key ID, secret access key, and AWS region in a .env file in your project root. Ensure .env is in .gitignore.

The RedwoodJS service contains the core logic for sending SMS. It interacts with the AWS SDK, handles input validation, prepares the API request parameters, and manages error responses. In this setup, it's within the api/src/services/sms/sms.ts file.

The provided code example uses UserInputError for invalid inputs (like incorrect phone number format) and RedwoodError for backend errors, allowing specific error handling at the service level and translating them to GraphQL errors for the client. For more advanced handling, examine specific AWS SDK error codes within the catch block.

Use a regular expression or a dedicated library to validate that numbers conform to the E.164 format (+ followed by country code and number) before sending them to the SNS API. This is important to ensure successful SMS delivery.

Manually test using the GraphQL Playground with your own valid E.164 phone number. Use the provided automated tests in api/src/services/sms/sms.test.ts, mocking the AWS SDK for reliable and reproducible testing that doesn't send actual SMS messages.

You'll need Node.js (v18 or later recommended), Yarn, RedwoodJS CLI, an active AWS Account, and basic familiarity with RedwoodJS, TypeScript, GraphQL, and the AWS Management Console.

Extend your Prisma schema with an SmsLog model to record details like recipient, message, status, and any errors. Modify the sendSms service to create or update SmsLog entries after each attempt.

The @requireAuth directive ensures that only authenticated users can call the sendSms mutation. If you intend for public access, remove this directive, but proceed with extreme caution to prevent abuse.

Use your hosting provider's secrets management service to store and inject AWS credentials into your application's environment. Never commit AWS credentials to your code repository.