Pulumi

The @wraps.dev/pulumi package provides a WrapsEmail Pulumi ComponentResource that deploys SES infrastructure — IAM roles, configuration sets, event pipelines, and DNS records — directly into your Pulumi stack. Use it when you manage your AWS infrastructure with Pulumi.

If you prefer to deploy infrastructure with a single command rather than managing it in code, use the CLI instead. Both approaches deploy identical resources.

Installation

npm install @wraps.dev/pulumi

The package requires @pulumi/pulumi and @pulumi/aws, which your Pulumi project already provides:

npm install @pulumi/pulumi @pulumi/aws

Prerequisites

Node.js 20+
Pulumi 3.x CLI installed
@pulumi/aws 6.x or 7.x
AWS credentials configured

Quick start

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

// Minimal: Vercel OIDC
const email = new WrapsEmail('email', {
  vercel: {
    teamSlug: 'my-team',
    projectName: 'my-app',
  },
});

// Export the role ARN to set as an environment variable in Vercel
export const roleArn = email.roleArn;
export const configSetName = email.configSetName;

Deploy with:

pulumi up

Configuration options

Authentication

vercel

VercelOIDCConfig

Vercel OIDC configuration. Mutually exclusive with oidc.

Show VercelOIDCConfig fields

teamSlug

string

required

Your Vercel team slug.

projectName

string

required

Your Vercel project name.

oidc

OIDCConfig

Custom OIDC provider for GitHub Actions, GitLab CI, or other OIDC-compatible platforms. Mutually exclusive with vercel.

Show OIDCConfig fields

providerUrl

string

required

The OIDC provider URL, e.g. https://token.actions.githubusercontent.com.

audience

string

required

The audience claim, e.g. sts.amazonaws.com.

subjectPattern

string

required

Subject pattern to restrict which tokens can assume the role.

Domain

domain

string

Primary sending domain. Creates an SES domain identity with DKIM. DKIM tokens are exported as stack outputs for DNS configuration.

dns

DNSConfig

DNS provider configuration for automatic record creation. Supports Route53, Cloudflare, and Vercel.

Show Provider examples

// Route53
dns: { provider: 'route53', hostedZoneId: 'Z1234567890' }

// Cloudflare
dns: { provider: 'cloudflare', zoneId: 'abc123', apiToken: pulumi.secret('token') }

// Vercel
dns: { provider: 'vercel', apiToken: pulumi.secret('token'), teamId: 'team_xxx' }

mailFromSubdomain

string

default:"mail"

Subdomain for the MAIL FROM domain. Combined with domain — e.g. mail + example.com → mail.example.com.

Open/click tracking

tracking

TrackingConfig

Open and click tracking configuration.

Show TrackingConfig fields

enabled

boolean

default:"true"

Enable open and click tracking.

opens

boolean

default:"true"

Track email opens.

clicks

boolean

default:"true"

Track link clicks.

Event tracking

events

EventsConfig

Enables the event pipeline: EventBridge → SQS → Lambda → DynamoDB.

Show EventsConfig fields

types

SESEventType[]

Event types to capture. Options: SEND, DELIVERY, BOUNCE, COMPLAINT, OPEN, CLICK, RENDERING_FAILURE, DELIVERY_DELAY, SUBSCRIPTION.

storeHistory

boolean

default:"true"

Persist events to a DynamoDB table.

retention

string

default:"90days"

History retention period. One of 7days, 30days, 90days, 6months, 1year, unlimited.

Email settings

reputationMetrics

boolean

default:"true"

Enable SES reputation metrics in CloudWatch.

tlsRequired

boolean

default:"false"

Require TLS for all outbound connections.

sendingEnabled

boolean

default:"true"

Enable sending on the SES configuration set.

dedicatedIp

boolean

default:"false"

Provision a dedicated sending IP address. Adds approximately $25/month to AWS costs.

suppressionList

SuppressionListConfig

Bounce and complaint suppression.

Show SuppressionListConfig fields

enabled

boolean

default:"true"

Enable automatic suppression.

reasons

SuppressionReason[]

default:"['BOUNCE', 'COMPLAINT']"

Events that trigger suppression.

SMTP

smtp

SMTPConfig

Create an IAM user with SMTP credentials for legacy systems.

Show SMTPConfig fields

enabled

boolean

required

Set to true to provision SMTP credentials.

Transform functions

transform

TransformFunctions

Escape hatch to customize any underlying Pulumi resource before creation. Each function receives the default resource args and returns modified args.

const email = new WrapsEmail('email', {
  // ...
  transform: {
    // Switch DynamoDB to provisioned billing
    table: (args) => ({ ...args, billingMode: 'PROVISIONED' }),
    // Increase Lambda memory
    lambda: (args) => ({ ...args, memorySize: 1024 }),
  },
});

Available transform keys: role, oidcProvider, configSet, domainIdentity, table, queue, dlq, lambda, eventRule, certificate, distribution.

