typedmailer 2.0.0 → 2.1.1

package/README.md

@@ -232,7 +232,7 @@ await mailer.send({ to: 'person@example.test', subject: 'Hello', text: 'Hi' });
 console.log(mailer.sent[0]);
 ```
 
-Messages captured by `createTestMailer` return `provider: 'test'` so test results are not mistaken for SMTP deliveries.
+Captures are independent copies of addresses, headers, metadata, and attachment bytes. `clear()` removes captures without reusing message IDs. Messages captured by `createTestMailer` return `provider: 'test'` so test results are not mistaken for SMTP deliveries.
 
 ## Verify provider webhooks
 
@@ -251,7 +251,7 @@ For Amazon SES, run `npm install typedmailer @aws-sdk/client-sesv2 && node --env
 
 ## Errors and delivery
 
-Provider and transport failures are normalized as `MailError`, with `code`, `provider`, `retryable`, `deliveryUnknown`, and the original error in `cause`. Codes mean:
+Provider and transport failures are normalized as `MailError`, with `code`, `provider`, `retryable`, `deliveryUnknown`, optional response `status` and `retryAfterSeconds`, and the original error in `cause`. Codes mean:
 
 | Code             | Meaning                                                               |
 | ---------------- | --------------------------------------------------------------------- |
@@ -264,6 +264,8 @@ Provider and transport failures are normalized as `MailError`, with `code`, `pro
 
 `retryable` is guidance from the normalized failure: recognized network failures and rate limits are retryable; API provider 5xx failures are retryable; authentication, configuration, unsupported, and SMTP 5xx failures are not. `deliveryUnknown` is separate: it is true when a send timeout/socket interruption, a provider 5xx, or an accepted response without a message ID means the provider may have accepted the message without returning a clear result. It stays false for verification failures, DNS lookup failures, authentication errors, rate limits, and SMTP response errors. This does not guarantee that retrying is safe. Use provider-supported idempotency where available and apply retry policy in your application. `cause` retains the original SDK error for diagnostics and can contain provider details; avoid logging it without reviewing your data handling policy.
 
+SMTP results also expose optional `accepted` and `rejected` envelope recipients. Partial rejection resolves with both lists; do not resend the whole recipient list. Use the [reliability guide](docs/reliability.md) for isolated `onSend` metrics hooks and tested durable inbox/outbox examples.
+
 A successful `send()` means the provider accepted the request; it does not confirm inbox delivery. Verify delivery, bounce, and complaint callbacks with [`typedmailer/webhooks`](docs/webhooks.md).
 
 `verifyConnection()` currently supports SMTP. API provider adapters report `unsupported` because they do not expose a side-effect-free credential check through this API; verify credentials with a controlled provider test message.

package/dist/config.js

@@ -1,4 +1,8 @@
 import { z } from 'zod';
+const headerValueSchema = z
+    .string()
+    .refine((value) => !/[\r\n\0]/.test(value), 'Header values cannot contain line breaks or NUL.');
+const headerNameSchema = z.string().regex(/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/, 'Use a valid header field name.');
 const emailSchema = z.string().email();
 const addressObjectSchema = z
     .object({
@@ -25,23 +29,25 @@ export const mailInputSchema = z
     subject: z
         .string()
         .min(1)
-        .refine((value) => value.trim().length > 0, 'Subject cannot be blank.'),
-    messageId: z.string().min(1).optional(),
+        .refine((value) => value.trim().length > 0, 'Subject cannot be blank.')
+        .refine((value) => !/[\r\n\0]/.test(value), 'Subject cannot contain line breaks or NUL.'),
+    messageId: headerValueSchema.min(1).optional(),
     text: z.string().optional(),
     html: z.string().optional(),
     replyTo: addressSchema.optional(),
     cc: z.union([addressSchema, z.array(addressSchema)]).optional(),
     bcc: z.union([addressSchema, z.array(addressSchema)]).optional(),
-    headers: z.record(z.string(), z.string()).optional(),
+    headers: z.record(headerNameSchema, headerValueSchema).optional(),
     attachments: z
         .array(z.object({
         filename: z
             .string()
             .min(1)
-            .refine((value) => value.trim().length > 0, 'Attachment filename cannot be blank.'),
+            .refine((value) => value.trim().length > 0, 'Attachment filename cannot be blank.')
+            .refine((value) => !/[\r\n\0]/.test(value), 'Attachment filename cannot contain line breaks or NUL.'),
         content: z.union([z.string(), z.instanceof(Uint8Array)]),
-        contentType: z.string().min(1).optional(),
-        contentId: z.string().min(1).optional(),
+        contentType: headerValueSchema.min(1).optional(),
+        contentId: headerValueSchema.min(1).optional(),
     }))
         .optional(),
     idempotencyKey: z.string().min(1).optional(),

package/dist/errors.d.ts

@@ -1,12 +1,18 @@
 export type MailErrorCode = 'configuration' | 'authentication' | 'rate_limit' | 'network' | 'provider' | 'unsupported';
 export interface MailErrorOptions extends ErrorOptions {
     readonly deliveryUnknown?: boolean;
+    /** HTTP or SMTP response status, when supplied by the SDK. */
+    readonly status?: number;
+    /** Provider retry delay in seconds. Does not authorize automatic retry. */
+    readonly retryAfterSeconds?: number;
 }
 export declare class MailError extends Error {
     readonly code: MailErrorCode;
     readonly provider: string;
     readonly retryable: boolean;
     readonly deliveryUnknown: boolean;
+    readonly status: number | undefined;
+    readonly retryAfterSeconds: number | undefined;
     constructor(message: string, code: MailErrorCode, provider: string, retryable: boolean, options?: MailErrorOptions);
 }
 export type MailErrorOperation = 'send' | 'verify';

package/dist/errors.js

@@ -3,6 +3,8 @@ export class MailError extends Error {
     provider;
     retryable;
     deliveryUnknown;
+    status;
+    retryAfterSeconds;
     constructor(message, code, provider, retryable, options) {
         super(message, options);
         this.code = code;
@@ -10,6 +12,8 @@ export class MailError extends Error {
         this.retryable = retryable;
         this.name = 'MailError';
         this.deliveryUnknown = options?.deliveryUnknown ?? false;
+        this.status = options?.status;
+        this.retryAfterSeconds = options?.retryAfterSeconds;
     }
 }
 const networkErrorCodes = new Set([
@@ -25,19 +29,8 @@ const networkErrorCodes = new Set([
 ]);
 const ambiguousNetworkErrorCodes = new Set(['ETIMEDOUT', 'ECONNECTION', 'ECONNRESET', 'EPIPE', 'ESOCKET']);
 function mayHaveBeenAccepted(error, provider) {
-    const candidate = error;
-    const status = typeof candidate?.statusCode === 'number'
-        ? candidate.statusCode
-        : typeof candidate?.status === 'number'
-            ? candidate.status
-            : typeof candidate?.code === 'number'
-                ? candidate.code
-                : typeof error?.responseCode === 'number'
-                    ? error.responseCode
-                    : typeof error?.$metadata?.httpStatusCode ===
-                        'number'
-                        ? error.$metadata.httpStatusCode
-                        : undefined;
+    const candidate = record(error);
+    const status = responseStatus(error);
     const code = typeof candidate?.code === 'string' ? candidate.code : candidate?.name;
     if (provider === 'smtp' && status !== undefined)
         return false;
@@ -56,21 +49,12 @@ export function normalizeProviderError(error, provider, operation = 'verify') {
         return new MailError(error.message, error.code, error.provider, error.retryable, {
             ...(error.cause !== undefined ? { cause: error.cause } : {}),
             deliveryUnknown,
+            ...(error.status !== undefined ? { status: error.status } : {}),
+            ...(error.retryAfterSeconds !== undefined ? { retryAfterSeconds: error.retryAfterSeconds } : {}),
         });
     }
-    const candidate = error;
-    const status = typeof candidate?.statusCode === 'number'
-        ? candidate.statusCode
-        : typeof candidate?.status === 'number'
-            ? candidate.status
-            : typeof candidate?.code === 'number'
-                ? candidate.code
-                : typeof error?.responseCode === 'number'
-                    ? error.responseCode
-                    : typeof error?.$metadata?.httpStatusCode ===
-                        'number'
-                        ? error.$metadata.httpStatusCode
-                        : undefined;
+    const candidate = record(error);
+    const status = responseStatus(error);
     const code = typeof candidate?.code === 'string'
         ? candidate.code
         : typeof candidate?.name === 'string'
@@ -102,8 +86,40 @@ export function normalizeProviderError(error, provider, operation = 'verify') {
     const retryable = errorCode === 'network' ||
         errorCode === 'rate_limit' ||
         (provider !== 'smtp' && status !== undefined && status >= 500 && status < 600);
+    const retryAfterSeconds = retryAfter(error);
     return new MailError(safeMessage, errorCode, provider, retryable, {
         cause: error,
+        ...(status !== undefined ? { status } : {}),
+        ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}),
         deliveryUnknown: operation === 'send' && mayHaveBeenAccepted(error, provider),
     });
 }
+function record(value) {
+    return typeof value === 'object' && value !== null ? value : {};
+}
+function responseStatus(error) {
+    const candidate = record(error);
+    const metadata = record(candidate.$metadata);
+    const response = record(candidate.response);
+    return [
+        candidate.statusCode,
+        candidate.status,
+        candidate.code,
+        candidate.responseCode,
+        metadata.httpStatusCode,
+        response.status,
+    ].find((value) => typeof value === 'number' && Number.isInteger(value) && value >= 100 && value <= 599);
+}
+function retryAfter(error) {
+    const candidate = record(error);
+    const response = record(candidate.response);
+    const headers = response.headers ?? candidate.headers;
+    const value = headers instanceof Headers
+        ? headers.get('retry-after')
+        : Object.entries(record(headers)).find(([key]) => key.toLowerCase() === 'retry-after')?.[1];
+    const text = Array.isArray(value) ? value[0] : value;
+    if (typeof text !== 'string' && typeof text !== 'number')
+        return undefined;
+    const seconds = typeof text === 'number' || /^\d+(?:\.\d+)?$/.test(text) ? Number(text) : (Date.parse(text) - Date.now()) / 1_000;
+    return Number.isFinite(seconds) && seconds >= 0 ? Math.ceil(seconds) : undefined;
+}

package/dist/index.d.ts

@@ -6,4 +6,4 @@ export declare function createMailer<const TOptions extends BuiltInMailerOptions
 export declare function createMailer(input: MailerOptions): Mailer<string>;
 export { MailError } from './errors.js';
 export type { MailErrorCode, MailErrorOperation, MailErrorOptions } from './errors.js';
-export type { CustomMailerOptions, MailAddress, MailAttachment, Mailer, NormalizedMailInput, ProviderAdapter, ProviderName, ProviderSendResult, SendMailInput, SendMailResult, } from './types.js';
+export type { CustomMailerOptions, MailAddress, MailAttachment, Mailer, MailSendEvent, MailSendObserver, NormalizedMailInput, ProviderAdapter, ProviderName, ProviderSendResult, SendMailInput, SendMailResult, } from './types.js';

package/dist/index.js

@@ -44,6 +44,15 @@ export function createMailer(input) {
         ? customMailerOptionsSchema.parse(input)
         : mailerOptionsSchema.parse(input);
     const providerName = typeof parsedOptions.provider === 'string' ? parsedOptions.provider : parsedOptions.provider.name;
+    const notify = (event) => {
+        try {
+            // Telemetry must never alter delivery or produce an unhandled rejection.
+            void Promise.resolve(parsedOptions.onSend?.(event)).catch(() => undefined);
+        }
+        catch {
+            // A synchronous observer failure is isolated as well.
+        }
+    };
     const assertOpen = () => {
         if (closed)
             throw new MailError('Mailer has been closed.', 'configuration', providerName, false);
@@ -107,6 +116,8 @@ export function createMailer(input) {
                 ...(bcc ? { bcc } : {}),
                 ...(parsed.replyTo ? { replyTo: parsed.replyTo } : {}),
             };
+            const startedAt = performance.now();
+            notify({ type: 'started', provider: providerName });
             try {
                 const result = await runWithProvider((provider) => provider.send(normalized));
                 if (typeof result?.messageId !== 'string' || result.messageId.trim().length === 0) {
@@ -114,14 +125,34 @@ export function createMailer(input) {
                         deliveryUnknown: true,
                     });
                 }
-                return {
+                for (const recipients of [result.accepted, result.rejected]) {
+                    if (recipients !== undefined &&
+                        (!Array.isArray(recipients) ||
+                            recipients.some((recipient) => typeof recipient !== 'string' || !recipient.trim()))) {
+                        throw new MailError('The provider returned an invalid recipient receipt.', 'provider', providerName, false, { deliveryUnknown: true });
+                    }
+                }
+                const receipt = {
+                    ...(result.accepted ? { accepted: [...result.accepted] } : {}),
+                    ...(result.rejected ? { rejected: [...result.rejected] } : {}),
                     provider: providerName,
                     messageId: result.messageId,
                     acceptedAt: new Date(),
                 };
+                notify({ type: 'succeeded', provider: providerName, durationMs: performance.now() - startedAt });
+                return receipt;
             }
             catch (error) {
-                throw normalizeProviderError(error, providerName, 'send');
+                const normalizedError = normalizeProviderError(error, providerName, 'send');
+                notify({
+                    type: 'failed',
+                    provider: providerName,
+                    durationMs: performance.now() - startedAt,
+                    code: normalizedError.code,
+                    retryable: normalizedError.retryable,
+                    deliveryUnknown: normalizedError.deliveryUnknown,
+                });
+                throw normalizedError;
             }
         },
         async verifyConnection() {

package/dist/providers/registry.d.ts

@@ -1,11 +1,12 @@
 import { z } from 'zod';
-import type { MailProvider } from '../types.js';
+import type { MailProvider, MailSendObserver } from '../types.js';
 export declare const mailerBaseOptionsSchema: z.ZodObject<{
     from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
         email: z.ZodString;
         name: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>]>;
     maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+    onSend: z.ZodOptional<z.ZodCustom<MailSendObserver, MailSendObserver>>;
 }, z.core.$strict>;
 export declare const providerOptions: {
     readonly resend: z.ZodObject<{
@@ -14,6 +15,7 @@ export declare const providerOptions: {
             name: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>]>;
         maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+        onSend: z.ZodOptional<z.ZodCustom<MailSendObserver, MailSendObserver>>;
         provider: z.ZodLiteral<"resend">;
         apiKey: z.ZodString;
     }, z.core.$strict>;
@@ -23,6 +25,7 @@ export declare const providerOptions: {
             name: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>]>;
         maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+        onSend: z.ZodOptional<z.ZodCustom<MailSendObserver, MailSendObserver>>;
         provider: z.ZodLiteral<"brevo">;
         apiKey: z.ZodString;
     }, z.core.$strict>;
@@ -32,6 +35,7 @@ export declare const providerOptions: {
             name: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>]>;
         maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+        onSend: z.ZodOptional<z.ZodCustom<MailSendObserver, MailSendObserver>>;
         provider: z.ZodLiteral<"postmark">;
         apiKey: z.ZodString;
     }, z.core.$strict>;
@@ -41,6 +45,7 @@ export declare const providerOptions: {
             name: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>]>;
         maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+        onSend: z.ZodOptional<z.ZodCustom<MailSendObserver, MailSendObserver>>;
         provider: z.ZodLiteral<"sendgrid">;
         apiKey: z.ZodString;
     }, z.core.$strict>;
@@ -50,6 +55,7 @@ export declare const providerOptions: {
             name: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>]>;
         maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+        onSend: z.ZodOptional<z.ZodCustom<MailSendObserver, MailSendObserver>>;
         provider: z.ZodLiteral<"mailgun">;
         apiKey: z.ZodString;
         domain: z.ZodString;
@@ -64,6 +70,7 @@ export declare const providerOptions: {
             name: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>]>;
         maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+        onSend: z.ZodOptional<z.ZodCustom<MailSendObserver, MailSendObserver>>;
         provider: z.ZodLiteral<"ses">;
         region: z.ZodString;
     }, z.core.$strict>;
@@ -73,6 +80,7 @@ export declare const providerOptions: {
             name: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>]>;
         maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+        onSend: z.ZodOptional<z.ZodCustom<MailSendObserver, MailSendObserver>>;
         provider: z.ZodLiteral<"smtp">;
         host: z.ZodString;
         port: z.ZodNumber;
@@ -91,6 +99,7 @@ export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>]>;
     maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+    onSend: z.ZodOptional<z.ZodCustom<MailSendObserver, MailSendObserver>>;
     provider: z.ZodLiteral<"resend">;
     apiKey: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
@@ -99,6 +108,7 @@ export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>]>;
     maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+    onSend: z.ZodOptional<z.ZodCustom<MailSendObserver, MailSendObserver>>;
     provider: z.ZodLiteral<"brevo">;
     apiKey: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
@@ -107,6 +117,7 @@ export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>]>;
     maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+    onSend: z.ZodOptional<z.ZodCustom<MailSendObserver, MailSendObserver>>;
     provider: z.ZodLiteral<"postmark">;
     apiKey: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
@@ -115,6 +126,7 @@ export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>]>;
     maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+    onSend: z.ZodOptional<z.ZodCustom<MailSendObserver, MailSendObserver>>;
     provider: z.ZodLiteral<"sendgrid">;
     apiKey: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
@@ -123,6 +135,7 @@ export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>]>;
     maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+    onSend: z.ZodOptional<z.ZodCustom<MailSendObserver, MailSendObserver>>;
     provider: z.ZodLiteral<"mailgun">;
     apiKey: z.ZodString;
     domain: z.ZodString;
@@ -136,6 +149,7 @@ export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>]>;
     maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+    onSend: z.ZodOptional<z.ZodCustom<MailSendObserver, MailSendObserver>>;
     provider: z.ZodLiteral<"ses">;
     region: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
@@ -144,6 +158,7 @@ export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>]>;
     maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+    onSend: z.ZodOptional<z.ZodCustom<MailSendObserver, MailSendObserver>>;
     provider: z.ZodLiteral<"smtp">;
     host: z.ZodString;
     port: z.ZodNumber;

package/dist/providers/registry.js

@@ -6,6 +6,9 @@ export const mailerBaseOptionsSchema = z
     from: senderSchema,
     /** Optional aggregate in-memory attachment cap. No default preserves existing behavior. */
     maxAttachmentBytes: z.number().int().positive().optional(),
+    onSend: z
+        .custom((value) => typeof value === 'function', 'Expected an observer function.')
+        .optional(),
 })
     .strict();
 export const providerOptions = {

package/dist/providers/sendgrid.js

@@ -35,7 +35,7 @@ export function createSendGridProvider(options) {
                                 filename: attachment.filename,
                                 content: Buffer.from(attachment.content).toString('base64'),
                                 ...(attachment.contentType ? { type: attachment.contentType } : {}),
-                                ...(attachment.contentId ? { contentId: attachment.contentId, disposition: 'inline' } : {}),
+                                ...(attachment.contentId ? { content_id: attachment.contentId, disposition: 'inline' } : {}),
                             })),
                         }
                         : {}),

package/dist/providers/smtp.js

@@ -6,6 +6,9 @@ function toNodemailerAddress(address) {
         return address;
     return { address: address.email, ...(address.name !== undefined ? { name: address.name } : {}) };
 }
+function envelopeEmail(address) {
+    return typeof address === 'string' ? address : address.address;
+}
 export function createSmtpProvider(options) {
     const transport = nodemailer.createTransport({
         host: options.host,
@@ -50,7 +53,11 @@ export function createSmtpProvider(options) {
                         deliveryUnknown: true,
                     });
                 }
-                return { messageId: result.messageId };
+                return {
+                    messageId: result.messageId,
+                    ...(Array.isArray(result.accepted) ? { accepted: result.accepted.map(envelopeEmail) } : {}),
+                    ...(Array.isArray(result.rejected) ? { rejected: result.rejected.map(envelopeEmail) } : {}),
+                };
             }
             catch (error) {
                 throw normalizeProviderError(error, 'smtp', 'send');

package/dist/testing.js

@@ -5,6 +5,7 @@ export function createTestMailer(options) {
     const from = senderSchema.parse(options.from);
     const sent = [];
     let closed = false;
+    let sequence = 0;
     const assertOpen = () => {
         if (closed)
             throw new MailError('Mailer has been closed.', 'configuration', 'test', false);
@@ -16,10 +17,10 @@ export function createTestMailer(options) {
         },
         async send(input) {
             assertOpen();
-            const message = { ...input, from: input.from ?? from };
+            const message = structuredClone({ ...input, from: input.from ?? from });
             mailInputSchema.parse(message);
             sent.push(message);
-            return { provider: 'test', messageId: `test-${sent.length}`, acceptedAt: new Date() };
+            return { provider: 'test', messageId: `test-${++sequence}`, acceptedAt: new Date() };
         },
         async verifyConnection() {
             assertOpen();

package/dist/types.d.ts

@@ -29,6 +29,9 @@ export interface SendMailResult<TProvider extends string = ProviderName | 'test'
     readonly messageId: string;
     /** Time when the provider accepted the request. This does not confirm inbox delivery. */
     readonly acceptedAt: Date;
+    /** SMTP envelope recipients accepted/rejected by the relay; not proof of inbox delivery. */
+    readonly accepted?: readonly string[];
+    readonly rejected?: readonly string[];
 }
 export interface Mailer<TProvider extends string = ProviderName | 'test'> {
     send(input: SendMailInput): Promise<SendMailResult<TProvider>>;
@@ -46,6 +49,7 @@ export interface CustomMailerOptions<TProvider extends string = string> {
     readonly provider: ProviderAdapter<TProvider>;
     readonly from: MailAddress;
     readonly maxAttachmentBytes?: number;
+    readonly onSend?: MailSendObserver;
 }
 export interface NormalizedMailInput extends Omit<SendMailInput, 'from' | 'to' | 'cc' | 'bcc' | 'replyTo'> {
     readonly from: MailAddress;
@@ -56,9 +60,29 @@ export interface NormalizedMailInput extends Omit<SendMailInput, 'from' | 'to' |
 }
 export interface ProviderSendResult {
     readonly messageId: string;
+    readonly accepted?: readonly string[];
+    readonly rejected?: readonly string[];
 }
 export interface MailProvider {
     send(input: NormalizedMailInput): Promise<ProviderSendResult>;
     verifyConnection(): Promise<void>;
     close(): Promise<void>;
 }
+/** Contains no addresses, message content, credentials, or arbitrary provider errors. */
+export type MailSendEvent = {
+    readonly type: 'started';
+    readonly provider: string;
+} | {
+    readonly type: 'succeeded';
+    readonly provider: string;
+    readonly durationMs: number;
+} | {
+    readonly type: 'failed';
+    readonly provider: string;
+    readonly durationMs: number;
+    readonly code: import('./errors.js').MailErrorCode;
+    readonly retryable: boolean;
+    readonly deliveryUnknown: boolean;
+};
+/** Observer failures are isolated. Async observers do not delay sends or close(). */
+export type MailSendObserver = (event: MailSendEvent) => void | Promise<void>;

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/provider-contracts.md

@@ -7,6 +7,8 @@ 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, 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.
@@ -37,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

@@ -44,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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typedmailer",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "A type-safe Node.js email library with one API for Resend, Brevo, Postmark, SendGrid, Mailgun, Amazon SES, or SMTP.",
   "author": "Erol Senol",
   "license": "MIT",
@@ -38,7 +38,9 @@
     "docs/webhooks.md",
     "CODE_OF_CONDUCT.md",
     "docs/migration-v2.md",
-    "docs/framework-webhooks.md"
+    "docs/framework-webhooks.md",
+    "docs/reliability.md",
+    "examples/reliability"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -106,6 +108,7 @@
   },
   "devDependencies": {
     "@aws-sdk/client-sesv2": ">=3.797.0 <4",
+    "@electric-sql/pglite": "^0.5.8",
     "@getbrevo/brevo": ">=6.0.1 <7",
     "@sendgrid/mail": ">=8.0.0 <9",
     "@types/express": "^5.0.6",
@@ -117,6 +120,7 @@
     "husky": "^9.1.7",
     "lint-staged": "^17.6.0",
     "mailgun.js": ">=14.0.0 <15",
+    "nock": "^14.0.17",
     "nodemailer": ">=7.0.0 <11",
     "postmark": ">=5.0.0 <6",
     "prettier": "^3.9.9",