typedmailer 1.4.0 → 2.1.0

package/README.md

@@ -39,6 +39,8 @@ npm install typedmailer mailgun.js form-data
 npm install typedmailer @aws-sdk/client-sesv2
 ```
 
+Upgrading from v1? Read the [v2 migration guide](docs/migration-v2.md), including the SES SDK minimum and attachment encoding changes.
+
 Requires Node.js 22 or newer. Provider SDKs are optional peers and are loaded only when their adapter is selected.
 
 For SMTP, use `secure: true` with implicit TLS (commonly port 465), or use STARTTLS with `secure: false` and `requireTLS: true`. Port 587 requires STARTTLS by default; other ports use opportunistic TLS unless `requireTLS` is set.
@@ -134,7 +136,7 @@ const mailer = createMailer({
 
 ### Amazon SES
 
-SES requires a region and uses the AWS SDK credential provider chain, such as environment credentials, a shared profile, or an IAM role.
+SES requires `@aws-sdk/client-sesv2 >=3.797.0 <4`, a region, and uses the AWS SDK credential provider chain, such as environment credentials, a shared profile, or an IAM role.
 
 ```ts
 const mailer = createMailer({
@@ -162,10 +164,12 @@ For local development, start Mailpit with `docker run --rm -p 1025:1025 -p 8025:
 
 ## Message options
 
-`to` accepts an email string, a `{ email, name }` object, or an array. Provide `text` or `html` (or both). Optional fields include `from`, `replyTo`, `cc`, `bcc`, `headers`, `attachments`, `metadata`, and `idempotencyKey`; `messageId` is SMTP-only. Attachments may include `contentId` for inline images with Resend, Postmark, SendGrid, Mailgun, Amazon SES, and SMTP. Attachment content accepts strings or `Uint8Array`; the provider adapters buffer it for SDK requests, so use an application-managed upload or streaming workflow for large files. Set `maxAttachmentBytes` on `createMailer()` to reject a message before loading or calling the provider when the combined UTF-8 and binary attachment content exceeds your application's memory budget. It is unset by default for backward compatibility.
+`to` accepts an email string, a `{ email, name }` object, or an array. Provide `text` or `html` (or both). Optional fields include `from`, `replyTo`, `cc`, `bcc`, `headers`, `attachments`, `metadata`, and `idempotencyKey`; `messageId` is SMTP-only. Attachments may include `contentId` for inline images with Resend, Postmark, SendGrid, Mailgun, Amazon SES, and SMTP. Attachment content accepts UTF-8 text strings or raw bytes as `Uint8Array`; the provider adapters buffer it for SDK requests, so use an application-managed upload or streaming workflow for large files. Set `maxAttachmentBytes` on `createMailer()` to reject a message before loading or calling the provider when the combined UTF-8 and binary attachment content exceeds your application's memory budget. It is unset by default for backward compatibility.
 
 Subjects and attachment filenames cannot be blank. Supplied content types and inline content IDs must be non-empty. The library does not impose a fixed attachment-size limit.
 
+Built-in and custom mailer configuration reject unknown option keys. Named sender strings validate the enclosed email address; display names cannot contain line breaks. Message/configuration validation failures are Zod errors. Built-in provider names are preserved in result types: a Resend mailer returns `SendMailResult<'resend'>`.
+
 Provider capabilities differ. Unsupported fields return a `MailError` with code `unsupported` instead of being silently ignored.
 
 | Provider   | Custom `messageId` | `idempotencyKey` | Metadata | Inline attachments | `verifyConnection()` |
@@ -202,7 +206,7 @@ const result = await mailer.send({ to: 'person@example.com', subject: 'Hello', t
 await mailer.close();
 ```
 
-The custom adapter owns provider SDK setup, field support, and error handling. Throwing an error still passes through TypedMailer error normalization. Connection verification is reported as `unsupported` when the adapter does not implement it.
+The custom adapter owns provider SDK setup, field support, and error handling. Throwing an error still passes through TypedMailer error normalization. Connection verification is reported as `unsupported` when the adapter does not implement it. Blank or invalid custom message IDs reject with code `provider` and `deliveryUnknown: true`.
 
 ```ts
 await mailer.send({
@@ -228,11 +232,11 @@ 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
 
-Use `verifyWebhook` from `typedmailer/webhooks` to authenticate a raw request and receive normalized events. Your HTTP route remains responsible for preserving the raw body, responding to the provider, deduplicating events durably, and applying application changes. See [Webhook verification](docs/webhooks.md) for provider-specific configuration and security requirements.
+Use `verifyWebhook` from `typedmailer/webhooks` to authenticate a raw request and receive normalized events. Your HTTP route remains responsible for preserving the raw body, responding to the provider, deduplicating events durably, and applying application changes. See [Webhook verification](docs/webhooks.md) for provider-specific configuration and security requirements, and the tested [Next.js and Express route examples](docs/framework-webhooks.md) for raw-body capture and durable event acceptance.
 
 ## Runnable examples
 
@@ -247,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                                                               |
 | ---------------- | --------------------------------------------------------------------- |
@@ -260,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.d.ts

@@ -1,5 +1,9 @@
 import { z } from 'zod';
 import type { MailAddress } from './types.js';
+export declare const senderSchema: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+    email: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>]>;
 export declare const mailInputSchema: z.ZodObject<{
     from: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
         email: z.ZodString;

package/dist/config.js

@@ -1,12 +1,22 @@
 import { z } from 'zod';
-const addressSchema = z.union([
-    z.string().email(),
-    z.object({ email: z.string().email(), name: z.string().optional() }).strict(),
-]);
-const senderSchema = z.union([
-    z.string().email(),
-    z.string().regex(/^.+ <[^<>\s]+@[^<>\s]+>$/, 'Use a valid email address or "Name <email@example.com>".'),
-    z.object({ email: z.string().email(), name: z.string().optional() }).strict(),
+const emailSchema = z.string().email();
+const addressObjectSchema = z
+    .object({
+    email: emailSchema,
+    name: z
+        .string()
+        .refine((value) => !/[\r\n]/.test(value), 'Display names cannot contain line breaks.')
+        .optional(),
+})
+    .strict();
+const addressSchema = z.union([emailSchema, addressObjectSchema]);
+export const senderSchema = z.union([
+    emailSchema,
+    z.string().refine((value) => {
+        const match = /^([^<>\r\n]+) <([^<>\s]+)>$/.exec(value);
+        return match !== null && match[1].trim().length > 0 && emailSchema.safeParse(match[2]).success;
+    }, 'Use a valid email address or "Name <email@example.com>".'),
+    addressObjectSchema,
 ]);
 export const mailInputSchema = z
     .object({

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

@@ -1,9 +1,9 @@
 import { type MailerOptions as BuiltInMailerOptions } from './providers/registry.js';
-import type { CustomMailerOptions, Mailer, ProviderName } from './types.js';
+import type { CustomMailerOptions, Mailer } from './types.js';
 export type MailerOptions = BuiltInMailerOptions | CustomMailerOptions;
 export declare function createMailer<const TProvider extends string>(input: CustomMailerOptions<TProvider>): Mailer<TProvider>;
-export declare function createMailer(input: BuiltInMailerOptions): Mailer<ProviderName | 'test'>;
+export declare function createMailer<const TOptions extends BuiltInMailerOptions>(input: TOptions): Mailer<TOptions['provider']>;
 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,16 +116,43 @@ 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));
-                return {
+                if (typeof result?.messageId !== 'string' || result.messageId.trim().length === 0) {
+                    throw new MailError('The provider returned no message identifier.', 'provider', providerName, false, {
+                        deliveryUnknown: true,
+                    });
+                }
+                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,12 +1,13 @@
 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>;
-}, z.core.$strip>;
+    onSend: z.ZodOptional<z.ZodCustom<MailSendObserver, MailSendObserver>>;
+}, z.core.$strict>;
 export declare const providerOptions: {
     readonly resend: z.ZodObject<{
         from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
@@ -14,42 +15,47 @@ 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.$strip>;
+    }, z.core.$strict>;
     readonly brevo: 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>>;
         provider: z.ZodLiteral<"brevo">;
         apiKey: z.ZodString;
-    }, z.core.$strip>;
+    }, z.core.$strict>;
     readonly postmark: 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>>;
         provider: z.ZodLiteral<"postmark">;
         apiKey: z.ZodString;
-    }, z.core.$strip>;
+    }, z.core.$strict>;
     readonly sendgrid: 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>>;
         provider: z.ZodLiteral<"sendgrid">;
         apiKey: z.ZodString;
-    }, z.core.$strip>;
+    }, z.core.$strict>;
     readonly mailgun: 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>>;
         provider: z.ZodLiteral<"mailgun">;
         apiKey: z.ZodString;
         domain: z.ZodString;
@@ -57,22 +63,24 @@ export declare const providerOptions: {
             us: "us";
             eu: "eu";
         }>>;
-    }, z.core.$strip>;
+    }, z.core.$strict>;
     readonly ses: 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>>;
         provider: z.ZodLiteral<"ses">;
         region: z.ZodString;
-    }, z.core.$strip>;
+    }, z.core.$strict>;
     readonly smtp: 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>>;
         provider: z.ZodLiteral<"smtp">;
         host: z.ZodString;
         port: z.ZodNumber;
@@ -83,7 +91,7 @@ export declare const providerOptions: {
         connectionTimeout: z.ZodDefault<z.ZodNumber>;
         greetingTimeout: z.ZodDefault<z.ZodNumber>;
         socketTimeout: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip>;
+    }, z.core.$strict>;
 };
 export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
@@ -91,38 +99,43 @@ 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.$strip>, z.ZodObject<{
+}, z.core.$strict>, 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>>;
     provider: z.ZodLiteral<"brevo">;
     apiKey: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
+}, z.core.$strict>, 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>>;
     provider: z.ZodLiteral<"postmark">;
     apiKey: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
+}, z.core.$strict>, 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>>;
     provider: z.ZodLiteral<"sendgrid">;
     apiKey: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
+}, z.core.$strict>, 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>>;
     provider: z.ZodLiteral<"mailgun">;
     apiKey: z.ZodString;
     domain: z.ZodString;
@@ -130,20 +143,22 @@ export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         us: "us";
         eu: "eu";
     }>>;
-}, z.core.$strip>, z.ZodObject<{
+}, z.core.$strict>, 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>>;
     provider: z.ZodLiteral<"ses">;
     region: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
+}, z.core.$strict>, 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>>;
     provider: z.ZodLiteral<"smtp">;
     host: z.ZodString;
     port: z.ZodNumber;
@@ -154,7 +169,7 @@ export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     connectionTimeout: z.ZodDefault<z.ZodNumber>;
     greetingTimeout: z.ZodDefault<z.ZodNumber>;
     socketTimeout: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip>], "provider">;
+}, z.core.$strict>], "provider">;
 export type MailerOptions = z.input<typeof mailerOptionsSchema>;
 export type ParsedMailerOptions = z.output<typeof mailerOptionsSchema>;
 export declare function loadProvider(options: ParsedMailerOptions): Promise<MailProvider>;

package/dist/providers/registry.js

@@ -1,14 +1,16 @@
 import { z } from 'zod';
 import { MailError } from '../errors.js';
-export const mailerBaseOptionsSchema = z.object({
-    from: z.union([
-        z.string().email(),
-        z.string().regex(/^.+ <[^<>\s]+@[^<>\s]+>$/, 'Use a valid email address or "Name <email@example.com>".'),
-        z.object({ email: z.string().email(), name: z.string().optional() }).strict(),
-    ]),
+import { senderSchema } from '../config.js';
+export const mailerBaseOptionsSchema = z
+    .object({
+    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 = {
     resend: mailerBaseOptionsSchema.extend({ provider: z.literal('resend'), apiKey: z.string().min(1) }),
     brevo: mailerBaseOptionsSchema.extend({ provider: z.literal('brevo'), apiKey: z.string().min(1) }),

package/dist/providers/resend.js

@@ -28,7 +28,7 @@ export function createResendProvider(options) {
                     ? {
                         attachments: input.attachments.map((attachment) => ({
                             filename: attachment.filename,
-                            content: typeof attachment.content === 'string' ? attachment.content : Buffer.from(attachment.content),
+                            content: Buffer.from(attachment.content).toString('base64'),
                             ...(attachment.contentType ? { contentType: attachment.contentType } : {}),
                             ...(attachment.contentId ? { contentId: attachment.contentId } : {}),
                         })),

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

@@ -1,9 +1,11 @@
 import { MailError } from './errors.js';
-import { mailInputSchema } from './config.js';
+import { mailInputSchema, senderSchema } from './config.js';
 /** In-memory mailer for application tests and local flows. It never sends network requests. */
 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);
@@ -15,10 +17,10 @@ export function createTestMailer(options) {
         },
         async send(input) {
             assertOpen();
-            const message = { ...input, from: input.from ?? options.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>;