@fabrika/email 0.8.1 → 0.9.0-cloudflare.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/email",
-	"version": "0.8.1",
+	"version": "0.9.0-cloudflare.1",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -12,47 +12,68 @@
 	},
 	"files": [
 		"src",
-		"!src/**/__tests__/**"
+		"!src/**/__tests__/**",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
-			"types": "./src/index.ts",
+			"types": "./types/src/index.d.ts",
 			"default": "./src/index.ts"
 		},
 		"./resend": {
 			"bun": "./src/resend.ts",
-			"types": "./src/resend.ts",
+			"types": "./types/src/resend.d.ts",
 			"default": "./src/resend.ts"
 		},
+		"./postmark": {
+			"bun": "./src/postmark.ts",
+			"types": "./types/src/postmark.d.ts",
+			"default": "./src/postmark.ts"
+		},
+		"./ahasend": {
+			"bun": "./src/ahasend.ts",
+			"types": "./types/src/ahasend.d.ts",
+			"default": "./src/ahasend.ts"
+		},
+		"./cloudflare": {
+			"bun": "./src/cloudflare.ts",
+			"types": "./types/src/cloudflare.d.ts",
+			"default": "./src/cloudflare.ts"
+		},
+		"./lettermint": {
+			"bun": "./src/lettermint.ts",
+			"types": "./types/src/lettermint.d.ts",
+			"default": "./src/lettermint.ts"
+		},
 		"./directory": {
 			"bun": "./src/directory.ts",
-			"types": "./src/directory.ts",
+			"types": "./types/src/directory.d.ts",
 			"default": "./src/directory.ts"
 		},
 		"./memory": {
 			"bun": "./src/memory.ts",
-			"types": "./src/memory.ts",
+			"types": "./types/src/memory.d.ts",
 			"default": "./src/memory.ts"
 		},
 		"./smartemailing": {
 			"bun": "./src/smartemailing.ts",
-			"types": "./src/smartemailing.ts",
+			"types": "./types/src/smartemailing.d.ts",
 			"default": "./src/smartemailing.ts"
 		},
 		"./providers": {
 			"bun": "./src/providers.ts",
-			"types": "./src/providers.ts",
+			"types": "./types/src/providers.d.ts",
 			"default": "./src/providers.ts"
 		},
 		"./platform": {
 			"bun": "./src/platform.ts",
-			"types": "./src/platform.ts",
+			"types": "./types/src/platform.d.ts",
 			"default": "./src/platform.ts"
 		},
 		"./conformance": {
 			"bun": "./src/conformance.ts",
-			"types": "./src/conformance.ts",
+			"types": "./types/src/conformance.d.ts",
 			"default": "./src/conformance.ts"
 		}
 	},

package/src/ahasend.ts

