It works.
',\n});\n```\n\nRequesting production access to send to anyone else is an AWS support review;\nno SDK can do it for you.\n\nBoth a region mismatch and a sandbox block surface as the same AWS text —\n*\"Email address is not verified\"*. `send()` throws a `SandboxError` for that case\nwhose message names the region actually used and separates the two causes, so you\ndon't re-verify an identity that is already verified somewhere else.\n\nTo check where you stand:\n\n```bash\naws sesv2 get-account --regionImportant announcement
',\n});\n```\n\n### React.email Support\n\n```typescript\nimport { EmailTemplate } from './emails/Welcome';\n\nawait email.send({\n from: 'you@company.com',\n to: 'user@example.com',\n subject: 'Welcome to our platform',\n react:Please find your invoice attached.
',\n attachments: [\n {\n filename: 'invoice.pdf',\n content: Buffer.from('...'), // Buffer or base64 string\n contentType: 'application/pdf', // Optional - auto-detected from filename\n },\n ],\n});\n\n// Multiple attachments\nawait email.send({\n from: 'you@company.com',\n to: 'user@example.com',\n subject: 'Monthly Report',\n html: 'Reports attached
',\n attachments: [\n {\n filename: 'report.pdf',\n content: pdfBuffer,\n contentType: 'application/pdf',\n },\n {\n filename: 'chart.png',\n content: imageBuffer,\n contentType: 'image/png',\n },\n {\n filename: 'data.csv',\n content: csvBuffer,\n contentType: 'text/csv',\n },\n ],\n});\n\n// Attachment with base64 string\nawait email.send({\n from: 'you@company.com',\n to: 'user@example.com',\n subject: 'Document',\n html: 'Document attached
',\n attachments: [\n {\n filename: 'document.pdf',\n content: 'JVBERi0xLjQKJeLjz9MK...', // base64 string\n contentType: 'application/pdf',\n },\n ],\n});\n```\n\n**Supported attachment features:**\n- Automatic MIME type detection from file extension\n- Base64 encoding handled automatically\n- Up to 100 attachments per email\n- Maximum message size: 10 MB (AWS SES limit)\n- Works with both HTML and plain text emails\n- Compatible with React.email components\n\n### Send with tags (for SES tracking)\n\n```typescript\nawait email.send({\n from: 'you@company.com',\n to: 'user@example.com',\n subject: 'Newsletter',\n html: 'Content
',\n tags: {\n campaign: 'newsletter-2025-01',\n type: 'marketing',\n },\n});\n```\n\n## Reply threading\n\nWhen 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).\n\n**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](https://wraps.dev/docs/guides/reply-threading) for the full CLI flow.\n\n### Configure the client\n\n```typescript\nimport { WrapsEmail } from '@wraps.dev/email';\n\nconst email = new WrapsEmail({\n region: 'us-east-1',\n replyThreading: {\n // Defaults shown — all fields optional\n parameterPrefix: '/wraps/email/reply-secret/', // SSM prefix written by the CLI\n ttlSeconds: 90 * 86_400, // 90 days; 0 = infinite\n cacheTtlMs: 5 * 60 * 1000, // per-domain secret cache\n // replyDomain: 'r.mail.yourapp.com', // defaults to r.mail.{fromDomain}\n },\n});\n```\n\nOne `WrapsEmail` instance handles any number of sending domains — the per-domain signing secret is fetched from SSM on first use and cached for `cacheTtlMs`.\n\n### Send a threaded message\n\n```typescript\nconst conversationId = email.replyThreading!.newConversation();\n\nconst result = await email.send({\n from: 'agent@yourapp.com',\n to: 'user@example.com',\n subject: 'Re: your support request',\n html: 'Hey — following up on your ticket.
',\n conversationId,\n});\n\n// result.conversationId === conversationId\n// result.sendId is a fresh 11-char id for this specific send\nawait saveThread({ conversationId: result.conversationId, sendId: result.sendId });\n```\n\nThe SDK generates a signed `Reply-To` address and overrides `ReplyToAddresses`. Passing both `replyTo` and `conversationId` throws `ValidationError` — pick one.\n\nTo continue an existing conversation, reuse the id you stored from a prior `send()`:\n\n```typescript\nawait email.send({\n from: 'agent@yourapp.com',\n to: 'user@example.com',\n subject: 'Re: your support request',\n html: 'Quick follow-up.
',\n conversationId: existingThread.conversationId,\n});\n```\n\n### ID format\n\nBoth `conversationId` and `sendId` must be 11-character base64url strings (8 raw bytes). UUIDs and other formats will throw `ValidationError`. Generate them with the SDK:\n\n```typescript\nimport { generateConversationId, generateSendId } from '@wraps.dev/email';\n\nconst conversationId = generateConversationId(); // e.g. \"a7F_2kQbNxR\"\nconst sendId = generateSendId();\n```\n\nOr use the client helper: `email.replyThreading!.newConversation()`.\n\n### Handle incoming replies\n\nThe inbound Lambda (deployed by `wraps email inbound init`) verifies the token and emits an `email.received` event on EventBridge with a `replyToken` block:\n\n```typescript\n// EventBridge target (Lambda, SQS consumer, etc.)\nexport async function handler(event: { detail: EmailReceivedDetail }) {\n const { replyToken, from, subject, text } = event.detail;\n\n if (replyToken?.status !== 'valid') {\n // One of: 'invalid-signature' | 'expired' | 'unsupported-version'\n // | 'malformed' | 'unknown-domain' | undefined (no token present)\n await routeToFallbackInbox(event.detail);\n return;\n }\n\n await appendReplyToThread({\n conversationId: replyToken.conversationId,\n inReplyToSendId: replyToken.sendId,\n from: from.address,\n body: text,\n });\n}\n```\n\nSee the [event shape reference](https://wraps.dev/docs/infrastructure/events) for the full `email.received` payload.\n\n### Rotating the signing secret\n\nRotate with the CLI whenever you need to — the previous secret stays valid during the rotation window so in-flight replies keep verifying:\n\n```bash\nwraps email reply rotate --domain yourapp.com\n```\n\nSDK instances pick up the new secret within `cacheTtlMs` (default 5 minutes). No redeploy needed.\n\n### Honest limits\n\n- **Verified ≠ sender identity.** A valid token proves the reply came back to an address you minted — it does not prove who sent it. Verify `From:` (SPF/DKIM/DMARC, or an explicit allow-list) before taking sensitive actions.\n- **Default TTL is 90 days.** Tokens older than that verify as `expired`. Pass `replyTtlSeconds: 0` on `send()` for infinite-lifetime tokens, or override per-domain with `replyThreading.ttlSeconds`.\n- **No replay defense in v1.** The same signed address will verify repeatedly until it expires. If you need single-use semantics, track `sendId` in your own store and reject duplicates.\n- **One secret per domain.** Multiple sending domains mean multiple SSM parameters (all under `parameterPrefix`) and multiple CLI `reply init` runs.\n\n## Template Management\n\nSES templates allow you to store reusable email designs with variables in your AWS account.\n\n### Create a template\n\n```typescript\nawait email.templates.create({\n name: 'welcome-email',\n subject: 'Welcome to {{companyName}}, {{name}}!',\n html: `\nClick to confirm: Confirm Account
\n `,\n text: 'Welcome {{name}}! Click to confirm: {{confirmUrl}}',\n});\n```\n\n### Create template from React.email component\n\n```typescript\nawait email.templates.createFromReact({\n name: 'welcome-email-v2',\n subject: 'Welcome to {{companyName}}, {{name}}!',\n react:Hello Alice!
' },\n { to: 'bob@example.com', subject: 'Hi Bob', html: 'Hello Bob!
' },\n ],\n});\n\nconsole.log(result.successCount, result.failureCount);\nfor (const entry of result.results) {\n if (entry.status === 'failure') console.error(entry.index, entry.error);\n}\n```\n\nFull reference: https://wraps.dev/docs/sdk-reference#send-batch\n\n## Suppression List\n\nCheck, add, remove, and list entries on the SES account-level suppression list. Always available (no config flag required).\n\n```typescript\nconst suppressed = await email.suppression.get('user@example.com');\nif (!suppressed) {\n await email.suppression.add('user@example.com', 'BOUNCE'); // or 'COMPLAINT'\n}\nawait email.suppression.remove('user@example.com');\nconst { entries, nextToken } = await email.suppression.list();\n```\n\nFull reference: https://wraps.dev/docs/sdk-reference#suppression\n\n## Inbox\n\nRead inbound emails stored in S3 by the Wraps-deployed inbound Lambda. `email.inbox` is `WrapsInbox | null` — non-null only when `inboxBucketName` is configured.\n\n```typescript\nconst { emails } = await email.inbox!.list();\nconst full = await email.inbox!.get(emails[0].emailId);\nconst attachmentUrl = await email.inbox!.getAttachment(full.emailId, 'att_1');\nawait email.inbox!.reply(full.emailId, {\n from: 'support@example.com',\n html: 'Thanks for reaching out!
',\n});\nawait email.inbox!.delete(full.emailId);\n```\n\nFull reference: https://wraps.dev/docs/sdk-reference#inbox\n\n## Event History\n\nQuery per-message delivery status from DynamoDB. `email.events` is `WrapsEmailEvents | null` — non-null only when `historyTableName` is configured.\n\n```typescript\nconst status = await email.events!.get(result.messageId); // sent/delivered/opened/clicked/bounced/complained/suppressed\nconst { emails } = await email.events!.list({ accountId: 'acct_123' });\n```\n\nFull reference: https://wraps.dev/docs/sdk-reference#events\n\n## Error Handling\n\n```typescript\nimport { WrapsEmailError, ValidationError, SESError } from '@wraps.dev/email';\n\ntry {\n await email.send({ ... });\n} catch (error) {\n if (error instanceof ValidationError) {\n // Invalid email address, missing required fields, etc.\n console.error('Validation error:', error.message);\n console.error('Field:', error.field);\n } else if (error instanceof SESError) {\n // AWS SES error (rate limit, unverified sender, etc.)\n console.error('SES error:', error.message);\n console.error('Code:', error.code); // 'MessageRejected', 'Throttling', etc.\n console.error('Request ID:', error.requestId);\n console.error('Retryable:', error.retryable);\n } else {\n // Other errors (network, auth, etc.)\n console.error('Unknown error:', error);\n }\n}\n```\n\n`WrapsEmailError` is the catch-all base class every other email error extends —\nuseful for a single `instanceof` check that covers all of them. That includes\ncredential failures: an unresolvable credential chain throws `CredentialsError`,\nnot the AWS SDK's own error type.\n\n```typescript\nimport { CredentialsError, SandboxError } from '@wraps.dev/email';\n\ntry {\n await email.send({ ... });\n} catch (error) {\n if (error instanceof CredentialsError) {\n // Nothing was sent — the credential chain came up empty. The message lists\n // every way to supply credentials (SSO, access keys, env vars, AWS_PROFILE,\n // or passing them to the constructor).\n console.error(error.message);\n } else if (error instanceof SandboxError) {\n // SES rejected the send: the identity is not verified in the region used.\n // Either the region is wrong or the account is sandboxed — error.message\n // walks through both, and error.region names the region actually used.\n console.error(error.region, error.message);\n }\n}\n```\n\n`SandboxError` extends `SESError`, so existing `instanceof SESError` handling\nkeeps working unchanged.\n\n`sendBatch()` never throws on send failure — partial *and* total failures come\nback as per-entry outcomes in its resolved `SendBatchResult`, including\nchunk-level SES errors. Only input validation throws. Always inspect the result:\n\n```typescript\nconst result = await email.sendBatch({ from, entries });\nif (result.failureCount > 0) {\n for (const entry of result.results) {\n if (entry.status === 'failure') console.error(entry.index, entry.error);\n }\n}\n```\n\n## Configuration Options\n\n```typescript\ninterface WrapsEmailConfig {\n // Pre-configured SES client for advanced authentication scenarios.\n // Takes precedence over region, credentials, roleArn, and endpoint.\n client?: SESClient;\n\n // Pre-configured S3 client for inbox operations.\n // Takes precedence over region/credentials for inbox.\n s3Client?: S3Client;\n\n // S3 bucket name for inbound email storage.\n // When provided, enables the inbox API (email.inbox).\n inboxBucketName?: string;\n\n // AWS region for SES. When omitted, resolved from AWS_REGION, then\n // AWS_DEFAULT_REGION, then the active profile, then us-east-1 as a last\n // resort. Ignored if `client` is provided.\n region?: string;\n\n // AWS credentials — static or a credential provider (e.g. Vercel OIDC).\n // Falls back to the AWS credential chain if omitted. Ignored if `client` is provided.\n credentials?:\n | { accessKeyId: string; secretAccessKey: string; sessionToken?: string }\n | AwsCredentialIdentityProvider;\n\n // IAM role ARN to assume via STS AssumeRole (OIDC federation, cross-account\n // access). Ignored if `client` is provided.\n roleArn?: string;\n\n // Role session name for AssumeRole (defaults to 'wraps-email-session').\n // Only used when roleArn is provided. Ignored if `client` is provided.\n roleSessionName?: string;\n\n // Custom SES endpoint, e.g. for LocalStack. Ignored if `client` is provided.\n endpoint?: string;\n\n // DynamoDB table name for email event history.\n // When provided, enables the events API (email.events).\n historyTableName?: string;\n\n // Pre-configured DynamoDB DocumentClient for events.\n // Takes precedence over region/credentials for events.\n dynamodbClient?: DynamoDBDocumentClient;\n\n // Pre-configured SES v2 client for the suppression list.\n // Takes precedence over region/credentials for suppression.\n sesv2Client?: SESv2Client;\n\n // Enable signed reply-to threading (see \"Reply threading\" above).\n // When set, send()/sendTemplate()/etc. accept `conversationId` to mint a\n // signed reply-to address that the inbound Lambda verifies.\n replyThreading?: ReplyThreadingConfig;\n}\n```\n\nOIDC / cross-account setups: use `roleArn` (see `packages/email/src/types.ts` for the\nfull `ReplyThreadingConfig` shape used by `replyThreading`).\n\n## Testing with LocalStack\n\n```typescript\nconst email = new WrapsEmail({\n region: 'us-east-1',\n endpoint: 'http://localhost:4566',\n});\n```\n\n## API Reference\n\n### `WrapsEmail`\n\nMain client class for sending emails via AWS SES.\n\n#### Methods\n\n- `send(params: SendEmailParams): Promise