typedmailer 1.4.0 → 2.1.0

package/dist/webhooks/normalize.d.ts

@@ -1,5 +1,5 @@
 import type { EmailWebhookEvent } from './types.js';
-export declare function normalizeResend(payload: unknown): readonly EmailWebhookEvent[];
+export declare function normalizeResend(payload: unknown, maxRecipients?: number): readonly EmailWebhookEvent[];
 export declare function normalizeMailgun(payload: unknown): readonly EmailWebhookEvent[];
 export declare function normalizeSendGrid(payload: unknown, maxEvents: number): readonly EmailWebhookEvent[];
 export declare function normalizeSes(payload: unknown, maxEvents: number): readonly EmailWebhookEvent[];

package/dist/webhooks/normalize.js

@@ -1,8 +1,12 @@
 import { WebhookVerificationError } from './types.js';
 import { asId, asOptionalRecord, asRecord, asString, asStringArray, firstString, isString, parseDate, } from './shared.js';
-export function normalizeResend(payload) {
+export function normalizeResend(payload, maxRecipients = 1_000) {
     const root = asRecord(payload);
     const data = asRecord(root.data);
+    const singleRecipient = asString(data.to);
+    const recipients = singleRecipient ? [singleRecipient] : asStringArray(data.to);
+    if ((Array.isArray(data.to) && data.to.length > maxRecipients) || recipients.length > maxRecipients)
+        throw new WebhookVerificationError('invalid_payload');
     return [
         makeEvent('resend', root, {
             id: asString(root.id),
@@ -10,6 +14,7 @@ export function normalizeResend(payload) {
             type: mapEventType(asString(root.type)),
             messageId: asString(data.email_id),
             recipient: firstString(data.to),
+            ...(recipients.length ? { recipients } : {}),
             occurredAt: parseDate(root.created_at),
         }),
     ];
@@ -66,6 +71,14 @@ export function normalizeSes(payload, maxEvents) {
     }
     const to = recipients.map((recipient) => asString(asRecord(recipient).emailAddress)).filter(isString);
     const emails = to.length > 0 ? to : asStringArray(mail.destination);
+    if (emails.length > maxEvents)
+        throw new WebhookVerificationError('invalid_payload');
+    const occurredAt = parseDate(delivery?.timestamp) ??
+        parseDate(bounce?.timestamp) ??
+        parseDate(complaint?.timestamp) ??
+        parseDate(asOptionalRecord(message.deliveryDelay)?.timestamp) ??
+        parseDate(asOptionalRecord(message.reject)?.timestamp) ??
+        parseDate(mail.timestamp);
     return emails.length > 0
         ? emails.map((recipient) => makeEvent('ses', message, {
             id: asString(message.messageId),
@@ -73,7 +86,7 @@ export function normalizeSes(payload, maxEvents) {
             type: mapEventType(eventName),
             messageId: asString(mail.messageId),
             recipient,
-            occurredAt: parseDate(delivery?.timestamp) ?? parseDate(bounce?.timestamp),
+            occurredAt,
         }))
         : [
             makeEvent('ses', message, {
@@ -81,7 +94,7 @@ export function normalizeSes(payload, maxEvents) {
                 eventType: eventName,
                 type: mapEventType(eventName),
                 messageId: asString(mail.messageId),
-                occurredAt: parseDate(asRecord(message.delivery).timestamp),
+                occurredAt,
             }),
         ];
 }
@@ -96,6 +109,7 @@ export function normalizeProviderEvents(provider, payload, maxEvents) {
             id: provider === 'brevo'
                 ? (asId(event.id) ?? asString(event['message-id']))
                 : (asId(event.ID) ?? asString(event.MessageID)),
+            eventId: provider === 'brevo' ? asId(event.id) : asId(event.ID),
             eventType: eventName,
             type: mapEventType(eventName),
             messageId: provider === 'brevo' ? asString(event['message-id']) : asString(event.MessageID),
@@ -107,12 +121,15 @@ export function normalizeProviderEvents(provider, payload, maxEvents) {
 function makeEvent(provider, raw, fields) {
     if (!fields.eventType)
         throw new WebhookVerificationError('invalid_payload');
+    const eventId = fields.eventId ?? (provider !== 'brevo' && provider !== 'postmark' && provider !== 'ses' ? fields.id : undefined);
     return {
         provider,
         raw,
         eventType: fields.eventType,
         type: fields.type,
         ...(fields.id ? { id: fields.id } : {}),
+        ...(eventId ? { eventId } : {}),
+        ...(fields.recipients ? { recipients: fields.recipients } : {}),
         ...(fields.messageId ? { messageId: fields.messageId } : {}),
         ...(fields.recipient ? { recipient: fields.recipient } : {}),
         ...(fields.occurredAt ? { occurredAt: fields.occurredAt } : {}),

package/dist/webhooks/signatures.d.ts

@@ -1,7 +1,7 @@
 import type { VerifyWebhookInput } from './types.js';
 export declare function verifyResend(input: Extract<VerifyWebhookInput, {
     provider: 'resend';
-}>, rawBody: Uint8Array): void;
+}>, rawBody: Uint8Array): string;
 export declare function verifyMailgun(input: Extract<VerifyWebhookInput, {
     provider: 'mailgun';
 }>, payload: unknown): void;
@@ -13,4 +13,7 @@ export declare function verifyAuthorization(input: Extract<VerifyWebhookInput, {
 }>, headerName: string): void;
 export declare function verifySnsNotification(input: Extract<VerifyWebhookInput, {
     provider: 'ses';
-}>, payload: unknown): Promise<unknown>;
+}>, payload: unknown): Promise<{
+    readonly payload: unknown;
+    readonly deliveryId: string;
+}>;

package/dist/webhooks/signatures.js

@@ -24,6 +24,7 @@ export function verifyResend(input, rawBody) {
         .some((item) => item.startsWith('v1,') && safeEqual(expected, decodeBase64(item.slice(3))));
     if (!matches)
         throw new WebhookVerificationError('invalid_signature');
+    return messageId;
 }
 export function verifyMailgun(input, payload) {
     const root = asRecord(payload);
@@ -73,7 +74,8 @@ export async function verifySnsNotification(input, payload) {
     const signingCertUrl = asString(envelope.SigningCertURL);
     const signature = asString(envelope.Signature);
     const signatureVersion = asString(envelope.SignatureVersion);
-    if (envelope.Type !== 'Notification' ||
+    if (!asString(envelope.MessageId) ||
+        envelope.Type !== 'Notification' ||
         topicArn !== input.topicArn ||
         !signingCertUrl ||
         !signature ||
@@ -114,13 +116,32 @@ export async function verifySnsNotification(input, payload) {
         throw new WebhookVerificationError('invalid_signature');
     let certificateBody;
     try {
-        certificateBody = await response.text();
+        if (!response.body)
+            throw new WebhookVerificationError('invalid_signature');
+        const reader = response.body.getReader();
+        const chunks = [];
+        let length = 0;
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                length += value.byteLength;
+                if (length > 32_768) {
+                    await reader.cancel();
+                    throw new WebhookVerificationError('invalid_signature');
+                }
+                chunks.push(value);
+            }
+            certificateBody = Buffer.concat(chunks, length).toString('utf8');
+        }
+        finally {
+            reader.releaseLock();
+        }
     }
     catch {
         throw new WebhookVerificationError('invalid_signature');
     }
-    if (certificateBody.length > 32_768)
-        throw new WebhookVerificationError('invalid_signature');
     try {
         const certificate = new X509Certificate(certificateBody);
         const now = input.now ?? new Date();
@@ -144,7 +165,7 @@ export async function verifySnsNotification(input, payload) {
     }
     try {
         const message = JSON.parse(asString(envelope.Message) ?? '');
-        return message;
+        return { payload: message, deliveryId: asString(envelope.MessageId) };
     }
     catch {
         throw new WebhookVerificationError('invalid_payload');

package/dist/webhooks/types.d.ts

@@ -2,11 +2,18 @@ export type ProviderName = import('../types.js').ProviderName;
 export type EmailWebhookEventType = 'accepted' | 'delivered' | 'bounced' | 'complained' | 'delayed' | 'opened' | 'clicked' | 'unsubscribed' | 'rejected' | 'failed' | 'other';
 export interface EmailWebhookEvent {
     readonly provider: Exclude<ProviderName, 'smtp'>;
+    /** Legacy provider identifier; may fall back to the email message ID. */
     readonly id?: string;
+    /** Provider event ID, without a message-ID fallback. */
+    readonly eventId?: string;
+    /** Authenticated transport notification ID (Resend/SNS). Shared by events in one notification. */
+    readonly deliveryId?: string;
     readonly type: EmailWebhookEventType;
     readonly eventType: string;
     readonly messageId?: string;
     readonly recipient?: string;
+    /** All Resend recipients; recipient retains the first address for compatibility. */
+    readonly recipients?: readonly string[];
     readonly occurredAt?: Date;
     /** Original provider data. It can contain message metadata and personal information. */
     readonly raw: unknown;

package/dist/webhooks.js

@@ -24,9 +24,10 @@ export async function verifyWebhook(input) {
         throw new WebhookVerificationError('invalid_payload');
     }
     switch (input.provider) {
-        case 'resend':
-            verifyResend(input, rawBody);
-            return normalizeResend(payload);
+        case 'resend': {
+            const deliveryId = verifyResend(input, rawBody);
+            return normalizeResend(payload, maxEvents).map((event) => ({ ...event, deliveryId }));
+        }
         case 'mailgun':
             verifyMailgun(input, payload);
             return normalizeMailgun(payload);
@@ -37,7 +38,12 @@ export async function verifyWebhook(input) {
         case 'postmark':
             verifyAuthorization(input, input.authorizationHeader ?? 'authorization');
             return normalizeProviderEvents(input.provider, payload, maxEvents);
-        case 'ses':
-            return normalizeSes(await verifySnsNotification(input, payload), maxEvents);
+        case 'ses': {
+            const notification = await verifySnsNotification(input, payload);
+            return normalizeSes(notification.payload, maxEvents).map((event) => ({
+                ...event,
+                deliveryId: notification.deliveryId,
+            }));
+        }
     }
 }

package/docs/framework-webhooks.md

@@ -0,0 +1,60 @@
+# Next.js and Express webhook routes
+
+The repository includes TypeScript Resend webhook examples in `examples/webhooks/`. Copy the appropriate adapter and `shared.ts` into your application. These files are examples, not new package exports; they depend on `typedmailer/webhooks`, and the Express adapter additionally needs `express` and its TypeScript types.
+
+Both examples preserve the exact signed request bytes, limit the raw body to 1 MiB, authenticate with the endpoint signing secret, and await `acceptEvents()` before returning HTTP 204. Implement that callback with a durable inbox or queue: store a stable provider event key under a unique constraint and commit atomically. Duplicate deliveries should resolve successfully after confirming the prior durable acceptance. The callback's second argument supplies `deliveryId` from Resend's authenticated `svix-id` header; use it with the provider name as an inbox uniqueness key. Normalized event IDs are optional. Keep business processing in your worker.
+
+The examples return 400 for malformed event payloads, 401 for failed signatures, 413 for oversized bodies, and 503 for acceptance failures. The Express adapter also returns 415 for unsupported content types or compressed requests. Upstream proxies and hosting platforms should enforce matching request-size and timeout limits.
+
+## Next.js App Router
+
+Copy `nextjs.ts` and `shared.ts` into `lib/webhooks/`, then create `app/api/webhooks/resend/route.ts`:
+
+```ts
+import { createResendWebhookHandler } from '@/lib/webhooks/nextjs';
+import { acceptEmailEvents } from '@/lib/email-event-inbox';
+
+export const runtime = 'nodejs';
+
+const webhookSecret = process.env.RESEND_WEBHOOK_SECRET;
+if (!webhookSecret) throw new Error('RESEND_WEBHOOK_SECRET is required.');
+
+export const POST = createResendWebhookHandler({
+  webhookSecret,
+  acceptEvents: acceptEmailEvents,
+});
+```
+
+`acceptEmailEvents` is your application's durable ingestion function. It receives `readonly EmailWebhookEvent[]` and `{ deliveryId: string }`, and resolves after the transaction or durable queue write succeeds. The adapter uses a standard Web `Request` and `Response`, so it does not need to import Next.js. Its streaming reader checks actual received bytes even when `Content-Length` is absent or inaccurate.
+
+## Express
+
+Copy `express.ts` and `shared.ts` into your application, then mount the router before the global JSON parser:
+
+```ts
+import express from 'express';
+import { createResendWebhookRouter } from './webhooks/express.js';
+import { acceptEmailEvents } from './email-event-inbox.js';
+
+const webhookSecret = process.env.RESEND_WEBHOOK_SECRET;
+if (!webhookSecret) throw new Error('RESEND_WEBHOOK_SECRET is required.');
+
+const app = express();
+app.use(
+  '/webhooks/resend',
+  createResendWebhookRouter({
+    webhookSecret,
+    acceptEvents: acceptEmailEvents,
+  }),
+);
+app.use(express.json());
+app.listen(3000);
+```
+
+Do not mount `express.json()` before the webhook router. Parsed and reserialized JSON does not preserve the signed bytes. The route uses `express.raw()` with a finite byte limit and disables decompression to retain the exact raw input.
+
+## Verification
+
+`tests/webhook-examples.test.ts` exercises signed and tampered requests, body limits, invalid JSON, and failed durable acceptance. Express tests use an ephemeral local HTTP server. SDK and webhook tests never send real emails. CI separately verifies SMTP through Mailpit.
+
+References: [Next.js Route Handlers](https://nextjs.org/docs/app/api-reference/file-conventions/route), [Express raw parser](https://expressjs.com/en/5x/api.html#express.raw), and [Resend webhook verification](https://resend.com/docs/webhooks/introduction).

package/docs/migration-v2.md

@@ -0,0 +1,35 @@
+# Migrating from v1 to v2
+
+TypedMailer 2 retains the shared `createMailer()` / `send()` API, lazy optional SDK loading, Node.js 22+ support, and AWS credential chain. It tightens configuration contracts and corrects provider attachment serialization.
+
+## Provider SDKs
+
+Amazon SES now requires `@aws-sdk/client-sesv2 >=3.797.0 <4`. Older versions can silently omit `Simple.Headers` and `Simple.Attachments` when serializing requests. Upgrade your installed SDK and lockfile:
+
+```sh
+npm install typedmailer@^2 @aws-sdk/client-sesv2@^3.797.0
+```
+
+Other provider SDK peer ranges are unchanged. Install only the SDKs your application uses.
+
+## Configuration validation
+
+Built-in provider options now reject unknown keys, matching custom provider configuration and message validation. Pass only the documented fields rather than spreading an application-wide configuration object. For example, a misspelled `apiToken` is rejected rather than ignored.
+
+Named senders such as `App <sender@example.com>` validate the enclosed email address using the same validation as plain and object addresses. `App <a@b>`, blank display names in named strings, and line breaks in display names are rejected. The configured sender is validated immediately in `createTestMailer()` as well as `createMailer()`. Valid email strings and `{ email, name }` objects remain supported. Validation failures remain Zod errors; transport failures remain `MailError` instances.
+
+## Attachments
+
+Attachment strings represent UTF-8 file content for every adapter; `Uint8Array` represents raw bytes. The Resend adapter now Base64-encodes both forms before calling its SDK. If you worked around the v1 Resend behavior by supplying a Base64 string, pass the original text or `Buffer.from(encodedContent, 'base64')` instead. Pre-encoded strings would otherwise be encoded a second time.
+
+`maxAttachmentBytes` still measures original content bytes, before provider Base64 encoding. Attachments remain buffered; streaming, upload storage, and concurrency budgets belong to the application.
+
+## Result types and custom adapters
+
+`createMailer({ provider: 'resend', ... })` now returns `Mailer<'resend'>`. A union of provider options preserves that union. Built-in results no longer include the impossible `'test'` provider; `createTestMailer()` still returns `Mailer<'test'>`. Broader explicit `Mailer` / `SendMailResult` annotations remain valid.
+
+Every successful send must have a non-blank provider message ID. Custom adapters must return `{ messageId: 'provider-id' }`. Blank, missing, or invalid IDs reject with `MailError`, code `provider`, and `deliveryUnknown: true`, matching built-in adapters. Do not blindly retry such sends: the provider may already have accepted the email.
+
+## Webhook routes
+
+The webhook API is unchanged. New [Next.js and Express examples](framework-webhooks.md) demonstrate raw-body preservation, bounded reads, and acknowledging only after the application durably accepts events. They do not install a database or implement business side effects.

package/docs/provider-contracts.md

@@ -6,7 +6,9 @@ The adapters provide one `createMailer(...).send(...)` interface, while provider
 
 - Provider SDKs are optional peers. Only the selected adapter is loaded, and a missing selected SDK becomes a `MailError` with code `configuration`.
 - `send()` resolves when the provider reports that it accepted the request. It does not prove inbox delivery.
-- A successful result includes the selected provider, provider message ID, and local acceptance timestamp. If the provider gives no ID, `messageId` is an empty string.
+- A successful result includes the selected provider, a non-blank provider message ID, and local acceptance timestamp. If a built-in or custom provider gives no usable ID, `send()` rejects with a `MailError` with code `provider` and `deliveryUnknown: true`.
+- SMTP results include optional `accepted`/`rejected` envelope recipients. Partial acceptance resolves, while complete rejection rejects; acceptance does not prove inbox delivery.
+- Optional `onSend` observers expose sanitized lifecycle metrics, with synchronous and asynchronous failures isolated. See [reliability](reliability.md).
 - TypedMailer does not retry automatically. `retryable` and `deliveryUnknown` are diagnostic signals, not a safe retry instruction. A timeout or ambiguous provider response can mean the provider accepted the message.
 - Unsupported fields or operations fail with `MailError` code `unsupported`; adapters must not silently discard caller data.
 - `close()` is safe to call repeatedly, stops new work, waits for in-flight operations, and closes the underlying transport at most once.
@@ -23,7 +25,13 @@ The adapters provide one `createMailer(...).send(...)` interface, while provider
 | Amazon SES | No                | No              | Yes      | Yes                | Unsupported             |
 | SMTP       | Yes               | No              | No       | Yes                | SMTP connection check   |
 
-Attachments are buffered for provider SDK requests. Configure `maxAttachmentBytes` on `createMailer()` to enforce an aggregate byte cap over all attachment content; strings are counted as UTF-8 bytes and `Uint8Array` content by `byteLength`. The option has no default cap to preserve existing behavior. Large-file streaming belongs in the application. `contentId` is supported by the providers listed as supporting inline attachments. `verifyConnection()` is only available for SMTP because the API providers do not offer a side-effect-free check through this interface.
+Attachments are buffered for provider SDK requests. Configure `maxAttachmentBytes` on `createMailer()` to enforce an aggregate byte cap over all attachment content; strings represent UTF-8 file content and are counted as UTF-8 bytes and `Uint8Array` content by `byteLength`. The option has no default cap to preserve existing behavior. Large-file streaming belongs in the application. `contentId` is supported by the providers listed as supporting inline attachments. `verifyConnection()` is only available for SMTP because the API providers do not offer a side-effect-free check through this interface.
+
+## SDK serialization compatibility
+
+Amazon SES requires `@aws-sdk/client-sesv2 >=3.797.0 <4` to serialize both custom headers and attachments. Resend receives Base64 attachment strings derived from the original UTF-8 text or binary bytes. `tests/providers/sdk-serialization.test.ts` runs the actual Resend SDK with an intercepted fetch and the actual SES SDK with a local transport; it verifies the serialized HTTP payload rather than only mocked SDK arguments. These tests run against both the lockfile and minimum supported SDK versions in CI.
+
+Built-in mailers preserve the selected provider literal (or provider union) in their result type. Built-in and custom configurations reject unknown keys and share sender validation.
 
 ## Updating a provider adapter
 
@@ -31,4 +39,4 @@ When changing an adapter, add its configuration schema and lazy loader in `src/p
 
 ## Custom adapters
 
-Applications can provide a `ProviderAdapter<TName>` directly to `createMailer()` without adding a built-in provider. Its `send()` method receives `NormalizedMailInput`: `from` is always set, and `to`, `cc`, and `bcc` are arrays when present. Resolve with `{ messageId }` after the SDK accepts the message. `verifyConnection()` and `close()` are optional; verification rejects with `unsupported` when omitted, while close is a no-op. TypedMailer normalizes thrown errors and tags results with the adapter's name. The generic adapter name is preserved in `SendMailResult<TName>` for TypeScript callers. Custom adapters are responsible for documenting and enforcing unsupported message fields.
+Applications can provide a `ProviderAdapter<TName>` directly to `createMailer()` without adding a built-in provider. Its `send()` method receives `NormalizedMailInput`: `from` is always set, and `to`, `cc`, and `bcc` are arrays when present. Resolve with `{ messageId }` and optional `accepted`/`rejected` recipient lists after the SDK accepts the message. `verifyConnection()` and `close()` are optional; verification rejects with `unsupported` when omitted, while close is a no-op. TypedMailer normalizes thrown errors and tags results with the adapter's name. The generic adapter name is preserved in `SendMailResult<TName>` for TypeScript callers. Custom adapters are responsible for documenting and enforcing unsupported message fields.

package/docs/reliability.md

@@ -0,0 +1,59 @@
+# Reliable application delivery
+
+TypedMailer reports provider acceptance, not inbox delivery. It performs no automatic retry, queueing, database migration, or failover. Version 2.1 adds optional SMTP recipient results, structured provider errors, authenticated webhook notification IDs, and isolated send observers.
+
+## SMTP partial acceptance
+
+```ts
+const result = await mailer.send(message);
+if (result.rejected?.length) {
+  await recordPartialAcceptance(result);
+}
+```
+
+SMTP `accepted` and `rejected` contain envelope recipient addresses reported by the relay, including CC/BCC. A send with some rejected recipients still resolves when the relay accepts the remaining recipients. Do not retry the entire original message: recipients already accepted could receive duplicates. When every recipient is rejected, the SMTP adapter rejects. These fields are optional for other and custom providers. Treat the recipient lists as personal data.
+
+## Error diagnostics and observations
+
+`MailError.status` contains the HTTP or SMTP response status when the SDK exposes it. `retryAfterSeconds` contains an optional parsed `Retry-After` delay, rounded up to whole seconds; unsupported/malformed delays remain undefined. These values do not override `deliveryUnknown` or make a retry safe. The original SDK error remains in `cause` and can contain sensitive information.
+
+```ts
+const mailer = createMailer({
+  provider: 'resend',
+  apiKey,
+  from: 'sender@example.test',
+  onSend(event) {
+    if (event.type === 'started') return;
+    metrics.record(event.provider, event.type, event.durationMs);
+    if (event.type === 'failed') metrics.recordFailure(event.code);
+  },
+});
+```
+
+`onSend` emits `started` followed by `succeeded` or `failed` for a validated send that reaches provider execution. Payloads contain provider, duration, and safe error classifications, never addresses, subject, content, headers, credentials, or arbitrary SDK errors. Construction/message validation failures and calls after close do not emit send events. Observer exceptions and rejected promises are ignored deliberately. Async observers are not awaited by `send()` or `close()`; applications own flushing and error reporting for their telemetry. Keep synchronous callbacks short. No telemetry dependency is installed by the package.
+
+## Durable webhook inbox
+
+Copy [`durable-mail.ts`](../examples/reliability/durable-mail.ts) and [`schema.sql`](../examples/reliability/schema.sql) into your application. Supply a `SqlDatabase` adapter for your PostgreSQL client. `acceptWebhookDelivery` inserts one complete notification with a unique `(provider, delivery_id)` constraint. Use it from the framework handler's `acceptEvents` callback and resolve only after database commit. A storage failure must return a retryable HTTP failure, not an acknowledgment.
+
+For Resend and SES, `verifyWebhook()` provides an authenticated `deliveryId`. It identifies the whole notification; SES can produce multiple recipient events sharing this ID. Store the complete event array once, then apply business changes in a transaction with an inbox processing marker. Do not deduplicate each recipient separately using only `deliveryId`. For other providers, use genuine `eventId` values where present, or an application-defined provider-specific key. The legacy `id` can equal a message ID and must not be assumed unique across delivery/open/bounce events. Do not invent an unsigned delivery ID from a request header.
+
+The supplied inbox schema stores normalized events including `raw`. Define retention, access controls, encryption, and any payload redaction in your application. Processing markers and business transactions depend on your domain and are not implemented by this example.
+
+## Transactional outbox
+
+`enqueueMail` uses a stable business-operation ID to prevent duplicate queue entries. Validate the message first and call it in the same database transaction as the business change. Apply `schema.sql` using your application's migration process. The adapter passed to enqueue can represent an open transaction; worker and inbox adapters must commit before reporting success. Binary attachments are encoded explicitly for JSON storage and restored as `Uint8Array`.
+
+`createSqlOutboxStore` claims one queued row with `FOR UPDATE SKIP LOCKED`, committing `sending` before network I/O. `processNextMail` sends once and records one of these states:
+
+| State      | Meaning and next action                                                                              |
+| ---------- | ---------------------------------------------------------------------------------------------------- |
+| `accepted` | Provider accepted the request. Follow delivery webhooks separately.                                  |
+| `partial`  | SMTP rejected some recipients. Reconcile the rejected subset.                                        |
+| `failed`   | Classified rejection with no uncertain acceptance. Application policy decides whether to requeue.    |
+| `unknown`  | Acceptance cannot be established. Reconcile with the provider before resending.                      |
+| `sending`  | Claimed, but no outcome persisted yet. A worker crash or failed receipt commit can leave this state. |
+
+The example deliberately does not reclaim stale `sending` rows automatically. Reconcile them and move to `unknown` when acceptance cannot be proven. A failed receipt commit propagates to the worker; it never reclassifies an accepted send as a failure. Use provider idempotency only where supported and keep the key stable across retries. Never resend the whole partial/unknown job automatically.
+
+Tests run the SQL against embedded PostgreSQL (PGlite), verify deduplication and state transitions, and exercise database failure paths. Production database concurrency, migrations, worker deployment, provider delivery, and operational recovery require application-level verification.

package/docs/webhooks.md

@@ -2,6 +2,8 @@
 
 TypedMailer exposes `verifyWebhook()` from `typedmailer/webhooks`. It authenticates a raw HTTP webhook request before returning normalized event records. It does not start an HTTP server, acknowledge requests, persist event IDs, or perform application actions. Your route owns HTTP responses, durable deduplication, and business logic.
 
+For framework integration, use the tested [Next.js App Router and Express route examples](framework-webhooks.md).
+
 ## Raw request bodies
 
 Pass the exact bytes received by your HTTP framework. Parsing JSON and serializing it again changes the signed input and causes verification to fail. `rawBody` accepts a string or `Uint8Array`; `headers` is a case-insensitive record of request header names and values. If the framework parses request bodies automatically, configure a raw-body capture before its JSON parser. Apply an HTTP request-body size limit before buffering the body. `verifyWebhook()` also rejects bodies larger than 1 MiB by default; set `maxBodyBytes` to a suitable positive value for your provider and expected batch size. Normalized event batches are limited to 1,000 events by default; set `maxEvents` to adjust that limit. Keep both limits finite and consistent with the upstream request limit.
@@ -42,13 +44,15 @@ for (const event of events) {
 
 ## Normalized event shape
 
-Each event includes `provider`, provider `eventType`, a normalized `type`, and the original provider payload in `raw`. When available, it also includes a provider event ID (`id`), message ID, recipient, and event timestamp (`occurredAt`). `raw` may contain personal data and provider metadata; avoid logging it without review. Unknown provider event names map to `type: 'other'` and retain their original `eventType`.
+Each event includes `provider`, provider `eventType`, a normalized `type`, and the original provider payload in `raw`. When available, it also includes `eventId` (a genuine provider event ID), `messageId`, `recipient`, and `occurredAt`. Resend/SNS events also carry an authenticated `deliveryId`. Resend preserves all recipients in `recipients` while retaining the first in `recipient` and still returning one event. SES returns one event per recipient and preserves complaint/delay timestamps.
+
+`id` remains a legacy identifier for compatibility: Brevo/Postmark can fall back to the message ID. Do not assume it is unique across different events for the same email. `raw` may contain personal data and provider metadata; avoid logging it without review. Unknown provider event names map to `type: 'other'` and retain their original `eventType`.
 
 Normalized types are `accepted`, `delivered`, `bounced`, `complained`, `delayed`, `opened`, `clicked`, `unsubscribed`, `rejected`, `failed`, and `other`.
 
 ## Delivery, retries, and deduplication
 
-Providers retry webhook delivery. `verifyWebhook()` verifies authenticity but does not prevent the same authentic event from being processed twice. Persist event IDs (or a stable provider/message/event key when the provider has no event ID) with a unique constraint before applying side effects. Acknowledge only after durable acceptance by your application. Do not log secrets or full event payloads by default.
+Providers retry webhook delivery. `verifyWebhook()` verifies authenticity but does not prevent the same authentic event from being processed twice. Persist complete notifications by `(provider, deliveryId)` where available, or use genuine provider `eventId` values and a provider-specific fallback when absent. SES recipient events share one notification ID; do not discard siblings by deduplicating each with that ID alone. Use a unique constraint before applying side effects. See [durable inbox/outbox examples](reliability.md). Acknowledge only after durable acceptance by your application. Do not log secrets or full event payloads by default.
 
 ## Provider references
 

package/examples/reliability/durable-mail.ts

@@ -0,0 +1,134 @@
+import { MailError, type Mailer, type SendMailInput, type SendMailResult } from 'typedmailer';
+import type { EmailWebhookEvent } from 'typedmailer/webhooks';
+
+/** Implement using a database client. Inbox/worker queries must commit before resolving; enqueue may use a business transaction. */
+export interface SqlDatabase {
+  query(sql: string, values: readonly unknown[]): Promise<{ readonly rows: readonly Record<string, unknown>[] }>;
+}
+
+export interface OutboxJob {
+  readonly id: string;
+  readonly input: SendMailInput;
+}
+
+export interface OutboxFailure {
+  readonly state: 'failed' | 'unknown';
+  readonly code: string;
+  readonly retryable: boolean;
+}
+
+export interface OutboxStore {
+  claim(): Promise<OutboxJob | undefined>;
+  accept(id: string, result: SendMailResult<string>): Promise<void>;
+  fail(id: string, failure: OutboxFailure): Promise<void>;
+}
+
+/** One committed row per authenticated notification, including every normalized event. */
+export async function acceptWebhookDelivery(
+  database: SqlDatabase,
+  deliveryId: string,
+  events: readonly EmailWebhookEvent[],
+): Promise<void> {
+  const provider = events[0]?.provider;
+  if (!deliveryId.trim() || !provider || events.some((event) => event.provider !== provider)) {
+    throw new Error('Expected one provider and an authenticated notification ID.');
+  }
+  await database.query(
+    `INSERT INTO mail_webhook_inbox (provider, delivery_id, events)
+     VALUES ($1, $2, $3::jsonb) ON CONFLICT (provider, delivery_id) DO NOTHING`,
+    [provider, deliveryId, JSON.stringify(events)],
+  );
+}
+
+/** Validate input before calling; enqueue in the SAME transaction as the business change. */
+export async function enqueueMail(database: SqlDatabase, id: string, input: SendMailInput): Promise<void> {
+  if (!id.trim()) throw new Error('Expected a stable business operation ID.');
+  await database.query(`INSERT INTO mail_outbox (id, input) VALUES ($1, $2::jsonb) ON CONFLICT (id) DO NOTHING`, [
+    id,
+    JSON.stringify({
+      ...input,
+      ...(input.attachments
+        ? {
+            attachments: input.attachments.map((attachment) => ({
+              ...attachment,
+              content:
+                typeof attachment.content === 'string'
+                  ? attachment.content
+                  : { encoding: 'typedmailer-bytes', base64: Buffer.from(attachment.content).toString('base64') },
+            })),
+          }
+        : {}),
+    }),
+  ]);
+}
+
+/** Claim commits BEFORE network I/O. A crash leaves sending for reconciliation, never blind resend. */
+export function createSqlOutboxStore(database: SqlDatabase): OutboxStore {
+  return {
+    async claim() {
+      const result = await database.query(
+        `WITH candidate AS (
+           SELECT id FROM mail_outbox WHERE state = 'queued'
+           ORDER BY created_at, id FOR UPDATE SKIP LOCKED LIMIT 1
+         ) UPDATE mail_outbox SET state = 'sending', updated_at = now()
+           FROM candidate WHERE mail_outbox.id = candidate.id
+           RETURNING mail_outbox.id, mail_outbox.input`,
+        [],
+      );
+      const row = result.rows[0];
+      if (!row) return undefined;
+      if (typeof row.id !== 'string') throw new Error('Invalid outbox row ID.');
+      // Stored JSON comes from validated application input. The mailer validates again before sending.
+      const input = JSON.parse(JSON.stringify(row.input), (_key, value: unknown) => {
+        if (
+          typeof value === 'object' &&
+          value !== null &&
+          'encoding' in value &&
+          value.encoding === 'typedmailer-bytes' &&
+          'base64' in value &&
+          typeof value.base64 === 'string'
+        ) {
+          return new Uint8Array(Buffer.from(value.base64, 'base64'));
+        }
+        return value;
+      }) as SendMailInput;
+      return { id: row.id, input };
+    },
+    async accept(id, result) {
+      const updated = await database.query(
+        `UPDATE mail_outbox SET state = $2, receipt = $3::jsonb, updated_at = now()
+         WHERE id = $1 AND state = 'sending' RETURNING id`,
+        [id, result.rejected?.length ? 'partial' : 'accepted', JSON.stringify(result)],
+      );
+      if (updated.rows[0]?.id !== id) throw new Error('Outbox receipt was not committed.');
+    },
+    async fail(id, failure) {
+      const updated = await database.query(
+        `UPDATE mail_outbox SET state = $2, failure = $3::jsonb, updated_at = now()
+         WHERE id = $1 AND state = 'sending' RETURNING id`,
+        [id, failure.state, JSON.stringify(failure)],
+      );
+      if (updated.rows[0]?.id !== id) throw new Error('Outbox failure was not committed.');
+    },
+  };
+}
+
+/** No automatic retry: the application reconciles unknown and partial delivery states. */
+export async function processNextMail(mailer: Mailer<string>, store: OutboxStore): Promise<boolean> {
+  const job = await store.claim();
+  if (!job) return false;
+  let result: SendMailResult<string>;
+  try {
+    result = await mailer.send(job.input);
+  } catch (error) {
+    const failure: OutboxFailure =
+      error instanceof MailError
+        ? { state: error.deliveryUnknown ? 'unknown' : 'failed', code: error.code, retryable: error.retryable }
+        : { state: 'unknown', code: 'unclassified', retryable: false };
+    await store.fail(job.id, failure);
+    return true;
+  }
+  // Persistence failures propagate. Never reinterpret an accepted send as a send failure.
+  await store.accept(job.id, result);
+  return true;
+}

package/examples/reliability/schema.sql

@@ -0,0 +1,20 @@
+CREATE TABLE mail_webhook_inbox (
+  provider text NOT NULL,
+  delivery_id text NOT NULL,
+  events jsonb NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (provider, delivery_id)
+);
+
+CREATE TABLE mail_outbox (
+  id text PRIMARY KEY,
+  input jsonb NOT NULL,
+  state text NOT NULL DEFAULT 'queued'
+    CHECK (state IN ('queued', 'sending', 'accepted', 'partial', 'failed', 'unknown')),
+  receipt jsonb,
+  failure jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX mail_outbox_queued ON mail_outbox (created_at, id) WHERE state = 'queued';