@@ -0,0 +1,172 @@
+// AhaSend's API v2 (https://ahasend.com/docs/api-reference/messages/create-message), built from its documentation and
+// verified on a live account in October 2026. It keeps an idempotency key for 24 hours, and a 202 carries one result
+// per recipient, which can itself be a refusal. It renders a message's content as a template only when the request
+// carries substitutions, which this adapter never sends, so `{{` in a message reaches the recipient as written.
+
+import { z } from 'zod'
+import { type EmailProvider, parseProviderVariables } from './config.js'
+import { base64Of } from './content.js'
+import { EmailDeliveryError, type EmailMessage, type EmailSenderCapabilities, oneClickUnsubscribeHeaders } from './email.js'
+import {
+	credentialVariable,
+	type HttpEmailRequest,
+	HttpEmailSender,
+	type HttpEmailSenderOptions,
+	isCredential,
+	optionalVariable,
+	providerIdempotencyKey,
+} from './http-sender.js'
+import type { ProviderResponse } from './http.js'
+import { isValidEmailAddress } from './validation.js'
+
+const AHASEND_API_URL = 'https://api.ahasend.com/v2/accounts'
+const ACCOUNT_ID_PATTERN = /^[A-Za-z0-9-]{1,64}$/
+/** A refusal carries only a free-text `message`, read here to tell a reused key from another 422 and never put into an error. */
+const ahaSendErrorSchema = z.object({ message: z.string() })
+const KEY_REUSED = /idempotency key/i
+const MAX_IDEMPOTENCY_KEY_LENGTH = 255
+const ahaSendResultSchema = z.object({
+	// `queued` and `scheduled` are documented; any status but `error` with an id is taken, so a new one is no failure.
+	data: z.tuple([z.object({ status: z.string(), id: z.string().nullable() })]),
+})
+/**
+ * AhaSend refuses a message over 20 MiB with its attachments base64 and MIME-wrapped; 12 MiB of bytes leaves room for
+ * the bodies, and its body stays under the 30 MB request bound.
+ */
+const AHASEND_MAX_ATTACHMENT_BYTES = 12 * 1024 * 1024
+
+export interface AhaSendEmailSenderOptions extends HttpEmailSenderOptions {
+	/** An API key v2, scoped to `messages:send:{domain}` at least. */
+	readonly apiKey: string
+	/** The account the key belongs to: the path of every request. */
+	readonly accountId: string
+	/**
+	 * The address a `broadcast` message is sent from, on a domain the account has configured as a Marketing domain:
+	 * AhaSend's terms allow marketing mail through the API from such a domain only. Without it, a broadcast is refused.
+	 */
+	readonly broadcastFrom?: string
+}
+
+/** A refusal's body is one free-text `message`, so only the status is read. */
+export class AhaSendEmailSender extends HttpEmailSender {
+	/** `broadcast` only with `broadcastFrom`. */
+	readonly capabilities: EmailSenderCapabilities
+	readonly #apiKey: string
+	readonly #messagesUrl: string
+	readonly #broadcastFrom: string | undefined
+
+	constructor(options: AhaSendEmailSenderOptions) {
+		if (!isCredential(options.apiKey)) {
+			throw new EmailDeliveryError('AhaSend API key is invalid', { code: 'invalid_configuration' })
+		}
+		if (!ACCOUNT_ID_PATTERN.test(options.accountId)) {
+			throw new EmailDeliveryError('AhaSend account ID is invalid', { code: 'invalid_configuration' })
+		}
+		if (options.broadcastFrom !== undefined && !isValidEmailAddress(options.broadcastFrom)) {
+			throw new EmailDeliveryError('AhaSend broadcast sender is invalid', { code: 'invalid_configuration' })
+		}
+		super({ label: 'AhaSend', provider: 'ahasend' }, options)
+		this.#apiKey = options.apiKey
+		this.#messagesUrl = `${AHASEND_API_URL}/${options.accountId}/messages`
+		this.#broadcastFrom = options.broadcastFrom
+		this.capabilities = {
+			idempotent: true,
+			confirmation: 'sync',
+			maxBatch: 1,
+			listUnsubscribe: true,
+			maxAttachmentBytes: AHASEND_MAX_ATTACHMENT_BYTES,
+			...(options.broadcastFrom === undefined ? {} : { broadcast: true }),
+		}
+	}
+
+	protected async request(message: EmailMessage): Promise<HttpEmailRequest> {
+		const senderName = message.fromName ?? this.from.name
+		// `send` refused a broadcast message without `broadcastFrom`; never send one from the transactional domain.
+		const fromAddress = message.broadcast === true ? this.#broadcastFrom : this.from.address
+		if (fromAddress === undefined) throw new EmailDeliveryError('AhaSend sends no broadcast email', { code: 'invalid_message' })
+		const attachments = message.attachments ?? []
+		return {
+			url: this.#messagesUrl,
+			headers: {
+				Authorization: `Bearer ${this.#apiKey}`,
+				'Idempotency-Key': await providerIdempotencyKey(message.idempotencyKey, MAX_IDEMPOTENCY_KEY_LENGTH),
+			},
+			body: {
+				from: {
+					email: fromAddress,
+					...(senderName === undefined ? {} : { name: senderName }),
+				},
+				recipients: [{ email: message.to }],
+				subject: message.subject,
+				text_content: message.text,
+				...(message.html === undefined ? {} : { html_content: message.html }),
+				...(message.replyTo === undefined ? {} : { reply_to: { email: message.replyTo } }),
+				...(message.unsubscribeUrl === undefined ? {} : { headers: oneClickUnsubscribeHeaders(message.unsubscribeUrl) }),
+				...(attachments.length === 0
+					? {}
+					: {
+						attachments: attachments.map((attachment) => ({
+							base64: true,
+							data: base64Of(attachment.content),
+							content_type: attachment.contentType,
+							file_name: attachment.filename,
+						})),
+					}),
+			},
+		}
+	}
+
+	protected messageId(response: ProviderResponse): string | undefined {
+		const result = ahaSendResultSchema.safeParse(response.body).data?.data[0]
+		if (result === undefined) return undefined
+		// The item's `error` is free text about the recipient, so it stays out of the refusal.
+		if (result.status === 'error') {
+			throw new EmailDeliveryError(`AhaSend refused the recipient (${response.status})`, { code: 'provider_rejected', httpStatus: response.status })
+		}
+		return result.id ?? undefined
+	}
+
+	protected override refusal(response: ProviderResponse): EmailDeliveryError | undefined {
+		const status = response.status
+		// Documented for an unknown account; a key of another account answers 401.
+		if (status === 404) {
+			return new EmailDeliveryError('AhaSend knows no such account (404)', { code: 'provider_unauthorized', httpStatus: status })
+		}
+		// Live, a concurrent request under the key waited for the first and replayed its answer; 409 is documented.
+		if (status === 409) {
+			return new EmailDeliveryError('A matching AhaSend request is still in progress', { code: 'request_in_progress', httpStatus: status })
+		}
+		// A malformed body is a 400; a 422 names the key reused for another request, and any other is a rejection.
+		if (status === 422 && KEY_REUSED.test(ahaSendErrorSchema.safeParse(response.body).data?.message ?? '')) {
+			return new EmailDeliveryError('AhaSend refused the idempotency key for this request (422)', {
+				code: 'idempotency_conflict',
+				httpStatus: status,
+			})
+		}
+		return undefined
+	}
+}
+
+const ahaSendVariablesSchema = z.object({
+	FABRIKA_EMAIL_AHASEND_API_KEY: credentialVariable,
+	FABRIKA_EMAIL_AHASEND_ACCOUNT_ID: z.string().regex(ACCOUNT_ID_PATTERN),
+	FABRIKA_EMAIL_AHASEND_BROADCAST_FROM: optionalVariable(isValidEmailAddress),
+})
+
+export const ahaSendEmailProvider: EmailProvider = {
+	variables: [
+		{ name: 'FABRIKA_EMAIL_AHASEND_API_KEY', secret: true, required: true },
+		{ name: 'FABRIKA_EMAIL_AHASEND_ACCOUNT_ID', secret: false, required: true },
+		{ name: 'FABRIKA_EMAIL_AHASEND_BROADCAST_FROM', secret: false, required: false },
+	],
+	create({ from, env, fetch }) {
+		const variables = parseProviderVariables(ahaSendVariablesSchema, env)
+		return new AhaSendEmailSender({
+			apiKey: variables.FABRIKA_EMAIL_AHASEND_API_KEY,
+			accountId: variables.FABRIKA_EMAIL_AHASEND_ACCOUNT_ID,
+			broadcastFrom: variables.FABRIKA_EMAIL_AHASEND_BROADCAST_FROM,
+			from,
+			fetch,
+		})
+	},
+}

