@fabrika/email 0.8.1 → 0.9.0-cloudflare.1

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 to `message`; undefined when the answer is not a valid success. May throw a refusal. */
+	protected abstract messageId(response: ProviderResponse, message: EmailMessage): 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, message)
+		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'

package/src/lettermint.ts

@@ -0,0 +1,153 @@
+// Lettermint's Sending API (https://lettermint.co/docs/api-reference/sending), built from its OpenAPI document and
+// verified on a live project in October 2026. It keeps an idempotency key for 24 hours, and a 202 means it took the
+// message.
+
+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,
+	formatMailbox,
+	type HttpEmailRequest,
+	HttpEmailSender,
+	type HttpEmailSenderOptions,
+	isChannelName,
+	isCredential,
+	optionalVariable,
+	providerIdempotencyKey,
+} from './http-sender.js'
+import type { ProviderResponse } from './http.js'
+
+const LETTERMINT_SEND_URL = 'https://api.lettermint.co/v1/send'
+/** The slug Lettermint gives a new project's broadcast route. */
+const DEFAULT_BROADCAST_ROUTE = 'broadcast'
+const MAX_IDEMPOTENCY_KEY_LENGTH = 255
+/** `pending` and `scheduled` are documented; the id is what counts, so a new status is no failure. */
+const lettermintSuccessSchema = z.object({ message_id: z.string() })
+/** Lettermint refuses a text or HTML body shorter than this with a 422, counting characters once trimmed. */
+const LETTERMINT_MIN_BODY_LENGTH = 3
+/** A 409 carries only a `message`; the one for a key reused with another body says so in these words. */
+const lettermintErrorSchema = z.object({ message: z.string() })
+const OTHER_PAYLOAD = /payload/i
+/** A structured refusal, whose message names a route the project lacks; read only to say so, never put into the error. */
+const lettermintApiErrorSchema = z.object({ error: z.object({ message: z.string() }) })
+const UNKNOWN_ROUTE = /route/i
+/** Lettermint refuses a request over 25 MB with its attachments base64; 15 MiB of bytes leaves room for the bodies. */
+const LETTERMINT_MAX_ATTACHMENT_BYTES = 15 * 1024 * 1024
+
+export interface LettermintEmailSenderOptions extends HttpEmailSenderOptions {
+	/** A project API token: it sends through that project's default route. */
+	readonly projectToken: string
+	/** The slug of the project's broadcast route, which a `broadcast` message goes through; `broadcast` by default. */
+	readonly broadcastRoute?: string
+}
+
+export class LettermintEmailSender extends HttpEmailSender {
+	readonly capabilities: EmailSenderCapabilities = {
+		idempotent: true,
+		confirmation: 'sync',
+		maxBatch: 1,
+		listUnsubscribe: true,
+		maxAttachmentBytes: LETTERMINT_MAX_ATTACHMENT_BYTES,
+		minBodyLength: LETTERMINT_MIN_BODY_LENGTH,
+		broadcast: true,
+	}
+	readonly #projectToken: string
+	readonly #broadcastRoute: string
+
+	constructor(options: LettermintEmailSenderOptions) {
+		if (!isCredential(options.projectToken)) {
+			throw new EmailDeliveryError('Lettermint project token is invalid', { code: 'invalid_configuration' })
+		}
+		const broadcastRoute = options.broadcastRoute ?? DEFAULT_BROADCAST_ROUTE
+		if (!isChannelName(broadcastRoute)) {
+			throw new EmailDeliveryError('Lettermint broadcast route is invalid', { code: 'invalid_configuration' })
+		}
+		super({ label: 'Lettermint', provider: 'lettermint' }, options)
+		this.#projectToken = options.projectToken
+		this.#broadcastRoute = broadcastRoute
+	}
+
+	protected async request(message: EmailMessage): Promise<HttpEmailRequest> {
+		const attachments = message.attachments ?? []
+		return {
+			url: LETTERMINT_SEND_URL,
+			headers: {
+				'x-lettermint-token': this.#projectToken,
+				'Idempotency-Key': await providerIdempotencyKey(message.idempotencyKey, MAX_IDEMPOTENCY_KEY_LENGTH),
+			},
+			body: {
+				from: formatMailbox(this.from.address, message.fromName ?? this.from.name),
+				to: [message.to],
+				// Lettermint keeps broadcast mail on infrastructure apart from the transactional route.
+				...(message.broadcast === true ? { route: this.#broadcastRoute } : {}),
+				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) => ({
+							filename: attachment.filename,
+							content: base64Of(attachment.content),
+							content_type: attachment.contentType,
+						})),
+					}),
+			},
+		}
+	}
+
+	protected messageId(response: ProviderResponse): string | undefined {
+		return lettermintSuccessSchema.safeParse(response.body).data?.message_id
+	}
+
+	protected override refusal(response: ProviderResponse, message: EmailMessage): EmailDeliveryError | undefined {
+		const status = response.status
+		// Only a broadcast message names a route; a transactional one takes the project's default, so its 422 is another.
+		if (
+			status === 422 && message.broadcast === true && UNKNOWN_ROUTE.test(lettermintApiErrorSchema.safeParse(response.body).data?.error.message ?? '')
+		) {
+			return new EmailDeliveryError(
+				'Lettermint knows no such route in the project: create its broadcast route, or name it in FABRIKA_EMAIL_LETTERMINT_BROADCAST_ROUTE (422)',
+				{ code: 'provider_rejected', httpStatus: status },
+			)
+		}
+		if (status !== 409) return undefined
+		// The 409 has no code, so its text is read, and only to tell the two apart; it never reaches the error. A wording
+		// that no longer names the payload reads as in progress, which a retry cannot turn into a second delivery.
+		const text = lettermintErrorSchema.safeParse(response.body).data?.message
+		if (text !== undefined && OTHER_PAYLOAD.test(text)) {
+			return new EmailDeliveryError('Lettermint already took a different request under this idempotency key', {
+				code: 'idempotency_conflict',
+				httpStatus: status,
+			})
+		}
+		// Every other 409 is a request under the key still in progress, or one whose outcome is unknown, which Lettermint
+		// answers the same way until the key expires. A retry cannot deliver twice, so it is retried.
+		return new EmailDeliveryError('A matching Lettermint request is still in progress', { code: 'request_in_progress', httpStatus: status })
+	}
+}
+
+const lettermintVariablesSchema = z.object({
+	FABRIKA_EMAIL_LETTERMINT_PROJECT_TOKEN: credentialVariable,
+	FABRIKA_EMAIL_LETTERMINT_BROADCAST_ROUTE: optionalVariable(isChannelName),
+})
+
+export const lettermintEmailProvider: EmailProvider = {
+	variables: [
+		{ name: 'FABRIKA_EMAIL_LETTERMINT_PROJECT_TOKEN', secret: true, required: true },
+		{ name: 'FABRIKA_EMAIL_LETTERMINT_BROADCAST_ROUTE', secret: false, required: false },
+	],
+	create({ from, env, fetch }) {
+		const variables = parseProviderVariables(lettermintVariablesSchema, env)
+		return new LettermintEmailSender({
+			projectToken: variables.FABRIKA_EMAIL_LETTERMINT_PROJECT_TOKEN,
+			broadcastRoute: variables.FABRIKA_EMAIL_LETTERMINT_BROADCAST_ROUTE,
+			from,
+			fetch,
+		})
+	},
+}

