Skip to main content
The @wraps.dev/sms SDK lets you send SMS messages from your application using infrastructure you own in AWS. It authenticates with your AWS account using the same credential patterns as the email SDK — no Wraps credentials are stored.

​
Prerequisites

Before using the SDK, deploy SMS infrastructure to your AWS account: 
npx @wraps.dev/cli sms init
This provisions AWS End User Messaging resources (phone numbers, configuration sets, event tracking) in your account.

​
Installation

npm install @wraps.dev/sms

​
Quick example

import { WrapsSMS } from '@wraps.dev/sms';

const sms = new WrapsSMS();

const result = await sms.send({
  to: '+14155551234',
  message: 'Your verification code is 123456',
});

console.log('Sent:', result.messageId);
Phone numbers must be in E.164 format: a + followed by country code and number, e.g. +14155551234.

​
Authentication

The SDK resolves AWS credentials automatically. Choose the method that fits your deployment environment. When you construct WrapsSMS() with no arguments, the SDK resolves credentials in this order:
  1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
  2. ~/.aws/credentials file
  3. IAM role attached to the running compute (Lambda, EC2, ECS, etc.)
const sms = new WrapsSMS();
// Resolves: env vars → ~/.aws/credentials → IAM role

​
OIDC (Vercel, EKS, GitHub Actions)

For OIDC-based environments, pass the IAM role ARN created by wraps sms init. The SDK exchanges the OIDC token for temporary credentials automatically. 
const sms = new WrapsSMS({
  roleArn: process.env.AWS_ROLE_ARN,
});

​
Explicit credentials

Pass credentials directly. Use environment variables — never hard-code secrets. 
const sms = new WrapsSMS({
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
  region: 'us-east-1',
});

​
Constructor options

​
region
string
AWS region where your SMS infrastructure is deployed. Defaults to the region resolved from your AWS credentials or environment.
​
roleArn
string
IAM role ARN to assume via OIDC. Required when deploying to Vercel, GitHub Actions, or other OIDC-compatible environments.
​
credentials
object
Explicit AWS credentials. Provide accessKeyId and secretAccessKey. Use environment variables to avoid hard-coding secrets.

​
Next steps

Sending messages

Learn how to send single and batch SMS messages, including message types and sandbox mode.

Opt-out management

Check, add, and remove opt-outs to stay compliant with SMS regulations.

Build docs developers (and LLMs) love

Get started for freeTalk to us