package/src/cloudflare.ts

@@ -0,0 +1,142 @@
+// Cloudflare Email Service's Email Sending REST API (https://developers.cloudflare.com/email-service/api/send-emails/rest-api/),
+// built from its documentation in October 2026 and verified only against a stubbed fetch. It has no idempotency key,
+// and Cloudflare takes transactional mail only. The REST API, not the Workers `send_email` binding, so the transport is
+// one set of `FABRIKA_EMAIL_*` on every runtime that sends: a Worker, a Bun process on Zerops, an application.
+
+import { z } from 'zod'
+import { type EmailProvider, parseProviderVariables } from './config.js'
+import { base64Of } from './content.js'
+import { EmailDeliveryError, type EmailMessage, type EmailSenderCapabilities, oneClickUnsubscribeHeaders } from './email.js'
+import { credentialVariable, type HttpEmailRequest, HttpEmailSender, type HttpEmailSenderOptions, isCredential } from './http-sender.js'
+import type { ProviderResponse } from './http.js'
+
+const CLOUDFLARE_ACCOUNTS_URL = 'https://api.cloudflare.com/client/v4/accounts'
+/** A Cloudflare account ID: 32 hexadecimal digits, the path of every request. */
+const ACCOUNT_ID_PATTERN = /^[0-9a-fA-F]{32}$/
+const cloudflareSuccessSchema = z.object({
+	success: z.literal(true),
+	result: z.object({
+		message_id: z.string().optional(),
+		delivered: z.array(z.string()).optional(),
+		queued: z.array(z.string()).optional(),
+		permanent_bounces: z.array(z.string()).optional(),
+		suppressed_recipients: z.array(z.string()).optional(),
+	}),
+})
+/** Cloudflare bounds a custom header's value at 2,048 bytes; the URL travels inside `<…>`. */
+const MAX_HEADER_VALUE_BYTES = 2048
+/**
+ * Cloudflare counts the whole message, attachments base64 and MIME-wrapped, against 5 MiB; 3 MiB of bytes leaves
+ * about a mebibyte for the bodies and the headers.
+ */
+const CLOUDFLARE_MAX_ATTACHMENT_BYTES = 3 * 1024 * 1024
+
+export interface CloudflareEmailSenderOptions extends HttpEmailSenderOptions {
+	/** An account API token with the Email Sending Write permission and nothing else. */
+	readonly apiToken: string
+	/** The account the token sends for: the path of every request. */
+	readonly accountId: string
+}
+
+/** A refusal's body carries numeric codes and machine-readable messages; only the status is read. */
+export class CloudflareEmailSender extends HttpEmailSender {
+	readonly capabilities: EmailSenderCapabilities = {
+		idempotent: false,
+		confirmation: 'sync',
+		maxBatch: 1,
+		listUnsubscribe: true,
+		maxAttachmentBytes: CLOUDFLARE_MAX_ATTACHMENT_BYTES,
+		// Cloudflare Email Service takes transactional mail only, so it sends no broadcast.
+	}
+	readonly #apiToken: string
+	readonly #sendUrl: string
+
+	constructor(options: CloudflareEmailSenderOptions) {
+		if (!isCredential(options.apiToken)) {
+			throw new EmailDeliveryError('Cloudflare API token is invalid', { code: 'invalid_configuration' })
+		}
+		if (!ACCOUNT_ID_PATTERN.test(options.accountId)) {
+			throw new EmailDeliveryError('Cloudflare account ID is invalid', { code: 'invalid_configuration' })
+		}
+		super({ label: 'Cloudflare', provider: 'cloudflare' }, options)
+		this.#apiToken = options.apiToken
+		this.#sendUrl = `${CLOUDFLARE_ACCOUNTS_URL}/${options.accountId}/email/sending/send`
+	}
+
+	protected request(message: EmailMessage): HttpEmailRequest {
+		if (message.unsubscribeUrl !== undefined && new TextEncoder().encode(`<${message.unsubscribeUrl}>`).byteLength > MAX_HEADER_VALUE_BYTES) {
+			throw new EmailDeliveryError('Email unsubscribe URL is invalid', { code: 'invalid_message' })
+		}
+		const senderName = message.fromName ?? this.from.name
+		const attachments = message.attachments ?? []
+		return {
+			url: this.#sendUrl,
+			headers: { Authorization: `Bearer ${this.#apiToken}` },
+			body: {
+				from: { address: this.from.address, ...(senderName === undefined ? {} : { name: senderName }) },
+				to: message.to,
+				subject: message.subject,
+				text: message.text,
+				...(message.html === undefined ? {} : { html: message.html }),
+				...(message.replyTo === undefined ? {} : { reply_to: message.replyTo }),
+				...(message.unsubscribeUrl === undefined ? {} : { headers: oneClickUnsubscribeHeaders(message.unsubscribeUrl) }),
+				...(attachments.length === 0
+					? {}
+					: {
+						attachments: attachments.map((attachment) => ({
+							content: base64Of(attachment.content),
+							filename: attachment.filename,
+							type: attachment.contentType,
+							disposition: 'attachment',
+						})),
+					}),
+			},
+		}
+	}
+
+	protected messageId(response: ProviderResponse, message: EmailMessage): string | undefined {
+		const result = cloudflareSuccessSchema.safeParse(response.body).data?.result
+		if (result === undefined) return undefined
+		const listed = (addresses: readonly string[] | undefined): boolean =>
+			(addresses ?? []).some((address) => address.toLowerCase() === message.to.toLowerCase())
+		// A 200 groups the recipients by outcome; the one recipient listed as bounced or suppressed got nothing. The
+		// lists name the address, so they stay out of the refusal.
+		if (listed(result.permanent_bounces) || listed(result.suppressed_recipients)) {
+			throw new EmailDeliveryError(`Cloudflare refused the recipient (${response.status})`, { code: 'provider_rejected', httpStatus: response.status })
+		}
+		if (result.message_id !== undefined && result.message_id !== '') return result.message_id
+		// The REST guide documents a 200 with the recipients' status and no `message_id`. A recipient delivered or queued
+		// was taken, and the message's own key names that send, the same on every retry of it.
+		if (listed(result.delivered) || listed(result.queued)) return `cloudflare:${message.idempotencyKey}`
+		return undefined
+	}
+
+	protected override refusal(response: ProviderResponse): EmailDeliveryError | undefined {
+		// Documented as a resource not found: under this path, an account the token cannot reach.
+		if (response.status === 404) {
+			return new EmailDeliveryError('Cloudflare knows no such account (404)', { code: 'provider_unauthorized', httpStatus: response.status })
+		}
+		return undefined
+	}
+}
+
+const cloudflareVariablesSchema = z.object({
+	FABRIKA_EMAIL_CLOUDFLARE_API_TOKEN: credentialVariable,
+	FABRIKA_EMAIL_CLOUDFLARE_ACCOUNT_ID: z.string().regex(ACCOUNT_ID_PATTERN),
+})
+
+export const cloudflareEmailProvider: EmailProvider = {
+	variables: [
+		{ name: 'FABRIKA_EMAIL_CLOUDFLARE_API_TOKEN', secret: true, required: true },
+		{ name: 'FABRIKA_EMAIL_CLOUDFLARE_ACCOUNT_ID', secret: false, required: true },
+	],
+	create({ from, env, fetch }) {
+		const variables = parseProviderVariables(cloudflareVariablesSchema, env)
+		return new CloudflareEmailSender({
+			apiToken: variables.FABRIKA_EMAIL_CLOUDFLARE_API_TOKEN,
+			accountId: variables.FABRIKA_EMAIL_CLOUDFLARE_ACCOUNT_ID,
+			from,
+			fetch,
+		})
+	},
+}

