Skip to main content
The @wraps.dev/email SDK lets you send transactional email through AWS SES infrastructure that you deployed with wraps email init. Your AWS account owns all the resources — Wraps never stores your credentials or touches your data.
You must deploy email infrastructure before using this SDK. Run npx @wraps.dev/cli email init first.

​
Installation

npm install @wraps.dev/email

​
Prerequisites

  • Email infrastructure deployed via wraps email init
  • A verified domain (run wraps email domains verify -d yourdomain.com to confirm)
  • AWS credentials available in your environment

​
Quick start

import { WrapsEmail } from '@wraps.dev/email';

const email = new WrapsEmail({ region: 'us-east-1' });

const result = await email.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Welcome!',
  html: '<h1>Hello from Wraps!</h1>',
});

console.log('Sent:', result.messageId);

​
Authentication

The SDK resolves credentials using one of three methods. Use the default credential chain unless you have a specific reason to pass credentials explicitly. Pass no credentials. The SDK resolves them automatically in order: environment variables → ~/.aws/credentials → IAM role attached to the instance or container. 
import { WrapsEmail } from '@wraps.dev/email';

const email = new WrapsEmail();

​
2. OIDC for Vercel, EKS, or GitHub Actions

Pass a roleArn to have the SDK assume an IAM role using OIDC. This is the recommended approach for Vercel deployments and Kubernetes workloads. 
import { WrapsEmail } from '@wraps.dev/email';

const email = new WrapsEmail({
  roleArn: process.env.AWS_ROLE_ARN,
});
Set WRAPS_EMAIL_ROLE_ARN to the role ARN output by wraps email init. See the OIDC guide for Vercel for a full setup walkthrough.

​
3. Explicit credentials

Pass credentials directly. Useful for local testing or environments where the credential chain is unavailable. 
import { WrapsEmail } from '@wraps.dev/email';

const email = new WrapsEmail({
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
  region: 'us-east-1',
});
Never hardcode credentials in source code. Always read them from environment variables.

​
Constructor options

​
region
string
AWS region where your SES infrastructure is deployed (e.g. 'us-east-1'). Defaults to the AWS_REGION environment variable.
​
roleArn
string
ARN of an IAM role to assume via OIDC before sending. Use this for Vercel, EKS, or GitHub Actions deployments.
​
credentials
object
Explicit AWS credentials. Provide both accessKeyId and secretAccessKey. Optionally include sessionToken for temporary credentials.
​
client
SESClient
A pre-configured SESClient instance from @aws-sdk/client-ses. Use this when you need full control over the SES client, such as in two-step OIDC role assumption flows.

​
Next steps

Sending

Send emails with HTML, plain text, React components, and attachments.

Templates

Create reusable SES templates and send bulk email.

Error handling

Handle validation errors, SES errors, and common failure modes.

Build docs developers (and LLMs) love

Get started for freeTalk to us