typedmailer 1.3.0 → 2.0.0

package/README.md

@@ -39,8 +39,12 @@ 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.
+
 Supported runtime and release guarantees are documented in [`SUPPORT.md`](SUPPORT.md). Provider behavior guarantees and their test coverage are described in [`docs/provider-contracts.md`](docs/provider-contracts.md). The scheduled and manual provider smoke workflow is documented in [`docs/integration-testing.md`](docs/integration-testing.md).
 
 TypedMailer is for trusted server-side Node.js runtimes. It is not intended for browser or mobile client bundles.
@@ -132,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({
@@ -160,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()` |
@@ -200,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({
@@ -230,7 +236,7 @@ Messages captured by `createTestMailer` return `provider: 'test'` so test result
 
 ## 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
 

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/index.d.ts

@@ -1,8 +1,8 @@
 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';

package/dist/index.js

@@ -109,6 +109,11 @@ export function createMailer(input) {
             };
             try {
                 const result = await runWithProvider((provider) => provider.send(normalized));
+                if (typeof result?.messageId !== 'string' || result.messageId.trim().length === 0) {
+                    throw new MailError('The provider returned no message identifier.', 'provider', providerName, false, {
+                        deliveryUnknown: true,
+                    });
+                }
                 return {
                     provider: providerName,
                     messageId: result.messageId,

package/dist/providers/brevo.js

@@ -44,7 +44,7 @@ export function createBrevoProvider(options) {
                 return { messageId: result.messageId };
             }
             catch (error) {
-                throw normalizeProviderError(error, 'brevo');
+                throw normalizeProviderError(error, 'brevo', 'send');
             }
         },
         async verifyConnection() {

package/dist/providers/mailgun.js

@@ -62,7 +62,7 @@ export function createMailgunProvider(options) {
                 return { messageId: response.id };
             }
             catch (error) {
-                throw normalizeProviderError(error, 'mailgun');
+                throw normalizeProviderError(error, 'mailgun', 'send');
             }
         },
         async verifyConnection() {

package/dist/providers/postmark.js

@@ -42,7 +42,7 @@ export function createPostmarkProvider(options) {
                 return { messageId: response.MessageID };
             }
             catch (error) {
-                throw normalizeProviderError(error, 'postmark');
+                throw normalizeProviderError(error, 'postmark', 'send');
             }
         },
         async verifyConnection() {

package/dist/providers/registry.d.ts

@@ -6,7 +6,7 @@ export declare const mailerBaseOptionsSchema: z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>]>;
     maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
+}, z.core.$strict>;
 export declare const providerOptions: {
     readonly resend: z.ZodObject<{
         from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
@@ -16,7 +16,7 @@ export declare const providerOptions: {
         maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
         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;
@@ -25,7 +25,7 @@ export declare const providerOptions: {
         maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
         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;
@@ -34,7 +34,7 @@ export declare const providerOptions: {
         maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
         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;
@@ -43,7 +43,7 @@ export declare const providerOptions: {
         maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
         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;
@@ -57,7 +57,7 @@ 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;
@@ -66,7 +66,7 @@ export declare const providerOptions: {
         maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
         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;
@@ -77,12 +77,13 @@ export declare const providerOptions: {
         host: z.ZodString;
         port: z.ZodNumber;
         secure: z.ZodBoolean;
+        requireTLS: z.ZodOptional<z.ZodBoolean>;
         user: z.ZodOptional<z.ZodString>;
         password: z.ZodOptional<z.ZodString>;
         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<{
@@ -92,7 +93,7 @@ export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
     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>;
@@ -100,7 +101,7 @@ export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
     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>;
@@ -108,7 +109,7 @@ export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
     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>;
@@ -116,7 +117,7 @@ export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
     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>;
@@ -129,7 +130,7 @@ 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>;
@@ -137,7 +138,7 @@ export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
     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>;
@@ -147,12 +148,13 @@ export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     host: z.ZodString;
     port: z.ZodNumber;
     secure: z.ZodBoolean;
+    requireTLS: z.ZodOptional<z.ZodBoolean>;
     user: z.ZodOptional<z.ZodString>;
     password: z.ZodOptional<z.ZodString>;
     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,13 @@
 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(),
-});
+})
+    .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) }),
@@ -27,6 +26,7 @@ export const providerOptions = {
         host: z.string().min(1),
         port: z.number().int().min(1).max(65535),
         secure: z.boolean(),
+        requireTLS: z.boolean().optional(),
         user: z.string().min(1).optional(),
         password: z.string().min(1).optional(),
         connectionTimeout: z.number().int().positive().default(8_000),
@@ -80,6 +80,7 @@ export async function loadProvider(options) {
                     host: options.host,
                     port: options.port,
                     secure: options.secure,
+                    ...(options.requireTLS !== undefined ? { requireTLS: options.requireTLS } : {}),
                     ...(options.user ? { user: options.user } : {}),
                     ...(options.password ? { password: options.password } : {}),
                     connectionTimeout: options.connectionTimeout,

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

@@ -50,7 +50,7 @@ export function createSendGridProvider(options) {
                 return { messageId };
             }
             catch (error) {
-                throw normalizeProviderError(error, 'sendgrid');
+                throw normalizeProviderError(error, 'sendgrid', 'send');
             }
         },
         async verifyConnection() {

package/dist/providers/ses.js

@@ -55,7 +55,7 @@ export function createSesProvider(options) {
                 return { messageId: response.MessageId };
             }
             catch (error) {
-                throw normalizeProviderError(error, 'ses');
+                throw normalizeProviderError(error, 'ses', 'send');
             }
         },
         async verifyConnection() {

package/dist/providers/smtp.d.ts

@@ -3,6 +3,7 @@ interface SmtpOptions {
     host: string;
     port: number;
     secure: boolean;
+    requireTLS?: boolean;
     user?: string;
     password?: string;
     connectionTimeout: number;

package/dist/providers/smtp.js

@@ -11,7 +11,7 @@ export function createSmtpProvider(options) {
         host: options.host,
         port: options.port,
         secure: options.secure,
-        ...(options.port === 587 && !options.secure ? { requireTLS: true } : {}),
+        requireTLS: options.requireTLS ?? (options.port === 587 && !options.secure),
         connectionTimeout: options.connectionTimeout,
         greetingTimeout: options.greetingTimeout,
         socketTimeout: options.socketTimeout,
@@ -53,7 +53,7 @@ export function createSmtpProvider(options) {
                 return { messageId: result.messageId };
             }
             catch (error) {
-                throw normalizeProviderError(error, 'smtp');
+                throw normalizeProviderError(error, 'smtp', 'send');
             }
         },
         async verifyConnection() {

package/dist/testing.js

@@ -1,7 +1,8 @@
 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;
     const assertOpen = () => {
@@ -15,7 +16,7 @@ export function createTestMailer(options) {
         },
         async send(input) {
             assertOpen();
-            const message = { ...input, from: input.from ?? options.from };
+            const message = { ...input, from: input.from ?? from };
             mailInputSchema.parse(message);
             sent.push(message);
             return { provider: 'test', messageId: `test-${sent.length}`, acceptedAt: new Date() };

package/dist/webhooks/normalize.d.ts

@@ -1,6 +1,6 @@
 import type { EmailWebhookEvent } from './types.js';
 export declare function normalizeResend(payload: unknown): readonly EmailWebhookEvent[];
 export declare function normalizeMailgun(payload: unknown): readonly EmailWebhookEvent[];
-export declare function normalizeSendGrid(payload: unknown): readonly EmailWebhookEvent[];
-export declare function normalizeSes(payload: unknown): readonly EmailWebhookEvent[];
-export declare function normalizeProviderEvents(provider: 'brevo' | 'postmark', payload: unknown): readonly EmailWebhookEvent[];
+export declare function normalizeSendGrid(payload: unknown, maxEvents: number): readonly EmailWebhookEvent[];
+export declare function normalizeSes(payload: unknown, maxEvents: number): readonly EmailWebhookEvent[];
+export declare function normalizeProviderEvents(provider: 'brevo' | 'postmark', payload: unknown, maxEvents: number): readonly EmailWebhookEvent[];

package/dist/webhooks/normalize.js

@@ -31,9 +31,10 @@ export function normalizeMailgun(payload) {
         }),
     ];
 }
-export function normalizeSendGrid(payload) {
-    if (!Array.isArray(payload))
+export function normalizeSendGrid(payload, maxEvents) {
+    if (!Array.isArray(payload) || payload.length > maxEvents) {
         throw new WebhookVerificationError('invalid_payload');
+    }
     return payload.map((item) => {
         const event = asRecord(item);
         const eventName = asString(event.event);
@@ -47,7 +48,7 @@ export function normalizeSendGrid(payload) {
         });
     });
 }
-export function normalizeSes(payload) {
+export function normalizeSes(payload, maxEvents) {
     const message = asRecord(payload);
     const eventName = asString(message.eventType) ?? asString(message.notificationType);
     const mail = asRecord(message.mail);
@@ -59,6 +60,10 @@ export function normalizeSes(payload) {
         : Array.isArray(complaint?.complainedRecipients)
             ? complaint.complainedRecipients
             : [];
+    if (recipients.length > maxEvents ||
+        (!recipients.length && Array.isArray(mail.destination) && mail.destination.length > maxEvents)) {
+        throw new WebhookVerificationError('invalid_payload');
+    }
     const to = recipients.map((recipient) => asString(asRecord(recipient).emailAddress)).filter(isString);
     const emails = to.length > 0 ? to : asStringArray(mail.destination);
     return emails.length > 0
@@ -80,8 +85,10 @@ export function normalizeSes(payload) {
             }),
         ];
 }
-export function normalizeProviderEvents(provider, payload) {
+export function normalizeProviderEvents(provider, payload, maxEvents) {
     const items = Array.isArray(payload) ? payload : [payload];
+    if (items.length > maxEvents)
+        throw new WebhookVerificationError('invalid_payload');
     return items.map((item) => {
         const event = asRecord(item);
         const eventName = provider === 'brevo' ? asString(event.event) : asString(event.RecordType);

package/dist/webhooks/types.d.ts

@@ -16,6 +16,7 @@ interface RawWebhookInput {
     readonly rawBody: string | Uint8Array;
     readonly headers: WebhookHeaders;
     readonly maxBodyBytes?: number;
+    readonly maxEvents?: number;
     readonly now?: Date;
     readonly toleranceSeconds?: number;
 }

package/dist/webhooks.js

@@ -1,12 +1,18 @@
 import { WebhookVerificationError } from './webhooks/types.js';
 import { verifyAuthorization, verifyMailgun, verifyResend, verifySendGrid, verifySnsNotification, } from './webhooks/signatures.js';
 import { normalizeMailgun, normalizeProviderEvents, normalizeResend, normalizeSendGrid, normalizeSes, } from './webhooks/normalize.js';
+const DEFAULT_MAX_BODY_BYTES = 1_048_576;
+const DEFAULT_MAX_EVENTS = 1_000;
 export { WebhookVerificationError } from './webhooks/types.js';
 /** Authenticates a provider webhook before returning normalized, typed email events. */
 export async function verifyWebhook(input) {
     const rawBodyByteLength = typeof input.rawBody === 'string' ? Buffer.byteLength(input.rawBody) : input.rawBody.byteLength;
-    if (input.maxBodyBytes !== undefined &&
-        (!Number.isSafeInteger(input.maxBodyBytes) || input.maxBodyBytes < 1 || rawBodyByteLength > input.maxBodyBytes)) {
+    const maxBodyBytes = input.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes < 1 || rawBodyByteLength > maxBodyBytes) {
+        throw new WebhookVerificationError('invalid_payload');
+    }
+    const maxEvents = input.maxEvents ?? DEFAULT_MAX_EVENTS;
+    if (!Number.isSafeInteger(maxEvents) || maxEvents < 1) {
         throw new WebhookVerificationError('invalid_payload');
     }
     const rawBody = Buffer.from(input.rawBody);
@@ -26,12 +32,12 @@ export async function verifyWebhook(input) {
             return normalizeMailgun(payload);
         case 'sendgrid':
             verifySendGrid(input, rawBody);
-            return normalizeSendGrid(payload);
+            return normalizeSendGrid(payload, maxEvents);
         case 'brevo':
         case 'postmark':
             verifyAuthorization(input, input.authorizationHeader ?? 'authorization');
-            return normalizeProviderEvents(input.provider, payload);
+            return normalizeProviderEvents(input.provider, payload, maxEvents);
         case 'ses':
-            return normalizeSes(await verifySnsNotification(input, payload));
+            return normalizeSes(await verifySnsNotification(input, payload), maxEvents);
     }
 }

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,7 @@ 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`.
 - 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 +23,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
 

package/docs/webhooks.md

@@ -2,9 +2,11 @@
 
 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. You can also set `maxBodyBytes` on `verifyWebhook()` to reject an oversized payload before JSON parsing; it has no default because provider event batches vary in size.
+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.
 
 ## Authentication configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typedmailer",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "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",
@@ -36,7 +36,9 @@
     "docs/integration-testing.md",
     "docs/quickstart.md",
     "docs/webhooks.md",
-    "CODE_OF_CONDUCT.md"
+    "CODE_OF_CONDUCT.md",
+    "docs/migration-v2.md",
+    "docs/framework-webhooks.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -67,7 +69,7 @@
     "zod": "^4.6.5"
   },
   "peerDependencies": {
-    "@aws-sdk/client-sesv2": ">=3.0.0 <4",
+    "@aws-sdk/client-sesv2": ">=3.797.0 <4",
     "@getbrevo/brevo": ">=6.0.1 <7",
     "@sendgrid/mail": ">=8.0.0 <9",
     "form-data": ">=4.0.0 <5",
@@ -103,12 +105,14 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-sesv2": ">=3.0.0 <4",
+    "@aws-sdk/client-sesv2": ">=3.797.0 <4",
     "@getbrevo/brevo": ">=6.0.1 <7",
     "@sendgrid/mail": ">=8.0.0 <9",
+    "@types/express": "^5.0.6",
     "@types/node": "^26.6.3",
     "@types/nodemailer": "^8.0.2",
     "eslint": "^10.11.0",
+    "express": "^5.2.1",
     "form-data": ">=4.0.0 <5",
     "husky": "^9.1.7",
     "lint-staged": "^17.6.0",