Email SDK Reference

Email SDK Reference | Wraps

SDK Reference

A TypeScript-first SDK for sending emails through your Wraps-deployed AWS SES infrastructure. Simple, type-safe, and intuitive API with React.email support.

Installation

Quick Start

Initialization

Create a new WrapsEmail client. The SDK automatically detects AWS credentials from your environment.

new WrapsEmail(config?: WrapsEmailConfig)

Options

region (optional): AWS region where your infrastructure is deployed. Defaults to us-east-1
credentials (optional): AWS credentials object. Auto-detected if not provided.
endpoint (optional): Custom SES endpoint (for testing with LocalStack).

Authentication Order

Explicit credentials passed to constructor
Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
Shared credentials file (~/.aws/credentials)
IAM role (EC2, ECS, Lambda)

Send Email

Send an email using AWS SES through your Wraps infrastructure.

email.send(params: SendEmailParams): Promise<SendEmailResult>

Parameters

Parameter	Type	Description
`from`	string	Sender email address (must be verified)
`to`	string \| string[]	Recipient email address(es)
`subject`	string	Email subject line
`html`	string	HTML email body (optional)
`text`	string	Plain text email body (optional)
`react`	ReactElement	React.email component (optional)
`attachments`	Attachment[]	File attachments (optional)
`tags`	Record<string, string>	SES message tags (optional)
`cc, bcc, replyTo`	string \| string[]	Additional recipients (optional)

Examples

React.email Support

Use React.email components for beautiful, type-safe email templates. The SDK automatically renders React components to HTML and plain text.

Attachments

Send emails with file attachments (PDFs, images, documents, etc.). The SDK automatically handles MIME encoding.

Attachment Options

Field	Type	Description
`filename`	string	Filename with extension
`content`	Buffer \| string	File content (Buffer or base64 string)
`contentType`	string	MIME type (optional - auto-detected from filename)

Limits

Maximum 100 attachments per email
Maximum message size: 10 MB (AWS SES limit)
Works with both HTML and React.email components

Template Management

SES templates allow you to store reusable email designs with variables in your AWS account.

Available Methods

Method	Description
`templates.create(params)`	Create a new SES template
`templates.createFromReact(params)`	Create template from React component
`templates.update(params)`	Update an existing template
`templates.get(name)`	Get template details
`templates.list()`	List all templates
`templates.delete(name)`	Delete a template

Send Template

Send an email using a pre-defined SES template. Templates support variable substitution using {{variable}} syntax.

email.sendTemplate(params: SendTemplateParams): Promise<SendEmailResult>

Send Bulk Template

Send personalized templated emails to multiple recipients (up to 50 per call). Each recipient can have unique template data merged with default values.

email.sendBulkTemplate(params: SendBulkTemplateParams): Promise<SendBulkTemplateResult>

Inbox (Inbound Emails)

Read, reply to, and forward inbound emails. Requires inbound email infrastructure to be deployed with wraps email inbound init.

Available Methods

Method	Description
`inbox.list(options?)`	List inbound emails with pagination
`inbox.get(emailId)`	Get full email details by ID
`inbox.reply(emailId, options)`	Reply with threading headers
`inbox.forward(emailId, options)`	Forward to new recipients
`inbox.getAttachment(emailId, attachmentId, options?)`	Get presigned URL for attachment
`inbox.getRaw(emailId)`	Get presigned URL for raw MIME email
`inbox.delete(emailId)`	Delete email and all associated files

Email Events

Track the delivery lifecycle of every email. Requires event tracking infrastructure deployed with wraps email init (Production or Enterprise preset).

Status Values

Status	Description
`sent`	Email accepted by SES
`delivered`	Email delivered to recipient's mail server
`opened`	Recipient opened the email (tracking pixel)
`clicked`	Recipient clicked a link in the email
`bounced`	Email bounced (hard or soft bounce)
`complained`	Recipient marked as spam
`suppressed`	Email suppressed by SES (on suppression list)

Negative statuses (bounced, complained, suppressed) always override positive ones. Status is derived from the highest-priority event.

Available Methods

Method	Description
`events.get(messageId)`	Get full status and event timeline for an email
`events.list(options)`	List emails with status, filtered by account and time range

Suppression List

Manage the SES account-level suppression list. Emails on this list are automatically blocked from sending. The suppression API is always available — no extra configuration needed.

Remove from Suppression List

Available Methods

Method	Description
`suppression.get(email)`	Check if an email is suppressed (returns null if not)
`suppression.add(email, reason)`	Add email to suppression list
`suppression.remove(email)`	Remove from suppression list (idempotent)
`suppression.list(options?)`	List suppressed emails with filters and pagination

Error Handling

The SDK throws typed errors for different failure scenarios.

Error	Description
`ValidationError`	Invalid input parameters (includes `field` property)
`SESError`	AWS SES error (includes `code`, `requestId`, `retryable` properties)
`DynamoDBError`	DynamoDB error from events API (includes `code`, `requestId`, `retryable` properties)

TypeScript Support

The SDK is written in TypeScript and provides full type safety out of the box.

SDK Defaults & Limits

Important defaults and limits to keep in mind:

No automatic retry on failure — implement your own retry logic if retryable is true
Default pagination: 20 items per page
Presigned URL expiry: 1 hour (for attachments)
Bulk send limit: 50 destinations per call
Attachment limit: 100 per email (10 MB total message size)

Next Steps

Check out the package on npm for the latest version and changelog.

View Package

Explore the source code, report issues, or contribute.

View Source

Learn how to build beautiful email templates with React.

Learn More