package/src/memory.ts

@@ -11,7 +11,7 @@ import {
 	type EmailSender,
 	type EmailSenderCapabilities,
 } from './email.js'
-import { validateEmailAttachments, validateEmailMessage } from './validation.js'
+import { validateEmailAttachments, validateEmailBroadcast, validateEmailMessage } from './validation.js'
 
 export interface MemoryEmail {
 	readonly message: EmailMessage
@@ -82,6 +82,7 @@ export class MemoryEmailSender implements EmailSender {
 			maxBatch: 1,
 			listUnsubscribe: true,
 			maxAttachmentBytes: MEMORY_MAX_ATTACHMENT_BYTES,
+			broadcast: true,
 			...options.capabilities,
 		}
 		if (!Number.isSafeInteger(this.capabilities.maxBatch) || this.capabilities.maxBatch < 1) {
@@ -138,6 +139,7 @@ export class MemoryEmailSender implements EmailSender {
 			throw new EmailDeliveryError('The memory sender writes no List-Unsubscribe header', { code: 'invalid_message' })
 		}
 		validateEmailAttachments(message, this.capabilities, 'The memory sender')
+		validateEmailBroadcast(message, this.capabilities, 'The memory sender')
 		if (signal.aborted) throw failure('aborted')
 		const handoff: MutableHandoff = { message, at: this.#now(), taken: false, answer: 'network_error' }
 		this.#handoffs.push(handoff)

package/src/platform-wire.ts

@@ -17,6 +17,8 @@ export const PLATFORM_MAIL_CAPABILITIES: EmailSenderCapabilities = {
 	maxBatch: 1,
 	listUnsubscribe: true,
 	maxAttachmentBytes: 10 * 1024 * 1024,
+	// Control refuses one at once when its own transport sends none, and dispatches it on the provider's channel.
+	broadcast: true,
 }
 
 const LABEL = 'Platform mail'
@@ -38,6 +40,8 @@ interface PlatformMailRequest {
 	readonly replyTo?: string
 	readonly fromName?: string
 	readonly unsubscribeUrl?: string
+	/** Present only when true, so a transactional message encodes, and fingerprints, as it did before the field. */
+	readonly broadcast?: true
 	readonly attachments?: readonly PlatformMailAttachment[]
 }
 
@@ -52,6 +56,7 @@ function platformMailRequestOf(message: EmailMessage): PlatformMailRequest {
 		...(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
 			? {}
 			: {
@@ -118,6 +123,7 @@ const requestSchema = z.object({
 	replyTo: z.string().optional(),
 	fromName: z.string().optional(),
 	unsubscribeUrl: z.string().optional(),
+	broadcast: z.literal(true).optional(),
 	attachments: z.array(attachmentSchema).optional(),
 }).strict()
 

package/src/platform.ts

@@ -8,7 +8,7 @@ import {
 } from './email.js'
 import { parseTimeout, postToProvider } from './http.js'
 import { encodePlatformMailRequest, parsePlatformMailAnswer, PLATFORM_MAIL_CAPABILITIES, PLATFORM_MAIL_SEND_PATH } from './platform-wire.js'
-import { isVisibleAscii, validateEmailAttachments, validateEmailMessage } from './validation.js'
+import { isVisibleAscii, validateEmailAttachments, validateEmailBroadcast, validateEmailMessage } from './validation.js'
 
 export {
 	encodePlatformMailRequest,
@@ -68,6 +68,7 @@ export class PlatformEmailSender implements EmailSender {
 	async send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult> {
 		validateEmailMessage(message)
 		validateEmailAttachments(message, this.capabilities, LABEL)
+		validateEmailBroadcast(message, this.capabilities, LABEL)
 
 		// postToProvider serializes the body itself; the canonical text survives the round trip unchanged.
 		const body: unknown = JSON.parse(encodePlatformMailRequest(message))

package/src/postmark.ts

@@ -0,0 +1,136 @@
+// Postmark's Email API (https://postmarkapp.com/developer/api/email-api), built from its documentation and verified on a
+// live server in October 2026. It has no idempotency key; a 200 means Postmark took the message.
+
+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,
+	formatMailbox,
+	type HttpEmailRequest,
+	HttpEmailSender,
+	type HttpEmailSenderOptions,
+	isChannelName,
+	isCredential,
+	optionalVariable,
+} from './http-sender.js'
+import type { ProviderResponse } from './http.js'
+
+const POSTMARK_EMAIL_URL = 'https://api.postmarkapp.com/email'
+/** The ID Postmark suggests for a server's broadcast stream. */
+const DEFAULT_BROADCAST_STREAM = 'broadcast'
+const postmarkSuccessSchema = z.object({ MessageID: z.string(), ErrorCode: z.literal(0) })
+/** A refusal's `ErrorCode` is a documented number; its `Message` is free text and is never read. */
+const postmarkErrorSchema = z.object({ ErrorCode: z.number() })
+/** Out of credits: sending resumes once the account has them again. */
+const OUT_OF_CREDITS = 405
+/** The sender signature is missing (400) or unconfirmed (401), or the account is pending approval (412, 413). */
+const SENDER_NOT_ALLOWED: ReadonlySet<number> = new Set([400, 401, 412, 413])
+/** Postmark counts the decoded bytes of every attachment together and takes fewer than 10 MiB; the bodies are apart. */
+const POSTMARK_MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024 - 1
+/** The extensions Postmark refuses an attachment for (ErrorCode 411), from its documentation. */
+const FORBIDDEN_EXTENSIONS: readonly string[] =
+	'vbs exe bin bat chm com cpl crt hlp hta inf ins isp jse lnk mdb pcd pif reg scr sct shs vbe vba wsf wsh wsl msc msi msp mst'.split(' ')
+
+export interface PostmarkEmailSenderOptions extends HttpEmailSenderOptions {
+	/** A server token: it sends through that server's default transactional stream. */
+	readonly serverToken: string
+	/** The ID of the server's broadcast stream, which a `broadcast` message goes through; `broadcast` by default. */
+	readonly broadcastStream?: string
+}
+
+export class PostmarkEmailSender extends HttpEmailSender {
+	readonly capabilities: EmailSenderCapabilities = {
+		idempotent: false,
+		confirmation: 'sync',
+		maxBatch: 1,
+		listUnsubscribe: true,
+		maxAttachmentBytes: POSTMARK_MAX_ATTACHMENT_BYTES,
+		refusedAttachmentExtensions: FORBIDDEN_EXTENSIONS,
+		broadcast: true,
+	}
+	readonly #serverToken: string
+	readonly #broadcastStream: string
+
+	constructor(options: PostmarkEmailSenderOptions) {
+		if (!isCredential(options.serverToken)) {
+			throw new EmailDeliveryError('Postmark server token is invalid', { code: 'invalid_configuration' })
+		}
+		const broadcastStream = options.broadcastStream ?? DEFAULT_BROADCAST_STREAM
+		if (!isChannelName(broadcastStream)) {
+			throw new EmailDeliveryError('Postmark broadcast stream is invalid', { code: 'invalid_configuration' })
+		}
+		super({ label: 'Postmark', provider: 'postmark' }, options)
+		this.#serverToken = options.serverToken
+		this.#broadcastStream = broadcastStream
+	}
+
+	protected request(message: EmailMessage): HttpEmailRequest {
+		const attachments = message.attachments ?? []
+		return {
+			url: POSTMARK_EMAIL_URL,
+			headers: { 'X-Postmark-Server-Token': this.#serverToken, Accept: 'application/json' },
+			body: {
+				From: formatMailbox(this.from.address, message.fromName ?? this.from.name),
+				To: message.to,
+				Subject: message.subject,
+				TextBody: message.text,
+				// Postmark pauses a server whose transactional stream carries promotional mail.
+				...(message.broadcast === true ? { MessageStream: this.#broadcastStream } : {}),
+				...(message.html === undefined ? {} : { HtmlBody: message.html }),
+				...(message.replyTo === undefined ? {} : { ReplyTo: message.replyTo }),
+				...(message.unsubscribeUrl === undefined
+					? {}
+					: { Headers: Object.entries(oneClickUnsubscribeHeaders(message.unsubscribeUrl)).map(([Name, Value]) => ({ Name, Value })) }),
+				...(attachments.length === 0
+					? {}
+					: {
+						Attachments: attachments.map((attachment) => ({
+							Name: attachment.filename,
+							Content: base64Of(attachment.content),
+							ContentType: attachment.contentType,
+						})),
+					}),
+			},
+		}
+	}
+
+	protected messageId(response: ProviderResponse): string | undefined {
+		return postmarkSuccessSchema.safeParse(response.body).data?.MessageID
+	}
+
+	protected override refusal(response: ProviderResponse): EmailDeliveryError | undefined {
+		const status = response.status
+		const code = postmarkErrorSchema.safeParse(response.body).data?.ErrorCode
+		if (status !== 422 || code === undefined) return undefined
+		if (code === OUT_OF_CREDITS) {
+			return new EmailDeliveryError('Postmark account is out of credits', { code: 'quota_exceeded', httpStatus: status })
+		}
+		if (SENDER_NOT_ALLOWED.has(code)) {
+			return new EmailDeliveryError(`Postmark refused the sender or the account (${code})`, { code: 'provider_unauthorized', httpStatus: status })
+		}
+		return undefined
+	}
+}
+
+const postmarkVariablesSchema = z.object({
+	FABRIKA_EMAIL_POSTMARK_SERVER_TOKEN: credentialVariable,
+	FABRIKA_EMAIL_POSTMARK_BROADCAST_STREAM: optionalVariable(isChannelName),
+})
+
+export const postmarkEmailProvider: EmailProvider = {
+	variables: [
+		{ name: 'FABRIKA_EMAIL_POSTMARK_SERVER_TOKEN', secret: true, required: true },
+		{ name: 'FABRIKA_EMAIL_POSTMARK_BROADCAST_STREAM', secret: false, required: false },
+	],
+	create({ from, env, fetch }) {
+		const variables = parseProviderVariables(postmarkVariablesSchema, env)
+		return new PostmarkEmailSender({
+			serverToken: variables.FABRIKA_EMAIL_POSTMARK_SERVER_TOKEN,
+			broadcastStream: variables.FABRIKA_EMAIL_POSTMARK_BROADCAST_STREAM,
+			from,
+			fetch,
+		})
+	},
+}

package/src/providers.ts

@@ -1,9 +1,40 @@
-import type { EmailProviderRegistry } from './config.js'
+import { ahaSendEmailProvider } from './ahasend.js'
+import { cloudflareEmailProvider } from './cloudflare.js'
+import type { EmailProviderRegistry, EmailProviderVariable } from './config.js'
+import { lettermintEmailProvider } from './lettermint.js'
+import { postmarkEmailProvider } from './postmark.js'
 import { resendEmailProvider } from './resend.js'
 import { smartEmailingEmailProvider } from './smartemailing.js'
 
-/** The providers `FABRIKA_EMAIL_PROVIDER` can name in a stock installation. Memory and Directory are composition inputs. */
+/**
+ * The providers `FABRIKA_EMAIL_PROVIDER` can name in a stock installation, sorted by name: the order every help text
+ * and refusal lists them in. Memory and Directory are composition inputs.
+ */
 export const builtinEmailProviders = {
+	ahasend: ahaSendEmailProvider,
+	cloudflare: cloudflareEmailProvider,
+	lettermint: lettermintEmailProvider,
+	postmark: postmarkEmailProvider,
 	resend: resendEmailProvider,
 	smartemailing: smartEmailingEmailProvider,
 } satisfies EmailProviderRegistry
+
+/** Every built-in provider's own variables, in registry order: what the installers write and the workflow passes on. */
+export const builtinEmailProviderVariables: readonly EmailProviderVariable[] = Object.values(builtinEmailProviders).flatMap((provider) =>
+	provider.variables
+)
+
+/**
+ * The first framework release whose registry holds each built-in provider. An application on an older release builds
+ * its sender from its own registry, so it cannot be handed one it lacks; Control refuses that deploy. `null`: every
+ * release that sends through the installation (`mailer: 'installation'`, from 0.5.0) holds it. A new provider names
+ * the release after the newest one published without it.
+ */
+export const builtinEmailProviderSince = {
+	ahasend: '0.8.2',
+	cloudflare: '0.9.0',
+	lettermint: '0.8.2',
+	postmark: '0.8.2',
+	resend: null,
+	smartemailing: null,
+} as const satisfies Record<keyof typeof builtinEmailProviders, string | null>