@wraps.dev/email
Advanced tools
Send email via AWS SES with TypeScript. Bounce and complaint handling, suppression lists, delivery and open tracking, templates, batch sending, inbound email, attachments, and React Email support. Your AWS account, no vendor lock-in.
Beautiful email SDK for AWS SES with React.email support.
pnpm add @wraps.dev/email
import { WrapsEmail } from '@wraps.dev/email';
const email = new WrapsEmail({ region: 'us-east-1' });
await email.send({
from: 'you@company.com',
to: 'user@example.com',
subject: 'Welcome!',
html: '<h1>Hello World</h1>',
});
This package supports both CommonJS and ES Modules:
ESM (modern):
import { WrapsEmail } from '@wraps.dev/email';
CommonJS (Node.js):
const { WrapsEmail } = require('@wraps.dev/email');
The @wraps.dev/email/workers subpath is a zero-Node-APIs build (~5 KiB) that runs
on Cloudflare Workers, Deno Deploy, and any other workerd-based runtime. It uses
aws4fetch (Web Crypto) to sign requests and the SESv2 REST API (JSON payloads, no
DOMParser).
import { SESError, ValidationError, WrapsEmail } from '@wraps.dev/email/workers';
const email = new WrapsEmail({
region: env.AWS_REGION, // required — no credential chain at the edge
credentials: {
accessKeyId: env.AWS_ACCESS_KEY_ID,
secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
},
});
const result = await email.send({
from: 'hello@example.com',
to: 'user@example.com',
subject: 'Hello from the edge!',
html: '<h1>Hi there</h1>',
});
Both region and credentials are required — there is no AWS credential chain in a
Worker. Store them as Wrangler secrets:
wrangler secret put AWS_ACCESS_KEY_ID
wrangler secret put AWS_SECRET_ACCESS_KEY
from, to, cc, bcc, replyTo, subject, html, text, tags,
configurationSetName.
When html is provided without text, plain text is auto-generated (same as the
Node entry).
| Feature | Why | Alternative |
|---|---|---|
react | Requires react-dom/server (Node built-ins) | Render to HTML before calling send() |
attachments | MIME serialisation requires Buffer | Use the Node entry or pre-encode |
| Templates / inbox / events | Depend on @aws-sdk/* clients | Use the Node entry |
| Reply threading | Requires AWS SSM | Use the Node entry |
Scope the IAM key to ses:SendEmail only. Store credentials as Wrangler secrets
(never in wrangler.toml source). Rotate them periodically. For high-volume use,
consider enqueueing emails via a Cloudflare Queue rather than blocking the request
so transient SES errors don't surface to end users.
Wraps Email uses the AWS credential chain in the following order:
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)~/.aws/credentials)const email = new WrapsEmail({
credentials: {
accessKeyId: process.env.AWS_ACCESS_KEY_ID,
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
sessionToken: process.env.AWS_SESSION_TOKEN, // optional
},
region: 'us-west-2',
});
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=us-east-1
const email = new WrapsEmail(); // Credentials auto-detected
const result = await email.send({
from: 'you@company.com',
to: 'user@example.com',
subject: 'Welcome!',
html: '<h1>Hello World</h1>',
text: 'Hello World', // optional
});
console.log('Message ID:', result.messageId);
await email.send({
from: 'you@company.com',
to: ['user1@example.com', 'user2@example.com'],
cc: ['manager@company.com'],
bcc: ['archive@company.com'],
subject: 'Team Update',
html: '<p>Important announcement</p>',
});
import { EmailTemplate } from './emails/Welcome';
await email.send({
from: 'you@company.com',
to: 'user@example.com',
subject: 'Welcome to our platform',
react: <EmailTemplate name="John" orderId="12345" />,
});
Send emails with file attachments (PDFs, images, documents, etc.). The SDK automatically handles MIME encoding and uses AWS SES SendRawEmail under the hood.
// Single attachment
const result = await email.send({
from: 'you@company.com',
to: 'user@example.com',
subject: 'Your invoice',
html: '<p>Please find your invoice attached.</p>',
attachments: [
{
filename: 'invoice.pdf',
content: Buffer.from('...'), // Buffer or base64 string
contentType: 'application/pdf', // Optional - auto-detected from filename
},
],
});
// Multiple attachments
await email.send({
from: 'you@company.com',
to: 'user@example.com',
subject: 'Monthly Report',
html: '<h1>Monthly Report</h1><p>Reports attached</p>',
attachments: [
{
filename: 'report.pdf',
content: pdfBuffer,
contentType: 'application/pdf',
},
{
filename: 'chart.png',
content: imageBuffer,
contentType: 'image/png',
},
{
filename: 'data.csv',
content: csvBuffer,
contentType: 'text/csv',
},
],
});
// Attachment with base64 string
await email.send({
from: 'you@company.com',
to: 'user@example.com',
subject: 'Document',
html: '<p>Document attached</p>',
attachments: [
{
filename: 'document.pdf',
content: 'JVBERi0xLjQKJeLjz9MK...', // base64 string
contentType: 'application/pdf',
},
],
});
Supported attachment features:
await email.send({
from: 'you@company.com',
to: 'user@example.com',
subject: 'Newsletter',
html: '<p>Content</p>',
tags: {
campaign: 'newsletter-2025-01',
type: 'marketing',
},
});
When an agent or user replies to a message you sent, you need to know which conversation the reply belongs to — without trusting the From: address and without parsing In-Reply-To headers clients love to drop. Reply threading mints a signed Reply-To address per send (e.g. t_eyJ...@r.mail.yourapp.com). The Wraps-deployed inbound Lambda verifies the signature, extracts the conversation id, and publishes it on the email.received event so your handler can look up state in O(1).
Prerequisite: reply threading ships as part of the Wraps CLI inbound stack. Run wraps email reply init --domain yourapp.com once per sending domain — it provisions the signing secret in SSM, the r.mail.{domain} MX record, and the inbound Lambda that verifies tokens. See the Reply threading guide for the full CLI flow.
import { WrapsEmail } from '@wraps.dev/email';
const email = new WrapsEmail({
region: 'us-east-1',
replyThreading: {
// Defaults shown — all fields optional
parameterPrefix: '/wraps/email/reply-secret/', // SSM prefix written by the CLI
ttlSeconds: 90 * 86_400, // 90 days; 0 = infinite
cacheTtlMs: 5 * 60 * 1000, // per-domain secret cache
// replyDomain: 'r.mail.yourapp.com', // defaults to r.mail.{fromDomain}
},
});
One WrapsEmail instance handles any number of sending domains — the per-domain signing secret is fetched from SSM on first use and cached for cacheTtlMs.
const conversationId = email.replyThreading!.newConversation();
const result = await email.send({
from: 'agent@yourapp.com',
to: 'user@example.com',
subject: 'Re: your support request',
html: '<p>Hey — following up on your ticket.</p>',
conversationId,
});
// result.conversationId === conversationId
// result.sendId is a fresh 11-char id for this specific send
await saveThread({ conversationId: result.conversationId, sendId: result.sendId });
The SDK generates a signed Reply-To address and overrides ReplyToAddresses. Passing both replyTo and conversationId throws ValidationError — pick one.
To continue an existing conversation, reuse the id you stored from a prior send():
await email.send({
from: 'agent@yourapp.com',
to: 'user@example.com',
subject: 'Re: your support request',
html: '<p>Quick follow-up.</p>',
conversationId: existingThread.conversationId,
});
Both conversationId and sendId must be 11-character base64url strings (8 raw bytes). UUIDs and other formats will throw ValidationError. Generate them with the SDK:
import { generateConversationId, generateSendId } from '@wraps.dev/email';
const conversationId = generateConversationId(); // e.g. "a7F_2kQbNxR"
const sendId = generateSendId();
Or use the client helper: email.replyThreading!.newConversation().
The inbound Lambda (deployed by wraps email inbound init) verifies the token and emits an email.received event on EventBridge with a replyToken block:
// EventBridge target (Lambda, SQS consumer, etc.)
export async function handler(event: { detail: EmailReceivedDetail }) {
const { replyToken, from, subject, text } = event.detail;
if (replyToken?.status !== 'valid') {
// One of: 'invalid-signature' | 'expired' | 'unsupported-version'
// | 'malformed' | 'unknown-domain' | undefined (no token present)
await routeToFallbackInbox(event.detail);
return;
}
await appendReplyToThread({
conversationId: replyToken.conversationId,
inReplyToSendId: replyToken.sendId,
from: from.address,
body: text,
});
}
See the event shape reference for the full email.received payload.
Rotate with the CLI whenever you need to — the previous secret stays valid during the rotation window so in-flight replies keep verifying:
wraps email reply rotate --domain yourapp.com
SDK instances pick up the new secret within cacheTtlMs (default 5 minutes). No redeploy needed.
From: (SPF/DKIM/DMARC, or an explicit allow-list) before taking sensitive actions.expired. Pass replyTtlSeconds: 0 on send() for infinite-lifetime tokens, or override per-domain with replyThreading.ttlSeconds.sendId in your own store and reject duplicates.parameterPrefix) and multiple CLI reply init runs.SES templates allow you to store reusable email designs with variables in your AWS account.
await email.templates.create({
name: 'welcome-email',
subject: 'Welcome to {{companyName}}, {{name}}!',
html: `
<h1>Welcome {{name}}!</h1>
<p>Click to confirm: <a href="{{confirmUrl}}">Confirm Account</a></p>
`,
text: 'Welcome {{name}}! Click to confirm: {{confirmUrl}}',
});
await email.templates.createFromReact({
name: 'welcome-email-v2',
subject: 'Welcome to {{companyName}}, {{name}}!',
react: <WelcomeEmailTemplate />,
// React component should use {{variable}} syntax for SES placeholders
});
const result = await email.sendTemplate({
from: 'you@company.com',
to: 'user@example.com',
template: 'welcome-email',
templateData: {
name: 'John',
companyName: 'Acme Corp',
confirmUrl: 'https://app.com/confirm/abc123',
},
});
const results = await email.sendBulkTemplate({
from: 'you@company.com',
template: 'weekly-digest',
destinations: [
{
to: 'user1@example.com',
templateData: { name: 'Alice', unreadCount: 5 },
},
{
to: 'user2@example.com',
templateData: { name: 'Bob', unreadCount: 12 },
},
],
});
await email.templates.update({
name: 'welcome-email',
subject: 'Welcome aboard, {{name}}!',
html: '<h1>Welcome {{name}}!</h1>...',
});
const template = await email.templates.get('welcome-email');
console.log(template.name, template.subject);
const templates = await email.templates.list();
templates.forEach(t => console.log(t.name, t.createdTimestamp));
await email.templates.delete('welcome-email');
sendBatch() sends up to 100 recipients with unique subject/html/text per entry, inline — no pre-created SES template required (unlike sendBulkTemplate()). Partial failures are reported in the result, not thrown.
const result = await email.sendBatch({
from: 'hello@example.com',
entries: [
{ to: 'alice@example.com', subject: 'Hi Alice', html: '<p>Hello Alice!</p>' },
{ to: 'bob@example.com', subject: 'Hi Bob', html: '<p>Hello Bob!</p>' },
],
});
console.log(result.successCount, result.failureCount);
for (const entry of result.results) {
if (entry.status === 'failure') console.error(entry.index, entry.error);
}
Full reference: https://wraps.dev/docs/sdk-reference#send-batch
Check, add, remove, and list entries on the SES account-level suppression list. Always available (no config flag required).
const suppressed = await email.suppression.get('user@example.com');
if (!suppressed) {
await email.suppression.add('user@example.com', 'BOUNCE'); // or 'COMPLAINT'
}
await email.suppression.remove('user@example.com');
const { entries, nextToken } = await email.suppression.list();
Full reference: https://wraps.dev/docs/sdk-reference#suppression
Read inbound emails stored in S3 by the Wraps-deployed inbound Lambda. email.inbox is WrapsInbox | null — non-null only when inboxBucketName is configured.
const { emails } = await email.inbox!.list();
const full = await email.inbox!.get(emails[0].emailId);
const attachmentUrl = await email.inbox!.getAttachment(full.emailId, 'att_1');
await email.inbox!.reply(full.emailId, {
from: 'support@example.com',
html: '<p>Thanks for reaching out!</p>',
});
await email.inbox!.delete(full.emailId);
Full reference: https://wraps.dev/docs/sdk-reference#inbox
Query per-message delivery status from DynamoDB. email.events is WrapsEmailEvents | null — non-null only when historyTableName is configured.
const status = await email.events!.get(result.messageId); // sent/delivered/opened/clicked/bounced/complained/suppressed
const { emails } = await email.events!.list({ accountId: 'acct_123' });
Full reference: https://wraps.dev/docs/sdk-reference#events
import { WrapsEmailError, ValidationError, SESError } from '@wraps.dev/email';
try {
await email.send({ ... });
} catch (error) {
if (error instanceof ValidationError) {
// Invalid email address, missing required fields, etc.
console.error('Validation error:', error.message);
console.error('Field:', error.field);
} else if (error instanceof SESError) {
// AWS SES error (rate limit, unverified sender, etc.)
console.error('SES error:', error.message);
console.error('Code:', error.code); // 'MessageRejected', 'Throttling', etc.
console.error('Request ID:', error.requestId);
console.error('Retryable:', error.retryable);
} else {
// Other errors (network, auth, etc.)
console.error('Unknown error:', error);
}
}
WrapsEmailError is the catch-all base class every other email error extends —
useful for a single instanceof check that covers all of them.
BatchError is exported for type compatibility but is not currently thrown.
sendBatch() never throws on partial failure — it reports per-entry outcomes in
its resolved SendBatchResult instead. Always inspect the result:
const result = await email.sendBatch({ from, entries });
if (result.failureCount > 0) {
for (const entry of result.results) {
if (entry.status === 'failure') console.error(entry.index, entry.error);
}
}
interface WrapsEmailConfig {
// Pre-configured SES client for advanced authentication scenarios.
// Takes precedence over region, credentials, roleArn, and endpoint.
client?: SESClient;
// Pre-configured S3 client for inbox operations.
// Takes precedence over region/credentials for inbox.
s3Client?: S3Client;
// S3 bucket name for inbound email storage.
// When provided, enables the inbox API (email.inbox).
inboxBucketName?: string;
// AWS region for SES (defaults to us-east-1). Ignored if `client` is provided.
region?: string;
// AWS credentials — static or a credential provider (e.g. Vercel OIDC).
// Falls back to the AWS credential chain if omitted. Ignored if `client` is provided.
credentials?:
| { accessKeyId: string; secretAccessKey: string; sessionToken?: string }
| AwsCredentialIdentityProvider;
// IAM role ARN to assume via STS AssumeRole (OIDC federation, cross-account
// access). Ignored if `client` is provided.
roleArn?: string;
// Role session name for AssumeRole (defaults to 'wraps-email-session').
// Only used when roleArn is provided. Ignored if `client` is provided.
roleSessionName?: string;
// Custom SES endpoint, e.g. for LocalStack. Ignored if `client` is provided.
endpoint?: string;
// DynamoDB table name for email event history.
// When provided, enables the events API (email.events).
historyTableName?: string;
// Pre-configured DynamoDB DocumentClient for events.
// Takes precedence over region/credentials for events.
dynamodbClient?: DynamoDBDocumentClient;
// Pre-configured SES v2 client for the suppression list.
// Takes precedence over region/credentials for suppression.
sesv2Client?: SESv2Client;
// Enable signed reply-to threading (see "Reply threading" above).
// When set, send()/sendTemplate()/etc. accept `conversationId` to mint a
// signed reply-to address that the inbound Lambda verifies.
replyThreading?: ReplyThreadingConfig;
}
OIDC / cross-account setups: use roleArn (see packages/email/src/types.ts for the
full ReplyThreadingConfig shape used by replyThreading).
const email = new WrapsEmail({
region: 'us-east-1',
endpoint: 'http://localhost:4566',
});
WrapsEmailMain client class for sending emails via AWS SES.
send(params: SendEmailParams): Promise<SendEmailResult> - Send an emailsendBatch(params: SendBatchParams): Promise<SendBatchResult> - Send up to 100 recipients with unique content each (no pre-created template required)sendTemplate(params: SendTemplateParams): Promise<SendEmailResult> - Send using SES templatesendBulkTemplate(params: SendBulkTemplateParams): Promise<SendBulkTemplateResult> - Bulk send with templatetemplates.create(params: CreateTemplateParams): Promise<void> - Create SES templatetemplates.createFromReact(params: CreateTemplateFromReactParams): Promise<void> - Create template from Reacttemplates.update(params: UpdateTemplateParams): Promise<void> - Update templatetemplates.get(name: string): Promise<Template> - Get template detailstemplates.list(): Promise<TemplateMetadata[]> - List all templatestemplates.delete(name: string): Promise<void> - Delete templatesuppression.get(email: string): Promise<SuppressionEntry | null> - Check if an email is suppressedsuppression.add(email: string, reason: SuppressionReason): Promise<void> - Add an email to the suppression listsuppression.remove(email: string): Promise<void> - Remove an email from the suppression listsuppression.list(options?: SuppressionListOptions): Promise<SuppressionListResult> - List suppressed emailsinbox.list(options?: InboxListOptions): Promise<InboxListResult> - List inbound emails (when inboxBucketName is configured)inbox.get(emailId: string): Promise<InboxEmail> - Get a parsed inbound emailinbox.getAttachment(emailId, attachmentId, options?): Promise<string> - Presigned URL for an inbound attachmentinbox.getRaw(emailId: string): Promise<string> - Presigned URL for the raw MIME emailinbox.delete(emailId: string): Promise<void> - Delete an inbound email and its filesinbox.forward(emailId, options): Promise<SendEmailResult> - Forward an inbound emailinbox.reply(emailId, options): Promise<SendEmailResult> - Reply to an inbound emailevents.get(messageId: string): Promise<EmailStatus | null> - Get all events for a sent email (when historyTableName is configured)events.list(options: EmailListOptions): Promise<EmailListResult> - List emails with events for an accountdestroy(): void - Close SES client and clean up resourcesMIT
FAQs
Send email via AWS SES with TypeScript. Bounce and complaint handling, suppression lists, delivery and open tracking, templates, batch sending, inbound email, attachments, and React Email support. Your AWS account, no vendor lock-in.
The npm package @wraps.dev/email receives a total of 2,669 weekly downloads. As such, @wraps.dev/email popularity was classified as popular.
We found that @wraps.dev/email demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Company News
Socket is joining the OpenJS Security Stewardship Program to fund Node.js vulnerability research, maintainer remediation, and security releases.
Security News
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.