typedmailer 1.2.0 → 1.4.0

package/README.md

@@ -41,6 +41,8 @@ npm install typedmailer @aws-sdk/client-sesv2
 
 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.
@@ -176,6 +178,32 @@ Provider capabilities differ. Unsupported fields return a `MailError` with code
 | Amazon SES | No                 | No               | Yes      | Yes                | Unsupported          |
 | SMTP       | Yes                | No               | No       | Yes                | Yes                  |
 
+### Custom providers
+
+Use `ProviderAdapter` when your provider is not built in or you need to wrap an existing mail SDK. The adapter receives normalized addresses and the configured default sender; its `send` method must resolve with the provider message ID. Implement `verifyConnection` only when the provider offers a safe connection check, and use `close` to release resources such as pooled clients.
+
+```ts
+import { createMailer, type ProviderAdapter } from 'typedmailer';
+
+const adapter: ProviderAdapter<'acme'> = {
+  name: 'acme',
+  async send(message) {
+    const response = await acmeClient.sendEmail(message);
+    return { messageId: response.id };
+  },
+  async close() {
+    await acmeClient.close();
+  },
+};
+
+const mailer = createMailer({ provider: adapter, from: 'noreply@example.com' });
+const result = await mailer.send({ to: 'person@example.com', subject: 'Hello', text: 'Hi' });
+// result.provider is typed as "acme".
+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.
+
 ```ts
 await mailer.send({
   to: [{ email: 'person@example.com', name: 'Sam' }],

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { MailAddress } from './types.js';
 export declare const mailInputSchema: z.ZodObject<{
     from: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
         email: z.ZodString;
@@ -44,14 +45,8 @@ export declare const mailInputSchema: z.ZodObject<{
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strict>;
 export declare function normalizeAddresses<T>(value: T | readonly T[] | undefined): readonly T[] | undefined;
-export declare function emailOf(address: string | {
-    email: string;
-    name?: string;
-}): string;
-export declare function addressWithName(address: string | {
-    email: string;
-    name?: string;
-}): {
+export declare function emailOf(address: MailAddress): string;
+export declare function addressWithName(address: MailAddress): {
     email: string;
     name?: string;
 };

package/dist/config.js

@@ -53,8 +53,9 @@ export function emailOf(address) {
     return namedAddress?.[2] ?? address;
 }
 export function addressWithName(address) {
-    if (typeof address !== 'string')
-        return address;
+    if (typeof address !== 'string') {
+        return { email: address.email, ...(address.name !== undefined ? { name: address.name } : {}) };
+    }
     const namedAddress = address.match(/^(.+) <([^<>\s]+@[^<>\s]+)>$/);
     return namedAddress ? { email: namedAddress[2], name: namedAddress[1] } : { email: address };
 }

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-import { type MailerOptions } from './providers/registry.js';
-import type { Mailer } from './types.js';
-export type { MailerOptions };
-export declare function createMailer(input: MailerOptions): Mailer;
+import { type MailerOptions as BuiltInMailerOptions } from './providers/registry.js';
+import type { CustomMailerOptions, Mailer, ProviderName } 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(input: MailerOptions): Mailer<string>;
 export { MailError } from './errors.js';
 export type { MailErrorCode, MailErrorOperation, MailErrorOptions } from './errors.js';
-export type { MailAddress, MailAttachment, Mailer, NormalizedMailInput, ProviderName, SendMailInput, SendMailResult, } from './types.js';
+export type { CustomMailerOptions, MailAddress, MailAttachment, Mailer, NormalizedMailInput, ProviderAdapter, ProviderName, ProviderSendResult, SendMailInput, SendMailResult, } from './types.js';

package/dist/index.js

@@ -1,21 +1,59 @@
 import { Buffer } from 'node:buffer';
+import { z } from 'zod';
 import { MailError, normalizeProviderError } from './errors.js';
 import { mailInputSchema, normalizeAddresses } from './config.js';
-import { loadProvider, mailerOptionsSchema } from './providers/registry.js';
+import { loadProvider, mailerBaseOptionsSchema, mailerOptionsSchema, } from './providers/registry.js';
+function isProviderAdapter(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const adapter = value;
+    return (typeof adapter.name === 'string' &&
+        adapter.name.length > 0 &&
+        adapter.name.trim() === adapter.name &&
+        typeof adapter.send === 'function' &&
+        (adapter.verifyConnection === undefined || typeof adapter.verifyConnection === 'function') &&
+        (adapter.close === undefined || typeof adapter.close === 'function'));
+}
+const customMailerOptionsSchema = mailerBaseOptionsSchema
+    .extend({ provider: z.custom(isProviderAdapter, 'Invalid custom provider adapter.') })
+    .strict();
+function isCustomOptions(input) {
+    return typeof input.provider !== 'string';
+}
+function createCustomProvider(adapter) {
+    return {
+        send: (input) => adapter.send(input),
+        async verifyConnection() {
+            if (!adapter.verifyConnection) {
+                throw new MailError(`Connection verification is not supported by the custom provider "${adapter.name}".`, 'unsupported', adapter.name, false);
+            }
+            await adapter.verifyConnection();
+        },
+        async close() {
+            await adapter.close?.();
+        },
+    };
+}
 export function createMailer(input) {
     let providerPromise;
     let closed = false;
     let closePromise;
     let activeOperations = 0;
     let resolveOperationsIdle;
-    const parsedOptions = mailerOptionsSchema.parse(input);
+    const parsedOptions = isCustomOptions(input)
+        ? customMailerOptionsSchema.parse(input)
+        : mailerOptionsSchema.parse(input);
+    const providerName = typeof parsedOptions.provider === 'string' ? parsedOptions.provider : parsedOptions.provider.name;
     const assertOpen = () => {
         if (closed)
-            throw new MailError('Mailer has been closed.', 'configuration', parsedOptions.provider, false);
+            throw new MailError('Mailer has been closed.', 'configuration', providerName, false);
     };
     const getProvider = () => {
         assertOpen();
-        providerPromise ??= loadProvider(parsedOptions);
+        providerPromise ??=
+            typeof parsedOptions.provider === 'string'
+                ? loadProvider(parsedOptions)
+                : Promise.resolve(createCustomProvider(parsedOptions.provider));
         return providerPromise;
     };
     const runWithProvider = async (operation) => {
@@ -41,11 +79,13 @@ export function createMailer(input) {
                     ? Buffer.byteLength(attachment.content)
                     : attachment.content.byteLength), 0) ?? 0;
             if (parsedOptions.maxAttachmentBytes !== undefined && attachmentBytes > parsedOptions.maxAttachmentBytes) {
-                throw new MailError(`Attachment content exceeds the configured limit of ${parsedOptions.maxAttachmentBytes} bytes.`, 'configuration', parsedOptions.provider, false);
+                throw new MailError(`Attachment content exceeds the configured limit of ${parsedOptions.maxAttachmentBytes} bytes.`, 'configuration', providerName, false);
             }
+            const cc = normalizeAddresses(parsed.cc);
+            const bcc = normalizeAddresses(parsed.bcc);
             const normalized = {
-                from: (parsed.from ?? parsedOptions.from),
-                to: (normalizeAddresses(parsed.to) ?? []),
+                from: parsed.from ?? parsedOptions.from,
+                to: normalizeAddresses(parsed.to) ?? [],
                 subject: parsed.subject,
                 ...(parsed.messageId ? { messageId: parsed.messageId } : {}),
                 ...(parsed.text !== undefined ? { text: parsed.text } : {}),
@@ -63,24 +103,20 @@ export function createMailer(input) {
                     : {}),
                 ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
                 ...(parsed.metadata ? { metadata: parsed.metadata } : {}),
-                ...(normalizeAddresses(parsed.cc)
-                    ? { cc: normalizeAddresses(parsed.cc) }
-                    : {}),
-                ...(normalizeAddresses(parsed.bcc)
-                    ? { bcc: normalizeAddresses(parsed.bcc) }
-                    : {}),
+                ...(cc ? { cc } : {}),
+                ...(bcc ? { bcc } : {}),
                 ...(parsed.replyTo ? { replyTo: parsed.replyTo } : {}),
             };
             try {
                 const result = await runWithProvider((provider) => provider.send(normalized));
                 return {
-                    provider: parsedOptions.provider,
+                    provider: providerName,
                     messageId: result.messageId,
                     acceptedAt: new Date(),
                 };
             }
             catch (error) {
-                throw normalizeProviderError(error, parsedOptions.provider, 'send');
+                throw normalizeProviderError(error, providerName, 'send');
             }
         },
         async verifyConnection() {
@@ -88,7 +124,7 @@ export function createMailer(input) {
                 await runWithProvider((provider) => provider.verifyConnection());
             }
             catch (error) {
-                throw normalizeProviderError(error, parsedOptions.provider);
+                throw normalizeProviderError(error, providerName);
             }
         },
         async close() {

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

@@ -1,5 +1,12 @@
 import { z } from 'zod';
 import type { MailProvider } 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>;
 export declare const providerOptions: {
     readonly resend: z.ZodObject<{
         from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
@@ -70,6 +77,7 @@ 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>;
@@ -140,6 +148,7 @@ 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>;

package/dist/providers/registry.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { MailError } from '../errors.js';
-const baseOptions = z.object({
+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>".'),
@@ -10,23 +10,24 @@ const baseOptions = z.object({
     maxAttachmentBytes: z.number().int().positive().optional(),
 });
 export const providerOptions = {
-    resend: baseOptions.extend({ provider: z.literal('resend'), apiKey: z.string().min(1) }),
-    brevo: baseOptions.extend({ provider: z.literal('brevo'), apiKey: z.string().min(1) }),
-    postmark: baseOptions.extend({ provider: z.literal('postmark'), apiKey: z.string().min(1) }),
-    sendgrid: baseOptions.extend({ provider: z.literal('sendgrid'), apiKey: z.string().min(1) }),
-    mailgun: baseOptions.extend({
+    resend: mailerBaseOptionsSchema.extend({ provider: z.literal('resend'), apiKey: z.string().min(1) }),
+    brevo: mailerBaseOptionsSchema.extend({ provider: z.literal('brevo'), apiKey: z.string().min(1) }),
+    postmark: mailerBaseOptionsSchema.extend({ provider: z.literal('postmark'), apiKey: z.string().min(1) }),
+    sendgrid: mailerBaseOptionsSchema.extend({ provider: z.literal('sendgrid'), apiKey: z.string().min(1) }),
+    mailgun: mailerBaseOptionsSchema.extend({
         provider: z.literal('mailgun'),
         apiKey: z.string().min(1),
         domain: z.string().min(1),
         region: z.enum(['us', 'eu']).default('us'),
     }),
-    ses: baseOptions.extend({ provider: z.literal('ses'), region: z.string().min(1) }),
-    smtp: baseOptions
+    ses: mailerBaseOptionsSchema.extend({ provider: z.literal('ses'), region: z.string().min(1) }),
+    smtp: mailerBaseOptionsSchema
         .extend({
         provider: z.literal('smtp'),
         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 +81,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/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.d.ts

@@ -2,7 +2,7 @@ import type { Mailer, SendMailInput } from './types.js';
 export interface CapturedMail extends SendMailInput {
     readonly from: NonNullable<SendMailInput['from']>;
 }
-export interface TestMailer extends Mailer {
+export interface TestMailer extends Mailer<'test'> {
     readonly sent: CapturedMail[];
     clear(): void;
 }

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 export type MailAddress = string | {
     readonly email: string;
-    readonly name?: string;
+    readonly name?: string | undefined;
 };
 export interface MailAttachment {
     readonly filename: string;
@@ -24,18 +24,29 @@ export interface SendMailInput {
     readonly metadata?: Readonly<Record<string, string>>;
 }
 export type ProviderName = 'resend' | 'brevo' | 'smtp' | 'postmark' | 'sendgrid' | 'mailgun' | 'ses';
-export interface SendMailResult {
-    readonly provider: ProviderName | 'test';
+export interface SendMailResult<TProvider extends string = ProviderName | 'test'> {
+    readonly provider: TProvider;
     readonly messageId: string;
     /** Time when the provider accepted the request. This does not confirm inbox delivery. */
     readonly acceptedAt: Date;
 }
-export interface Mailer {
-    send(input: SendMailInput): Promise<SendMailResult>;
+export interface Mailer<TProvider extends string = ProviderName | 'test'> {
+    send(input: SendMailInput): Promise<SendMailResult<TProvider>>;
     verifyConnection(): Promise<void>;
     /** Rejects new operations, waits for active operations, and closes the provider at most once. */
     close(): Promise<void>;
 }
+export interface ProviderAdapter<TProvider extends string = string> {
+    readonly name: TProvider;
+    send(input: NormalizedMailInput): Promise<ProviderSendResult>;
+    verifyConnection?(): Promise<void>;
+    close?(): Promise<void> | void;
+}
+export interface CustomMailerOptions<TProvider extends string = string> {
+    readonly provider: ProviderAdapter<TProvider>;
+    readonly from: MailAddress;
+    readonly maxAttachmentBytes?: number;
+}
 export interface NormalizedMailInput extends Omit<SendMailInput, 'from' | 'to' | 'cc' | 'bcc' | 'replyTo'> {
     readonly from: MailAddress;
     readonly to: readonly MailAddress[];

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

@@ -15,6 +15,8 @@ export type WebhookHeaders = Readonly<Record<string, string | readonly string[]
 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,9 +1,20 @@
 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;
+    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);
     let payload;
     try {
@@ -21,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/provider-contracts.md

@@ -1,6 +1,6 @@
 # Provider behavior contracts
 
-The adapters provide one `createMailer(...).send(...)` interface, while provider APIs differ. This page records the behavior callers may rely on. The capability table in the README is the quick reference; adapter contract tests in `tests/provider-adapters.test.ts` are the executable mapping checks.
+The adapters provide one `createMailer(...).send(...)` interface, while provider APIs differ. This page records the behavior callers may rely on. The capability table in the README is the quick reference; built-in adapter contract tests are organized by provider under `tests/providers/`.
 
 ## Shared guarantees
 
@@ -28,3 +28,7 @@ Attachments are buffered for provider SDK requests. Configure `maxAttachmentByte
 ## Updating a provider adapter
 
 When changing an adapter, add its configuration schema and lazy loader in `src/providers/registry.ts`, keep its implementation in `src/providers/<provider>.ts`, and update the README capability table and this contract if caller-visible behavior changes. Add or adjust adapter tests for the provider payload, unsupported fields, returned message ID, and error normalization. Keep provider SDK versions within the declared peer range and verify both the locked SDK and minimum supported SDK set. CI derives the minimum-version install list from each peer range's explicit lower bound so the support metadata and compatibility check stay aligned.
+
+## 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.

package/docs/webhooks.md

@@ -4,7 +4,7 @@ TypedMailer exposes `verifyWebhook()` from `typedmailer/webhooks`. It authentica
 
 ## 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.
+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.2.0",
+  "version": "1.4.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",