package/src/conformance.ts

@@ -26,6 +26,8 @@ export interface WireMessage {
 	readonly unsubscribeUrl?: string
 	/** Each attachment with its bytes as base64. */
 	readonly attachments?: readonly EmailAttachmentContent[]
+	/** Whether the provider got it as broadcast mail, on its channel for them where it has one. */
+	readonly broadcast?: boolean
 }
 
 /** A stored or sent message in wire terms: what a local harness answers for an `EmailMessage` it kept. */
@@ -99,6 +101,8 @@ const UNSUBSCRIBE_MESSAGE: EmailMessage = {
 	unsubscribeUrl: 'https://app.example.test/api/mail.unsubscribe?t=conformance-token-6c2e',
 }
 
+const BROADCAST_MESSAGE: EmailMessage = { ...UNSUBSCRIBE_MESSAGE, idempotencyKey: 'conformance/broadcast-1', broadcast: true }
+
 const ATTACHMENT_MESSAGE: EmailMessage = {
 	...MINIMAL_MESSAGE,
 	idempotencyKey: 'conformance/attachment-1',
@@ -134,6 +138,7 @@ const INVALID_MESSAGES: readonly { readonly problem: string; readonly message: E
 	{ problem: 'a sender name over 128 characters', message: { ...MINIMAL_MESSAGE, fromName: 'x'.repeat(129) } },
 	{ problem: 'an unsubscribe URL over http', message: { ...MINIMAL_MESSAGE, unsubscribeUrl: 'http://app.example.test/u' } },
 	{ problem: 'an unsubscribe URL with a bracket', message: { ...MINIMAL_MESSAGE, unsubscribeUrl: 'https://app.example.test/u>x' } },
+	{ problem: 'a broadcast without an unsubscribe URL', message: { ...MINIMAL_MESSAGE, broadcast: true } },
 	{
 		problem: 'an attachment name with a path',
 		message: { ...MINIMAL_MESSAGE, attachments: [{ filename: '../etc/passwd', contentType: 'text/plain', content: ONE_BYTE }] },
@@ -231,6 +236,19 @@ function describeHttpSender(harness: EmailSenderHttpHarness): void {
 		expect(current.requests).toHaveLength(0)
 	})
 
+	test('hands a broadcast message to the provider as one when it says it sends them, and refuses it otherwise', async () => {
+		const current = httpCase(async (request) => harness.answers.accepted(request))
+		if (current.sender.capabilities.broadcast === true) {
+			await current.sender.send(BROADCAST_MESSAGE, new AbortController().signal)
+			const wire = await harness.readRequest(only(current.requests))
+			expect(wire).toMatchObject({ ...contentOf(BROADCAST_MESSAGE), unsubscribeUrl: BROADCAST_MESSAGE.unsubscribeUrl })
+			expect(wire.broadcast).toBe(true)
+			return
+		}
+		await expectRejection(() => current.sender.send(BROADCAST_MESSAGE, new AbortController().signal), 'invalid_message', () => MESSAGE_MARKERS)
+		expect(current.requests).toHaveLength(0)
+	})
+
 	test('hands the attachments it says it sends to the provider, and refuses them otherwise', async () => {
 		const current = httpCase(async (request) => harness.answers.accepted(request))
 		if (current.sender.capabilities.maxAttachmentBytes !== undefined) {
@@ -250,6 +268,31 @@ function describeHttpSender(harness: EmailSenderHttpHarness): void {
 		expect(current.requests).toHaveLength(0)
 	})
 
+	test('refuses an attachment of a file type it says it refuses, without a request', async () => {
+		const current = httpCase(async (request) => harness.answers.accepted(request))
+		const extension = current.sender.capabilities.refusedAttachmentExtensions?.[0]
+		if (extension === undefined || current.sender.capabilities.maxAttachmentBytes === undefined) return
+		const message: EmailMessage = {
+			...ATTACHMENT_MESSAGE,
+			attachments: [{ filename: `report.${extension.toUpperCase()}`, contentType: 'application/octet-stream', content: ONE_BYTE }],
+		}
+		await expectRejection(() => current.sender.send(message, new AbortController().signal), 'invalid_message', () => MESSAGE_MARKERS)
+		expect(current.requests).toHaveLength(0)
+	})
+
+	test('refuses a body shorter than it says it sends, counted in characters once trimmed, without a request', async () => {
+		const current = httpCase(async (request) => harness.answers.accepted(request))
+		const min = current.sender.capabilities.minBodyLength
+		if (min === undefined) return
+		const short = ` ${'😀'.repeat(min - 1)} `
+		for (const message of [{ ...MINIMAL_MESSAGE, text: short }, { ...MINIMAL_MESSAGE, html: short }]) {
+			await expectRejection(() => current.sender.send(message, new AbortController().signal), 'invalid_message', () => MESSAGE_MARKERS)
+		}
+		expect(current.requests).toHaveLength(0)
+		await current.sender.send({ ...MINIMAL_MESSAGE, text: '😀'.repeat(min) }, new AbortController().signal)
+		expect(current.requests).toHaveLength(1)
+	})
+
 	test.each(INVALID_MESSAGES)('refuses $problem as invalid_message without a request', async ({ message }) => {
 		const current = httpCase(async (request) => harness.answers.accepted(request))
 		await expectRejection(() => current.sender.send(message, new AbortController().signal), 'invalid_message', forbidden(current))
@@ -382,6 +425,16 @@ function describeLocalSender(harness: EmailSenderLocalHarness): void {
 		expect(await harness.stored()).toHaveLength(0)
 	})
 
+	test('stores a broadcast message as one when it says it sends them, and refuses it otherwise', async () => {
+		if (current().capabilities.broadcast === true) {
+			await current().send(BROADCAST_MESSAGE, new AbortController().signal)
+			expect(only(await harness.stored()).broadcast).toBe(true)
+			return
+		}
+		await expectRejection(() => current().send(BROADCAST_MESSAGE, new AbortController().signal), 'invalid_message', () => MESSAGE_MARKERS)
+		expect(await harness.stored()).toHaveLength(0)
+	})
+
 	test('stores the attachments it says it sends, and refuses them otherwise', async () => {
 		const limit = current().capabilities.maxAttachmentBytes
 		if (limit !== undefined) {
@@ -448,6 +501,7 @@ function expectOptionalFieldsAbsent(wire: WireMessage): void {
 	expect(wire.fromName).toBeUndefined()
 	expect(wire.unsubscribeUrl).toBeUndefined()
 	expect(wire.attachments).toBeUndefined()
+	expect(wire.broadcast ?? false).toBe(false)
 }
 
 function contentOf(message: EmailMessage): WireMessage {

package/src/content.ts

@@ -16,13 +16,14 @@ export interface EmailContent {
 	readonly replyTo?: string
 	readonly fromName?: string
 	readonly unsubscribeUrl?: string
+	readonly broadcast?: true
 	readonly attachments?: readonly EmailAttachmentContent[]
 }
 
 export function sameEmailContent(left: EmailContent, right: EmailContent): boolean {
 	return left.to === right.to && left.subject === right.subject && left.text === right.text && left.html === right.html
 		&& left.replyTo === right.replyTo && left.fromName === right.fromName && left.unsubscribeUrl === right.unsubscribeUrl
-		&& sameAttachments(left.attachments ?? [], right.attachments ?? [])
+		&& left.broadcast === right.broadcast && sameAttachments(left.attachments ?? [], right.attachments ?? [])
 }
 
 export function emailContentOf(message: EmailMessage): EmailContent {
@@ -35,6 +36,7 @@ export function emailContentOf(message: EmailMessage): EmailContent {
 		...(message.replyTo === undefined ? {} : { replyTo: message.replyTo }),
 		...(message.fromName === undefined ? {} : { fromName: message.fromName }),
 		...(message.unsubscribeUrl === undefined ? {} : { unsubscribeUrl: message.unsubscribeUrl }),
+		...(message.broadcast === true ? { broadcast: true } : {}),
 		...(attachments.length === 0
 			? {}
 			: {

package/src/directory.ts

@@ -9,7 +9,7 @@ import { z } from 'zod'
 import { type EmailProvider, parseProviderVariables } from './config.js'
 import { emailContentOf, sameEmailContent } from './content.js'
 import { EmailDeliveryError, type EmailDeliveryResult, type EmailMessage, type EmailSender, type EmailSenderCapabilities } from './email.js'
-import { validateEmailAttachments, validateEmailMessage } from './validation.js'
+import { validateEmailAttachments, validateEmailBroadcast, validateEmailMessage } from './validation.js'
 
 /** Resend's bound, so a local composition meets the limit a production transport has. */
 const DIRECTORY_MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024
@@ -24,6 +24,7 @@ const capturedEmailSchema = z.object({
 	replyTo: z.string().optional(),
 	fromName: z.string().optional(),
 	unsubscribeUrl: z.string().optional(),
+	broadcast: z.literal(true).optional(),
 	attachments: z.array(z.object({ filename: z.string(), contentType: z.string(), content: z.string() })).readonly().optional(),
 	capturedAt: z.number().int(),
 })
@@ -43,6 +44,7 @@ export class DirectoryEmailSender implements EmailSender {
 		maxBatch: 1,
 		listUnsubscribe: true,
 		maxAttachmentBytes: DIRECTORY_MAX_ATTACHMENT_BYTES,
+		broadcast: true,
 	}
 	readonly #directory: string
 	readonly #now: () => number
@@ -59,6 +61,7 @@ export class DirectoryEmailSender implements EmailSender {
 	async send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult> {
 		validateEmailMessage(message)
 		validateEmailAttachments(message, this.capabilities, 'The mail capture')
+		validateEmailBroadcast(message, this.capabilities, 'The mail capture')
 		if (signal.aborted) throw new EmailDeliveryError('The mail capture was aborted by the caller', { code: 'aborted' })
 		const messageId = createHash('sha256').update(message.idempotencyKey).digest('hex')
 		const captured: CapturedEmail = { messageId, idempotencyKey: message.idempotencyKey, ...emailContentOf(message), capturedAt: this.#now() }

package/src/email.ts

@@ -23,6 +23,12 @@ export interface EmailMessage {
 	 * <url>` and `List-Unsubscribe-Post: List-Unsubscribe=One-Click`. A transport without `listUnsubscribe` refuses it.
 	 */
 	readonly unsubscribeUrl?: string
+	/**
+	 * One message of a send to many recipients (a newsletter, an announcement), not a reply to what the recipient did.
+	 * A provider keeps such mail apart from transactional mail, and the law and the mailbox providers ask it to carry
+	 * an unsubscribe, so it needs `unsubscribeUrl`. A transport without `broadcast` refuses it.
+	 */
+	readonly broadcast?: boolean
 	/**
 	 * Files the message carries, at most `MAX_EMAIL_ATTACHMENTS`, together at most the transport's `maxAttachmentBytes`.
 	 * A transport without `maxAttachmentBytes` refuses a message that has any; an empty list is none.
@@ -47,6 +53,12 @@ export interface EmailSenderCapabilities {
 	readonly listUnsubscribe?: boolean
 	/** The most attachment bytes one message carries, every file together; absent: it sends no attachments. */
 	readonly maxAttachmentBytes?: number
+	/** File extensions it refuses an attachment for, lowercase and without the dot; absent: none. */
+	readonly refusedAttachmentExtensions?: readonly string[]
+	/** The fewest characters a text or HTML body has once trimmed; absent: any body that is not blank. */
+	readonly minBodyLength?: number
+	/** Whether it sends a `broadcast` message, on its provider's channel for them where it has one; absent is no. */
+	readonly broadcast?: boolean
 }
 
 export interface EmailSender {