Output	Type	Description
`roleArn`	`Output<string>`	IAM role ARN for SDK authentication
`region`	`Output<string>`	AWS region
`configSetName`	`Output<string>`	SES configuration set name
`domain`	`Output<string \| undefined>`	Verified domain (if configured)
`mailFromDomain`	`Output<string \| undefined>`	MAIL FROM domain (if configured)
`dkimTokens`	`Output<string[] \| undefined>`	DKIM tokens for DNS configuration
`tableName`	`Output<string \| undefined>`	DynamoDB table name (if history enabled)
`queueUrl`	`Output<string \| undefined>`	SQS queue URL (if events enabled)
`dlqUrl`	`Output<string \| undefined>`	SQS dead-letter queue URL
`lambdaArn`	`Output<string \| undefined>`	Lambda function ARN (if history enabled)
`customTrackingDomain`	`Output<string \| undefined>`	Custom tracking domain (if configured)
`httpsTrackingEnabled`	`Output<boolean>`	Whether HTTPS tracking is enabled
`cloudFrontDomain`	`Output<string \| undefined>`	CloudFront distribution domain (if HTTPS tracking enabled)
`acmCertificateValidationRecords`	`Output<Array<...> \| undefined>`	ACM certificate validation records (if HTTPS tracking enabled)
`archiveArn`	`Output<string \| undefined>`	Mail Manager archive ARN (if archiving enabled)
`archivingEnabled`	`Output<boolean>`	Whether archiving is enabled
`smtpUserArn`	`Output<string \| undefined>`	SMTP IAM user ARN (if SMTP enabled)
`smtpEndpoint`	`Output<string \| undefined>`	SMTP endpoint (if SMTP enabled)
`smtpUsername`	`Output<string \| undefined>`	SMTP username — store securely
`smtpPassword`	`Output<string \| undefined>`	SMTP password — store securely
`envVars`	`Output<{ WRAPS_AWS_ROLE_ARN, WRAPS_AWS_REGION, WRAPS_CONFIG_SET? }>`	Convenience object with all env vars

smtpUsername and smtpPassword are shown once in pulumi up output. Store them in a secrets manager immediately — they cannot be retrieved again without rotating the access key.

Accessing underlying resources

All Pulumi resources are accessible via .nodes for advanced use cases:

const email = new WrapsEmail('email', { /* ... */ });

// Always present
email.nodes.role;       // aws.iam.Role
email.nodes.configSet;  // aws.ses.ConfigurationSet

// Present when events are configured
email.nodes.table;     // aws.dynamodb.Table
email.nodes.queue;     // aws.sqs.Queue
email.nodes.dlq;       // aws.sqs.Queue
email.nodes.lambda;    // aws.lambda.Function
email.nodes.eventRule; // aws.cloudwatch.EventRule

// Present when OIDC is configured
email.nodes.oidcProvider; // aws.iam.OpenIdConnectProvider

// Present when domain is configured
email.nodes.domainIdentity; // aws.ses.DomainIdentity
email.nodes.domainDkim;     // aws.ses.DomainDkim

// Present when SMTP is enabled
email.nodes.smtpUser;      // aws.iam.User
email.nodes.smtpAccessKey; // aws.iam.AccessKey

Full example program

import * as pulumi from '@pulumi/pulumi';
import { WrapsEmail } from '@wraps.dev/pulumi';

const email = new WrapsEmail('email', {
  // Vercel OIDC authentication
  vercel: {
    teamSlug: 'my-team',
    projectName: 'my-app',
  },

  // Domain with automatic Route53 DNS
  domain: 'example.com',
  dns: { provider: 'route53', hostedZoneId: 'Z1234567890ABCDEF' },
  mailFromSubdomain: 'mail',

  // Event tracking with 90-day history
  events: {
    types: ['SEND', 'DELIVERY', 'BOUNCE', 'COMPLAINT', 'OPEN', 'CLICK'],
    storeHistory: true,
    retention: '90days',
  },

  // Tag all resources
  tags: {
    Environment: 'production',
  },
});

// Export values to set as environment variables in your application
export const roleArn = email.roleArn;
export const region = email.region;
export const configSetName = email.configSetName;

// Or use the convenience object
export const envVars = email.envVars;

Email SDK

SMS SDK

IaC Integrations

Installation

Prerequisites

Quick start

Configuration options

Authentication

Domain

Open/click tracking

Event tracking

Email settings

SMTP

Transform functions

Tags

Outputs

Accessing underlying resources

Full example program

Build docs developers (and LLMs) love

Email SDK

SMS SDK

IaC Integrations

​Installation

​Prerequisites

​Quick start

​Configuration options

​Authentication

​Domain

​Open/click tracking

​Event tracking

​Email settings

​SMTP

​Transform functions

​Tags

​Outputs

​Accessing underlying resources

​Full example program

Build docs developers (and LLMs) love

Installation

Prerequisites

Quick start

Configuration options

Authentication

Domain

Open/click tracking

Event tracking

Email settings

SMTP

Transform functions

Tags

Outputs

Accessing underlying resources

Full example program