Skip to main content
When a recipient replies STOP to one of your messages, AWS End User Messaging adds them to your opt-out list. The SDK exposes methods on sms.optOuts to manage that list programmatically.
You are legally required to honor opt-out requests immediately. Never send messages to a number on your opt-out list. Ignoring opt-outs violates the TCPA and can result in significant fines.

​
Check opt-out status

Returns true if the number is on the opt-out list, false otherwise. 
const isOptedOut = await sms.optOuts.check('+14155551234');

if (isOptedOut) {
  console.log('User has opted out — do not send.');
}

​
Add an opt-out

Adds a number to the opt-out list. Call this if you receive an opt-out request through a channel other than an SMS reply (e.g. a preference center, unsubscribe link, or support request). 
await sms.optOuts.add('+14155551234');

​
Remove an opt-out

Removes a number from the opt-out list, re-enabling messages to that number. Only do this when the user has explicitly opted back in. 
await sms.optOuts.remove('+14155551234');

​
List phone numbers

Returns the phone numbers provisioned on your account (e.g. your toll-free number or simulator number). 
const numbers = await sms.numbers.list();

​
Error handling

The SDK throws typed errors so you can handle opt-out violations and other failures cleanly. 
import { SMSError, ValidationError, OptedOutError } from '@wraps.dev/sms';

try {
  await sms.send({ to: '+14155551234', message: 'Hello!' });
} catch (error) {
  if (error instanceof OptedOutError) {
    // The destination number is on the opt-out list
    console.log('User opted out:', error.phoneNumber);
  } else if (error instanceof ValidationError) {
    // The request was malformed (e.g. invalid phone number format)
    console.log('Invalid input:', error.field);
  } else if (error instanceof SMSError) {
    // An AWS-level error occurred
    console.log('AWS error:', error.code, error.retryable);
  }
}
Thrown when you attempt to send to a number that is on the opt-out list.
PropertyTypeDescription
phoneNumberstringThe opted-out phone number
messagestringHuman-readable error message
Thrown when request input is invalid, such as a phone number not in E.164 format or a missing required field.
PropertyTypeDescription
fieldstringThe field that failed validation
messagestringHuman-readable error message
Base error class for AWS End User Messaging errors. Covers quota limits, throttling, and infrastructure errors.
PropertyTypeDescription
codestringAWS error code
retryablebooleanWhether it is safe to retry the request
messagestringHuman-readable error message

​
Compliance best practices

  • Check before sending. Call sms.optOuts.check() before sending to any number you do not send to regularly, especially for re-engagement campaigns.
  • Honor opt-outs immediately. AWS automatically blocks messages to opted-out numbers, but syncing your own database ensures you don’t attempt sends that will fail.
  • Provide a clear opt-in. Only send to numbers where you have explicit written consent. Document how and when consent was obtained.
  • Respect QUIET_TIME. Avoid sending promotional messages late at night or early in the morning for the recipient’s time zone.
  • Identify your business. Include your company name in every message so recipients know who is contacting them.

Build docs developers (and LLMs) love

Get started for freeTalk to us