@fabrika/email 0.8.1 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/email",
-	"version": "0.8.1",
+	"version": "0.8.2",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -25,6 +25,21 @@
 			"types": "./src/resend.ts",
 			"default": "./src/resend.ts"
 		},
+		"./postmark": {
+			"bun": "./src/postmark.ts",
+			"types": "./src/postmark.ts",
+			"default": "./src/postmark.ts"
+		},
+		"./ahasend": {
+			"bun": "./src/ahasend.ts",
+			"types": "./src/ahasend.ts",
+			"default": "./src/ahasend.ts"
+		},
+		"./lettermint": {
+			"bun": "./src/lettermint.ts",
+			"types": "./src/lettermint.ts",
+			"default": "./src/lettermint.ts"
+		},
 		"./directory": {
 			"bun": "./src/directory.ts",
 			"types": "./src/directory.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/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 {

package/src/http-sender.ts

@@ -0,0 +1,138 @@
+// What every HTTP provider adapter shares, so an adapter holds only its provider's mapping: the request it sends for a
+// message, the message id of an accepted answer, and the answers it tells apart beyond the HTTP status. The base
+// validates the message against the adapter's capabilities before any I/O and classifies the rest.
+
+import { z } from 'zod'
+import type { EmailSenderIdentity } from './config.js'
+import {
+	EmailDeliveryError,
+	type EmailDeliveryResult,
+	type EmailFetch,
+	type EmailMessage,
+	type EmailSender,
+	type EmailSenderCapabilities,
+} from './email.js'
+import { parseTimeout, postToProvider, type ProviderResponse } from './http.js'
+import {
+	isValidEmailSenderIdentity,
+	isVisibleAscii,
+	validateEmailAttachments,
+	validateEmailBodies,
+	validateEmailBroadcast,
+	validateEmailMessage,
+} from './validation.js'
+
+/** The options every HTTP adapter takes beside its credentials. */
+export interface HttpEmailSenderOptions {
+	readonly from: EmailSenderIdentity
+	readonly fetch?: EmailFetch
+	readonly timeoutMs?: number
+}
+
+export interface HttpEmailRequest {
+	readonly url: string
+	readonly headers: Readonly<Record<string, string>>
+	readonly body: unknown
+}
+
+export abstract class HttpEmailSender implements EmailSender {
+	abstract readonly capabilities: EmailSenderCapabilities
+	protected readonly from: EmailSenderIdentity
+	readonly #label: string
+	readonly #provider: string
+	readonly #fetch: EmailFetch
+	readonly #timeoutMs: number
+
+	/** `label` names the provider in every message, `provider` in every result. An adapter checks its credentials first. */
+	protected constructor(names: { readonly label: string; readonly provider: string }, options: HttpEmailSenderOptions) {
+		if (!isValidEmailSenderIdentity(options.from)) {
+			throw new EmailDeliveryError(`${names.label} sender is invalid`, { code: 'invalid_configuration' })
+		}
+		this.from = options.from
+		this.#label = names.label
+		this.#provider = names.provider
+		this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init))
+		this.#timeoutMs = parseTimeout(names.label, options.timeoutMs)
+	}
+
+	/** The request for a message that passed validation. */
+	protected abstract request(message: EmailMessage): HttpEmailRequest | Promise<HttpEmailRequest>
+
+	/** The message id of a 2xx answer; undefined when the answer is not a valid success. May throw a refusal. */
+	protected abstract messageId(response: ProviderResponse): string | undefined
+
+	/** A failed answer to the message the provider tells apart beyond its status; undefined leaves it to `refusalByStatus`. */
+	protected refusal(_response: ProviderResponse, _message: EmailMessage): EmailDeliveryError | undefined {
+		return undefined
+	}
+
+	async send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult> {
+		validateEmailMessage(message)
+		if (message.unsubscribeUrl !== undefined && this.capabilities.listUnsubscribe !== true) {
+			throw new EmailDeliveryError(`${this.#label} cannot write the List-Unsubscribe headers`, { code: 'invalid_message' })
+		}
+		validateEmailAttachments(message, this.capabilities, this.#label)
+		validateEmailBodies(message, this.capabilities, this.#label)
+		validateEmailBroadcast(message, this.capabilities, this.#label)
+
+		const request = await this.request(message)
+		const response = await postToProvider({ label: this.#label, fetch: this.#fetch, ...request, signal, timeoutMs: this.#timeoutMs })
+		if (!response.ok) throw this.refusal(response, message) ?? refusalByStatus(this.#label, response.status)
+
+		const messageId = this.messageId(response)
+		if (messageId === undefined || messageId === '') {
+			throw new EmailDeliveryError(`${this.#label} returned an invalid success response`, {
+				code: 'malformed_response',
+				httpStatus: response.status,
+			})
+		}
+		return { status: 'accepted', provider: this.#provider, messageId }
+	}
+}
+
+/** The classification of a failed answer by its status alone, for every answer an adapter does not tell apart. */
+export function refusalByStatus(label: string, status: number): EmailDeliveryError {
+	if (status === 401 || status === 403) {
+		return new EmailDeliveryError(`${label} refused the credentials (${status})`, { code: 'provider_unauthorized', httpStatus: status })
+	}
+	if (status === 429) return new EmailDeliveryError(`${label} rate limit exceeded`, { code: 'rate_limited', httpStatus: status })
+	if (status >= 500) return new EmailDeliveryError(`${label} is unavailable`, { code: 'provider_unavailable', httpStatus: status })
+	return new EmailDeliveryError(`${label} rejected the request (${status})`, { code: 'provider_rejected', httpStatus: status })
+}
+
+/** RFC 5322 specials a display name may still hold after validation; any of them makes the name a quoted string. */
+const DISPLAY_NAME_SPECIALS = /[()[\]:;@,.]/
+
+/** `Name <address>` for an API that takes the sender as one header value; validation keeps the name quotable. */
+export function formatMailbox(address: string, name: string | undefined): string {
+	if (name === undefined) return address
+	return DISPLAY_NAME_SPECIALS.test(name) ? `"${name}" <${address}>` : `${name} <${address}>`
+}
+
+/** An API key or token: non-empty visible ASCII, so it fits a header unchanged. */
+export function isCredential(value: string): boolean {
+	return value.length > 0 && isVisibleAscii(value)
+}
+
+/** The name of a provider's stream or route: 1..64 letters, digits, `_` and `-`. */
+export function isChannelName(value: string): boolean {
+	return /^[A-Za-z0-9_-]{1,64}$/.test(value)
+}
+
+/** A provider variable that holds a credential. */
+export const credentialVariable = z.string().refine(isCredential)
+
+/** An optional provider variable: empty is absent, and a present value must pass `valid`. */
+export function optionalVariable(valid: (value: string) => boolean) {
+	return z.string().optional().transform((value) => (value === '' ? undefined : value)).refine((value) => value === undefined || valid(value))
+}
+
+/**
+ * The message's key as a provider that takes at most `maxLength` characters sends it. A longer key is sent as its
+ * SHA-256, which keeps one key one key: a retry sends the same digest, another message another.
+ */
+export async function providerIdempotencyKey(key: string, maxLength: number): Promise<string> {
+	if (key.length <= maxLength) return key
+	const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(key)))
+	return `sha256:${Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('')}`
+}

package/src/index.ts

@@ -36,5 +36,7 @@ export {
 	MAX_EMAIL_SUBJECT_LENGTH,
 	MAX_UNSUBSCRIBE_URL_LENGTH,
 	validateEmailAttachments,
+	validateEmailBodies,
+	validateEmailBroadcast,
 	validateEmailMessage,
 } from './validation.js'