@fabrika/email 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/email",
-	"version": "0.6.0",
+	"version": "0.8.0",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -45,6 +45,11 @@
 			"types": "./src/providers.ts",
 			"default": "./src/providers.ts"
 		},
+		"./platform": {
+			"bun": "./src/platform.ts",
+			"types": "./src/platform.ts",
+			"default": "./src/platform.ts"
+		},
 		"./conformance": {
 			"bun": "./src/conformance.ts",
 			"types": "./src/conformance.ts",

package/src/conformance.ts

@@ -3,6 +3,7 @@
 // request and how its provider answers; a local sender says where it stores what it took.
 
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { type EmailAttachmentContent, emailContentOf } from './content.js'
 import {
 	EMAIL_DELIVERY_ERRORS,
 	EmailDeliveryError,
@@ -21,6 +22,15 @@ export interface WireMessage {
 	readonly replyTo?: string
 	readonly fromName?: string
 	readonly idempotencyKey?: string
+	/** The URL of the `List-Unsubscribe` header, when `List-Unsubscribe-Post` says one click. */
+	readonly unsubscribeUrl?: string
+	/** Each attachment with its bytes as base64. */
+	readonly attachments?: readonly EmailAttachmentContent[]
+}
+
+/** A stored or sent message in wire terms: what a local harness answers for an `EmailMessage` it kept. */
+export function wireMessageOf(message: EmailMessage): WireMessage {
+	return { ...emailContentOf(message), idempotencyKey: message.idempotencyKey }
 }
 
 /** How the provider answers. `inProgress` and `idempotencyConflict` are required when the sender is idempotent. */
@@ -83,6 +93,34 @@ const MINIMAL_MESSAGE: EmailMessage = {
 	idempotencyKey: 'conformance/minimal-1',
 }
 
+const UNSUBSCRIBE_MESSAGE: EmailMessage = {
+	...MINIMAL_MESSAGE,
+	idempotencyKey: 'conformance/unsubscribe-1',
+	unsubscribeUrl: 'https://app.example.test/api/mail.unsubscribe?t=conformance-token-6c2e',
+}
+
+const ATTACHMENT_MESSAGE: EmailMessage = {
+	...MINIMAL_MESSAGE,
+	idempotencyKey: 'conformance/attachment-1',
+	attachments: [{ filename: 'conformance report.txt', contentType: 'text/plain', content: new TextEncoder().encode('Conformance attachment 9d4e') }],
+}
+
+/** The same message under its key, with other bytes in its one attachment. */
+const OTHER_ATTACHMENT_MESSAGE: EmailMessage = {
+	...ATTACHMENT_MESSAGE,
+	attachments: [{ filename: 'conformance report.txt', contentType: 'text/plain', content: new TextEncoder().encode('Conformance attachment 0f1a') }],
+}
+
+function oversizedMessage(maxAttachmentBytes: number): EmailMessage {
+	return {
+		...MINIMAL_MESSAGE,
+		idempotencyKey: 'conformance/oversized-1',
+		attachments: [{ filename: 'large.bin', contentType: 'application/octet-stream', content: new Uint8Array(maxAttachmentBytes + 1) }],
+	}
+}
+
+const ONE_BYTE = new Uint8Array([0x61])
+
 const INVALID_MESSAGES: readonly { readonly problem: string; readonly message: EmailMessage }[] = [
 	{ problem: 'a bad recipient', message: { ...MINIMAL_MESSAGE, to: 'not-an-address' } },
 	{ problem: 'an empty subject', message: { ...MINIMAL_MESSAGE, subject: '' } },
@@ -94,6 +132,23 @@ const INVALID_MESSAGES: readonly { readonly problem: string; readonly message: E
 	{ problem: 'a bad reply-to', message: { ...MINIMAL_MESSAGE, replyTo: 'not-an-address' } },
 	{ problem: 'a sender name with brackets', message: { ...MINIMAL_MESSAGE, fromName: 'Bad <name>' } },
 	{ 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: 'an attachment name with a path',
+		message: { ...MINIMAL_MESSAGE, attachments: [{ filename: '../etc/passwd', contentType: 'text/plain', content: ONE_BYTE }] },
+	},
+	{
+		problem: 'an attachment type with a line break',
+		message: { ...MINIMAL_MESSAGE, attachments: [{ filename: 'a.txt', contentType: 'text/plain\r\nX-Bad: 1', content: ONE_BYTE }] },
+	},
+	{
+		problem: 'more than 20 attachments',
+		message: {
+			...MINIMAL_MESSAGE,
+			attachments: Array.from({ length: 21 }, () => ({ filename: 'a.txt', contentType: 'text/plain', content: ONE_BYTE })),
+		},
+	},
 ]
 
 /**
@@ -165,6 +220,36 @@ function describeHttpSender(harness: EmailSenderHttpHarness): void {
 		expectOptionalFieldsAbsent(await harness.readRequest(only(current.requests)))
 	})
 
+	test('writes the one-click unsubscribe headers it says it writes, and refuses them otherwise', async () => {
+		const current = httpCase(async (request) => harness.answers.accepted(request))
+		if (current.sender.capabilities.listUnsubscribe === true) {
+			await current.sender.send(UNSUBSCRIBE_MESSAGE, new AbortController().signal)
+			expect((await harness.readRequest(only(current.requests))).unsubscribeUrl).toBe(UNSUBSCRIBE_MESSAGE.unsubscribeUrl)
+			return
+		}
+		await expectRejection(() => current.sender.send(UNSUBSCRIBE_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) {
+			await current.sender.send(ATTACHMENT_MESSAGE, new AbortController().signal)
+			expect((await harness.readRequest(only(current.requests))).attachments).toEqual(wireMessageOf(ATTACHMENT_MESSAGE).attachments)
+			return
+		}
+		await expectRejection(() => current.sender.send(ATTACHMENT_MESSAGE, new AbortController().signal), 'invalid_message', () => MESSAGE_MARKERS)
+		expect(current.requests).toHaveLength(0)
+	})
+
+	test('refuses attachments over its limit without a request', async () => {
+		const current = httpCase(async (request) => harness.answers.accepted(request))
+		const limit = current.sender.capabilities.maxAttachmentBytes
+		if (limit === undefined) return
+		await expectRejection(() => current.sender.send(oversizedMessage(limit), new AbortController().signal), 'invalid_message', () => MESSAGE_MARKERS)
+		expect(current.requests).toHaveLength(0)
+	})
+
 	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))
@@ -287,6 +372,37 @@ function describeLocalSender(harness: EmailSenderLocalHarness): void {
 		expectOptionalFieldsAbsent(only(await harness.stored()))
 	})
 
+	test('stores the one-click unsubscribe URL it says it writes, and refuses it otherwise', async () => {
+		if (current().capabilities.listUnsubscribe === true) {
+			await current().send(UNSUBSCRIBE_MESSAGE, new AbortController().signal)
+			expect(only(await harness.stored()).unsubscribeUrl).toBe(UNSUBSCRIBE_MESSAGE.unsubscribeUrl)
+			return
+		}
+		await expectRejection(() => current().send(UNSUBSCRIBE_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) {
+			await current().send(ATTACHMENT_MESSAGE, new AbortController().signal)
+			expect(only(await harness.stored()).attachments).toEqual(wireMessageOf(ATTACHMENT_MESSAGE).attachments)
+			await expectRejection(() => current().send(oversizedMessage(limit), new AbortController().signal), 'invalid_message', () => MESSAGE_MARKERS)
+			expect(await harness.stored()).toHaveLength(1)
+			return
+		}
+		await expectRejection(() => current().send(ATTACHMENT_MESSAGE, new AbortController().signal), 'invalid_message', () => MESSAGE_MARKERS)
+		expect(await harness.stored()).toHaveLength(0)
+	})
+
+	test('an idempotent sender refuses other attachment bytes under the same key', async () => {
+		const target = current()
+		if (!target.capabilities.idempotent || target.capabilities.maxAttachmentBytes === undefined) return
+		await target.send(ATTACHMENT_MESSAGE, new AbortController().signal)
+		await expectRejection(() => target.send(OTHER_ATTACHMENT_MESSAGE, new AbortController().signal), 'idempotency_conflict', () => MESSAGE_MARKERS)
+		expect(await harness.stored()).toHaveLength(1)
+	})
+
 	test.each(INVALID_MESSAGES)('refuses $problem as invalid_message and stores nothing', async ({ message }) => {
 		await expectRejection(() => current().send(message, new AbortController().signal), 'invalid_message', () => MESSAGE_MARKERS)
 		expect(await harness.stored()).toHaveLength(0)
@@ -330,6 +446,8 @@ function expectOptionalFieldsAbsent(wire: WireMessage): void {
 	expect(wire.html).toBeUndefined()
 	expect(wire.replyTo).toBeUndefined()
 	expect(wire.fromName).toBeUndefined()
+	expect(wire.unsubscribeUrl).toBeUndefined()
+	expect(wire.attachments).toBeUndefined()
 }
 
 function contentOf(message: EmailMessage): WireMessage {
@@ -394,7 +512,8 @@ function safeString(value: unknown): string {
 function markersOf(body: string): string[] {
 	const markers: string[] = []
 	const collect = (value: unknown): void => {
-		if (typeof value === 'string' && value.length >= MIN_BODY_MARKER_LENGTH) markers.push(value)
+		// A delivery error code is the contract's own vocabulary, which a relay answers with, not provider content.
+		if (typeof value === 'string' && value.length >= MIN_BODY_MARKER_LENGTH && !Object.hasOwn(EMAIL_DELIVERY_ERRORS, value)) markers.push(value)
 		else if (Array.isArray(value)) value.forEach(collect)
 		else if (typeof value === 'object' && value !== null) Object.values(value).forEach(collect)
 	}

package/src/content.ts

@@ -1,5 +1,12 @@
 import type { EmailMessage } from './email.js'
 
+/** An attachment as a local sender keeps and compares it: the bytes as base64. */
+export interface EmailAttachmentContent {
+	readonly filename: string
+	readonly contentType: string
+	readonly content: string
+}
+
 /** What a local sender compares when one idempotency key arrives twice: everything the recipient would see. */
 export interface EmailContent {
 	readonly to: string
@@ -8,14 +15,18 @@ export interface EmailContent {
 	readonly html?: string
 	readonly replyTo?: string
 	readonly fromName?: string
+	readonly unsubscribeUrl?: string
+	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.replyTo === right.replyTo && left.fromName === right.fromName && left.unsubscribeUrl === right.unsubscribeUrl
+		&& sameAttachments(left.attachments ?? [], right.attachments ?? [])
 }
 
 export function emailContentOf(message: EmailMessage): EmailContent {
+	const attachments = message.attachments ?? []
 	return {
 		to: message.to,
 		subject: message.subject,
@@ -23,5 +34,35 @@ export function emailContentOf(message: EmailMessage): EmailContent {
 		...(message.html === undefined ? {} : { html: message.html }),
 		...(message.replyTo === undefined ? {} : { replyTo: message.replyTo }),
 		...(message.fromName === undefined ? {} : { fromName: message.fromName }),
+		...(message.unsubscribeUrl === undefined ? {} : { unsubscribeUrl: message.unsubscribeUrl }),
+		...(attachments.length === 0
+			? {}
+			: {
+				attachments: attachments.map((attachment) => ({
+					filename: attachment.filename,
+					contentType: attachment.contentType,
+					content: base64Of(attachment.content),
+				})),
+			}),
+	}
+}
+
+const BASE64_CHUNK = 0x8000
+
+/** `bytes` as standard base64, on every runtime: `btoa` over chunks, so a large file never overflows the call stack. */
+export function base64Of(bytes: Uint8Array): string {
+	let binary = ''
+	for (let offset = 0; offset < bytes.byteLength; offset += BASE64_CHUNK) {
+		binary += String.fromCharCode(...bytes.subarray(offset, offset + BASE64_CHUNK))
 	}
+	return btoa(binary)
+}
+
+function sameAttachments(left: readonly EmailAttachmentContent[], right: readonly EmailAttachmentContent[]): boolean {
+	return left.length === right.length
+		&& left.every((attachment, index) => {
+			const other = right[index]
+			return other !== undefined && attachment.filename === other.filename && attachment.contentType === other.contentType
+				&& attachment.content === other.content
+		})
 }

package/src/directory.ts

@@ -9,7 +9,10 @@ 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 { validateEmailMessage } from './validation.js'
+import { validateEmailAttachments, 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
 
 const capturedEmailSchema = z.object({
 	messageId: z.string().min(1),
@@ -20,6 +23,8 @@ const capturedEmailSchema = z.object({
 	html: z.string().optional(),
 	replyTo: z.string().optional(),
 	fromName: z.string().optional(),
+	unsubscribeUrl: z.string().optional(),
+	attachments: z.array(z.object({ filename: z.string(), contentType: z.string(), content: z.string() })).readonly().optional(),
 	capturedAt: z.number().int(),
 })
 
@@ -32,7 +37,13 @@ export interface DirectoryEmailSenderOptions {
 }
 
 export class DirectoryEmailSender implements EmailSender {
-	readonly capabilities: EmailSenderCapabilities = { idempotent: true, confirmation: 'sync', maxBatch: 1 }
+	readonly capabilities: EmailSenderCapabilities = {
+		idempotent: true,
+		confirmation: 'sync',
+		maxBatch: 1,
+		listUnsubscribe: true,
+		maxAttachmentBytes: DIRECTORY_MAX_ATTACHMENT_BYTES,
+	}
 	readonly #directory: string
 	readonly #now: () => number
 
@@ -47,6 +58,7 @@ export class DirectoryEmailSender implements EmailSender {
 	/** One file per idempotency key: a repeated send of the same message answers the first id, as a provider does. */
 	async send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult> {
 		validateEmailMessage(message)
+		validateEmailAttachments(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

@@ -1,5 +1,12 @@
 export type EmailFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
 
+/** One file a message carries: the name the recipient sees, its media type and its bytes. */
+export interface EmailAttachment {
+	readonly filename: string
+	readonly contentType: string
+	readonly content: Uint8Array
+}
+
 export interface EmailMessage {
 	readonly to: string
 	readonly subject: string
@@ -11,6 +18,16 @@ export interface EmailMessage {
 	readonly replyTo?: string
 	/** Replaces the transport's display name for this message. */
 	readonly fromName?: string
+	/**
+	 * An `https:` URL that unsubscribes the recipient in one click (RFC 8058): the transport writes `List-Unsubscribe:
+	 * <url>` and `List-Unsubscribe-Post: List-Unsubscribe=One-Click`. A transport without `listUnsubscribe` refuses it.
+	 */
+	readonly unsubscribeUrl?: string
+	/**
+	 * 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.
+	 */
+	readonly attachments?: readonly EmailAttachment[]
 }
 
 export interface EmailDeliveryResult {
@@ -26,6 +43,10 @@ export interface EmailSenderCapabilities {
 	readonly confirmation: 'sync' | 'queued'
 	/** The most messages one call carries. `send` carries one, so every built-in adapter reports 1. */
 	readonly maxBatch: number
+	/** Whether it writes a message's one-click unsubscribe headers (`unsubscribeUrl`); absent is no. */
+	readonly listUnsubscribe?: boolean
+	/** The most attachment bytes one message carries, every file together; absent: it sends no attachments. */
+	readonly maxAttachmentBytes?: number
 }
 
 export interface EmailSender {
@@ -79,7 +100,17 @@ export class EmailDeliveryError extends Error {
 	}
 }
 
+/** The two headers of a one-click unsubscribe (RFC 8058), as a transport writes them for `unsubscribeUrl`. */
+export function oneClickUnsubscribeHeaders(url: string): Readonly<Record<string, string>> {
+	return { 'List-Unsubscribe': `<${url}>`, 'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click' }
+}
+
 /** The one retry rule: an unknown outcome is retried only over an idempotent transport. */
 export function mayRetryDelivery(error: EmailDeliveryError, capabilities: EmailSenderCapabilities): boolean {
 	return error.retryable && (error.outcome === 'not_sent' || capabilities.idempotent)
 }
+
+/** The bytes of every attachment of `message` together. */
+export function attachmentBytes(message: EmailMessage): number {
+	return (message.attachments ?? []).reduce((total, attachment) => total + attachment.content.byteLength, 0)
+}

package/src/index.ts

@@ -14,8 +14,9 @@ export type {
 	EmailSenderIdentity,
 	EmailTransportConfig,
 } from './config.js'
-export { EMAIL_DELIVERY_ERRORS, EmailDeliveryError, mayRetryDelivery } from './email.js'
+export { attachmentBytes, EMAIL_DELIVERY_ERRORS, EmailDeliveryError, mayRetryDelivery, oneClickUnsubscribeHeaders } from './email.js'
 export type {
+	EmailAttachment,
 	EmailDeliveryErrorCode,
 	EmailDeliveryErrorOptions,
 	EmailDeliveryOutcome,
@@ -25,4 +26,15 @@ export type {
 	EmailSender,
 	EmailSenderCapabilities,
 } from './email.js'
-export { isValidEmailAddress, isValidEmailDisplayName, isValidEmailFrom, MAX_EMAIL_SUBJECT_LENGTH, validateEmailMessage } from './validation.js'
+export {
+	isUnsubscribeUrl,
+	isValidAttachmentFilename,
+	isValidEmailAddress,
+	isValidEmailDisplayName,
+	isValidEmailFrom,
+	MAX_EMAIL_ATTACHMENTS,
+	MAX_EMAIL_SUBJECT_LENGTH,
+	MAX_UNSUBSCRIBE_URL_LENGTH,
+	validateEmailAttachments,
+	validateEmailMessage,
+} from './validation.js'

package/src/memory.ts

@@ -11,7 +11,7 @@ import {
 	type EmailSender,
 	type EmailSenderCapabilities,
 } from './email.js'
-import { validateEmailMessage } from './validation.js'
+import { validateEmailAttachments, validateEmailMessage } from './validation.js'
 
 export interface MemoryEmail {
 	readonly message: EmailMessage
@@ -51,6 +51,9 @@ interface KeyedEmail {
 	readonly messageId: string
 }
 
+/** Resend's bound, so a test meets the limit a production transport has. */
+const MEMORY_MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024
+
 const FAULT_MESSAGES: Readonly<Record<MemoryFault, string>> = {
 	provider_rejected: 'The memory sender rejected the message',
 	provider_unauthorized: 'The memory sender refused the credentials',
@@ -73,7 +76,14 @@ export class MemoryEmailSender implements EmailSender {
 	#taken = 0
 
 	constructor(options: MemoryEmailSenderOptions = {}) {
-		this.capabilities = { idempotent: true, confirmation: 'sync', maxBatch: 1, ...options.capabilities }
+		this.capabilities = {
+			idempotent: true,
+			confirmation: 'sync',
+			maxBatch: 1,
+			listUnsubscribe: true,
+			maxAttachmentBytes: MEMORY_MAX_ATTACHMENT_BYTES,
+			...options.capabilities,
+		}
 		if (!Number.isSafeInteger(this.capabilities.maxBatch) || this.capabilities.maxBatch < 1) {
 			throw new EmailDeliveryError('The memory sender batch size is invalid', { code: 'invalid_configuration' })
 		}
@@ -124,6 +134,10 @@ export class MemoryEmailSender implements EmailSender {
 
 	async send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult> {
 		validateEmailMessage(message)
+		if (message.unsubscribeUrl !== undefined && this.capabilities.listUnsubscribe !== true) {
+			throw new EmailDeliveryError('The memory sender writes no List-Unsubscribe header', { code: 'invalid_message' })
+		}
+		validateEmailAttachments(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

@@ -0,0 +1,207 @@
+// The wire of the platform transport's mail receiver: what an application's `PlatformEmailSender` posts to Control's
+// relay and what the relay answers. Both sides import it, so the encoding, the one parser and the status mapping
+// cannot drift apart. Runtime-neutral: Web APIs only.
+
+import { z } from 'zod'
+import { base64Of } from './content.js'
+import { EMAIL_DELIVERY_ERRORS, EmailDeliveryError, type EmailDeliveryErrorCode, type EmailMessage, type EmailSenderCapabilities } from './email.js'
+import { validateEmailAttachments, validateEmailMessage } from './validation.js'
+
+/** The relay's path under the receiver's URL (`FABRIKA_PLATFORM_MAIL_URL`). */
+export const PLATFORM_MAIL_SEND_PATH = '/platform/mail/send'
+
+/** What the relay promises: it records the message under its key and dispatches it later, perhaps after a person releases it. */
+export const PLATFORM_MAIL_CAPABILITIES: EmailSenderCapabilities = {
+	idempotent: true,
+	confirmation: 'queued',
+	maxBatch: 1,
+	listUnsubscribe: true,
+	maxAttachmentBytes: 10 * 1024 * 1024,
+}
+
+const LABEL = 'Platform mail'
+
+/** One attachment on the wire: the bytes as standard base64. */
+interface PlatformMailAttachment {
+	readonly filename: string
+	readonly contentType: string
+	readonly contentBase64: string
+}
+
+/** The request body: the message's own fields in a fixed order, absent optional fields left out. */
+interface PlatformMailRequest {
+	readonly to: string
+	readonly subject: string
+	readonly text: string
+	readonly html?: string
+	readonly idempotencyKey: string
+	readonly replyTo?: string
+	readonly fromName?: string
+	readonly unsubscribeUrl?: string
+	readonly attachments?: readonly PlatformMailAttachment[]
+}
+
+function platformMailRequestOf(message: EmailMessage): PlatformMailRequest {
+	const attachments = message.attachments ?? []
+	return {
+		to: message.to,
+		subject: message.subject,
+		text: message.text,
+		...(message.html === undefined ? {} : { html: message.html }),
+		idempotencyKey: message.idempotencyKey,
+		...(message.replyTo === undefined ? {} : { replyTo: message.replyTo }),
+		...(message.fromName === undefined ? {} : { fromName: message.fromName }),
+		...(message.unsubscribeUrl === undefined ? {} : { unsubscribeUrl: message.unsubscribeUrl }),
+		...(attachments.length === 0
+			? {}
+			: {
+				attachments: attachments.map((attachment) => ({
+					filename: attachment.filename,
+					contentType: attachment.contentType,
+					contentBase64: base64Of(attachment.content),
+				})),
+			}),
+	}
+}
+
+/**
+ * The request body as JSON text. It is canonical: two messages with the same content encode to the same text, so the
+ * relay fingerprints and stores this form.
+ */
+export function encodePlatformMailRequest(message: EmailMessage): string {
+	return JSON.stringify(platformMailRequestOf(message))
+}
+
+/** The SHA-256 (hex) of the canonical request body: what tells a repeated send from a different one under the same key. */
+export async function platformMailFingerprint(message: EmailMessage): Promise<string> {
+	return hexOf(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(encodePlatformMailRequest(message))))
+}
+
+/** The SHA-256 (hex) of a transport key: the only form the receiver stores. */
+export async function hashPlatformKey(key: string): Promise<string> {
+	return hexOf(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(key)))
+}
+
+/**
+ * The key an installation service (IAM) sends to the relay with: derived from the installation secret both it and
+ * Control already hold, so an existing installation needs no new secret.
+ */
+export async function installationMailKey(installationSecret: string): Promise<string> {
+	const secret = await crypto.subtle.importKey('raw', new TextEncoder().encode(installationSecret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])
+	return `px_${hexOf(await crypto.subtle.sign('HMAC', secret, new TextEncoder().encode('fabrika-platform-mail')))}`
+}
+
+function hexOf(digest: ArrayBuffer): string {
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+const BASE64_ALPHABET = /^[A-Za-z0-9+/]*={0,2}$/
+
+/** Standard padded base64. A single character class, because a grouped pattern overflows on a 10 MiB attachment. */
+function isBase64(value: string): boolean {
+	return value.length % 4 === 0 && BASE64_ALPHABET.test(value)
+}
+
+const attachmentSchema = z.object({
+	filename: z.string(),
+	contentType: z.string(),
+	contentBase64: z.string().refine(isBase64),
+}).strict()
+
+// Strict: a field this release does not know is refused, never dropped from a message someone will receive.
+const requestSchema = z.object({
+	to: z.string(),
+	subject: z.string(),
+	text: z.string(),
+	html: z.string().optional(),
+	idempotencyKey: z.string(),
+	replyTo: z.string().optional(),
+	fromName: z.string().optional(),
+	unsubscribeUrl: z.string().optional(),
+	attachments: z.array(attachmentSchema).optional(),
+}).strict()
+
+export type PlatformMailRequestResult =
+	| { readonly ok: true; readonly message: EmailMessage }
+	/** `reason` is a fixed text that names no recipient, subject or body. */
+	| { readonly ok: false; readonly code: 'invalid_message'; readonly reason: string }
+
+/** The relay's one parser of a request body (parsed JSON): a message the package's own validation accepts, or a refusal. */
+export function parsePlatformMailRequest(body: unknown): PlatformMailRequestResult {
+	const parsed = requestSchema.safeParse(body)
+	if (!parsed.success) return { ok: false, code: 'invalid_message', reason: 'Platform mail request is malformed' }
+	const { attachments, ...fields } = parsed.data
+	const message: EmailMessage = {
+		...fields,
+		...(attachments === undefined || attachments.length === 0
+			? {}
+			: {
+				attachments: attachments.map((attachment) => ({
+					filename: attachment.filename,
+					contentType: attachment.contentType,
+					content: bytesOf(attachment.contentBase64),
+				})),
+			}),
+	}
+	try {
+		validateEmailMessage(message)
+		validateEmailAttachments(message, PLATFORM_MAIL_CAPABILITIES, LABEL)
+	} catch (cause) {
+		if (cause instanceof EmailDeliveryError) return { ok: false, code: 'invalid_message', reason: cause.message }
+		throw cause
+	}
+	return { ok: true, message }
+}
+
+function bytesOf(base64: string): Uint8Array {
+	return Uint8Array.from(atob(base64), (character) => character.charCodeAt(0))
+}
+
+/** The HTTP status of each error the relay answers. */
+export const PLATFORM_MAIL_ERROR_STATUS = {
+	invalid_message: 400,
+	provider_unauthorized: 401,
+	idempotency_conflict: 409,
+	// An installation sender's message when Control has no transport: refused at once, as `not_sent`.
+	mail_not_configured: 503,
+	provider_unavailable: 503,
+} as const satisfies Partial<Record<EmailDeliveryErrorCode, number>>
+
+export type PlatformMailErrorCode = keyof typeof PLATFORM_MAIL_ERROR_STATUS
+
+export interface PlatformMailAccepted {
+	readonly status: 'accepted'
+	readonly messageId: string
+}
+
+/** The relay's answer as a sender reads it: any `EmailDeliveryErrorCode`, so its `retryable` and `outcome` carry over. */
+export type PlatformMailAnswer = PlatformMailAccepted | { readonly error: { readonly code: EmailDeliveryErrorCode } }
+
+/** The relay's answer as it writes one: an acceptance, or an error that has a status. */
+export type PlatformMailReply = PlatformMailAccepted | { readonly error: { readonly code: PlatformMailErrorCode } }
+
+/** `200 { status: 'accepted', messageId }`, or the error's status with `{ error: { code } }`. */
+export function platformMailAnswerResponse(reply: PlatformMailReply): Response {
+	if ('error' in reply) {
+		return Response.json({ error: { code: reply.error.code } }, { status: PLATFORM_MAIL_ERROR_STATUS[reply.error.code] })
+	}
+	return Response.json({ status: 'accepted', messageId: reply.messageId }, { status: 200 })
+}
+
+const errorCodeSchema = z.string().refine((code): code is EmailDeliveryErrorCode => Object.hasOwn(EMAIL_DELIVERY_ERRORS, code))
+const acceptedSchema = z.object({ status: z.literal('accepted'), messageId: z.string().min(1) })
+const errorSchema = z.object({ error: z.object({ code: errorCodeSchema }) })
+
+/**
+ * The relay's answer from its status and parsed JSON body, or `null` when it is no answer the relay writes: an
+ * acceptance under any status but 200, an error code under a success status, or anything else.
+ */
+export function parsePlatformMailAnswer(status: number, body: unknown): PlatformMailAnswer | null {
+	if (status === 200) {
+		const accepted = acceptedSchema.safeParse(body)
+		return accepted.success ? { status: 'accepted', messageId: accepted.data.messageId } : null
+	}
+	if (status < 400) return null
+	const refused = errorSchema.safeParse(body)
+	return refused.success ? { error: { code: refused.data.error.code } } : null
+}

package/src/platform.ts

@@ -0,0 +1,109 @@
+import {
+	EmailDeliveryError,
+	type EmailDeliveryResult,
+	type EmailFetch,
+	type EmailMessage,
+	type EmailSender,
+	type EmailSenderCapabilities,
+} 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'
+
+export {
+	encodePlatformMailRequest,
+	hashPlatformKey,
+	installationMailKey,
+	parsePlatformMailAnswer,
+	parsePlatformMailRequest,
+	PLATFORM_MAIL_CAPABILITIES,
+	PLATFORM_MAIL_ERROR_STATUS,
+	PLATFORM_MAIL_SEND_PATH,
+	platformMailAnswerResponse,
+	platformMailFingerprint,
+} from './platform-wire.js'
+export type {
+	PlatformMailAccepted,
+	PlatformMailAnswer,
+	PlatformMailErrorCode,
+	PlatformMailReply,
+	PlatformMailRequestResult,
+} from './platform-wire.js'
+
+/** `FABRIKA_EMAIL_PROVIDER=platform`: the application sends through the platform's relay, not a provider of its own. */
+export const PLATFORM_EMAIL_PROVIDER = 'platform'
+
+const LABEL = 'Platform mail'
+
+export interface PlatformEmailSenderOptions {
+	/** The receiver's http(s) origin (`FABRIKA_PLATFORM_MAIL_URL`); the send path is appended to it. */
+	readonly url: string
+	readonly key: string
+	readonly fetch?: EmailFetch
+	readonly timeoutMs?: number
+}
+
+/** Hands each message to the platform's relay, which records it under its key and dispatches it later. */
+export class PlatformEmailSender implements EmailSender {
+	readonly capabilities: EmailSenderCapabilities = PLATFORM_MAIL_CAPABILITIES
+	readonly #sendUrl: string
+	readonly #key: string
+	readonly #fetch: EmailFetch
+	readonly #timeoutMs: number
+
+	constructor(options: PlatformEmailSenderOptions) {
+		if (!isHttpOrigin(options.url)) {
+			throw new EmailDeliveryError('Platform mail URL is not an http(s) origin', { code: 'invalid_configuration' })
+		}
+		if (options.key.length === 0 || !isVisibleAscii(options.key)) {
+			throw new EmailDeliveryError('Platform mail key is invalid', { code: 'invalid_configuration' })
+		}
+
+		this.#sendUrl = `${options.url}${PLATFORM_MAIL_SEND_PATH}`
+		this.#key = options.key
+		this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init))
+		this.#timeoutMs = parseTimeout(LABEL, options.timeoutMs)
+	}
+
+	async send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult> {
+		validateEmailMessage(message)
+		validateEmailAttachments(message, this.capabilities, LABEL)
+
+		// postToProvider serializes the body itself; the canonical text survives the round trip unchanged.
+		const body: unknown = JSON.parse(encodePlatformMailRequest(message))
+		const response = await postToProvider({
+			label: LABEL,
+			fetch: this.#fetch,
+			url: this.#sendUrl,
+			headers: { Authorization: `Bearer ${this.#key}` },
+			body,
+			signal,
+			timeoutMs: this.#timeoutMs,
+		})
+
+		const answer = parsePlatformMailAnswer(response.status, response.body)
+		if (answer === null) {
+			throw new EmailDeliveryError(`Platform mail relay returned an invalid answer (${response.status})`, {
+				code: 'malformed_response',
+				httpStatus: response.status,
+			})
+		}
+		if ('error' in answer) {
+			throw new EmailDeliveryError(`Platform mail relay refused the message (${response.status})`, {
+				code: answer.error.code,
+				httpStatus: response.status,
+			})
+		}
+		return { status: 'accepted', provider: 'platform', messageId: answer.messageId }
+	}
+}
+
+/** `http(s)://host[:port]` exactly as written: no path, query, fragment or credentials. */
+function isHttpOrigin(value: string): boolean {
+	try {
+		const url = new URL(value)
+		return (url.protocol === 'http:' || url.protocol === 'https:') && url.origin === value
+	} catch {
+		return false
+	}
+}

package/src/resend.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { type EmailProvider, type EmailSenderIdentity, parseProviderVariables } from './config.js'
+import { base64Of } from './content.js'
 import {
 	EmailDeliveryError,
 	type EmailDeliveryResult,
@@ -7,9 +8,10 @@ import {
 	type EmailMessage,
 	type EmailSender,
 	type EmailSenderCapabilities,
+	oneClickUnsubscribeHeaders,
 } from './email.js'
 import { parseTimeout, postToProvider, type ProviderResponse } from './http.js'
-import { isValidEmailSenderIdentity, isVisibleAscii, validateEmailMessage } from './validation.js'
+import { isValidEmailSenderIdentity, isVisibleAscii, validateEmailAttachments, validateEmailMessage } from './validation.js'
 
 const RESEND_EMAILS_URL = 'https://api.resend.com/emails'
 const LABEL = 'Resend'
@@ -18,6 +20,8 @@ const resendErrorSchema = z.object({ name: z.string() })
 const QUOTA_ERRORS: ReadonlySet<string> = new Set(['daily_quota_exceeded', 'monthly_quota_exceeded'])
 /** RFC 5322 specials a display name may still hold after validation; any of them makes the name a quoted string. */
 const DISPLAY_NAME_SPECIALS = /[()[\]:;@,.]/
+/** Resend refuses a message over 40 MB once its attachments are base64; 25 MiB of bytes leaves room for the rest. */
+const RESEND_MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024
 
 export interface ResendEmailSenderOptions {
 	readonly apiKey: string
@@ -27,7 +31,13 @@ export interface ResendEmailSenderOptions {
 }
 
 export class ResendEmailSender implements EmailSender {
-	readonly capabilities: EmailSenderCapabilities = { idempotent: true, confirmation: 'sync', maxBatch: 1 }
+	readonly capabilities: EmailSenderCapabilities = {
+		idempotent: true,
+		confirmation: 'sync',
+		maxBatch: 1,
+		listUnsubscribe: true,
+		maxAttachmentBytes: RESEND_MAX_ATTACHMENT_BYTES,
+	}
 	readonly #apiKey: string
 	readonly #from: EmailSenderIdentity
 	readonly #fetch: EmailFetch
@@ -49,6 +59,8 @@ export class ResendEmailSender implements EmailSender {
 
 	async send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult> {
 		validateEmailMessage(message)
+		validateEmailAttachments(message, this.capabilities, LABEL)
+		const attachments = message.attachments ?? []
 
 		const response = await postToProvider({
 			label: LABEL,
@@ -62,6 +74,16 @@ export class ResendEmailSender implements EmailSender {
 				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,
+						})),
+					}),
 			},
 			signal,
 			timeoutMs: this.#timeoutMs,

package/src/smartemailing.ts

@@ -12,7 +12,7 @@ import {
 	type EmailSenderCapabilities,
 } from './email.js'
 import { parseTimeout, postToProvider } from './http.js'
-import { isValidEmailSenderIdentity, isVisibleAscii, validateEmailMessage } from './validation.js'
+import { isValidEmailSenderIdentity, isVisibleAscii, validateEmailAttachments, validateEmailMessage } from './validation.js'
 
 const SMARTEMAILING_SEND_URL = 'https://app.smartemailing.cz/api/v3/send/transactional-emails-bulk'
 const LABEL = 'SmartEmailing'
@@ -64,6 +64,11 @@ export class SmartEmailingEmailSender implements EmailSender {
 
 	async send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult> {
 		validateEmailMessage(message)
+		// Its API documents no message headers, so a one-click unsubscribe is refused rather than sent without one.
+		if (message.unsubscribeUrl !== undefined) {
+			throw new EmailDeliveryError('SmartEmailing cannot write the List-Unsubscribe headers', { code: 'invalid_message' })
+		}
+		validateEmailAttachments(message, this.capabilities, LABEL)
 
 		const senderName = message.fromName ?? this.#from.name
 		const response = await postToProvider({

package/src/validation.ts

@@ -1,5 +1,5 @@
 import type { EmailSenderIdentity } from './config.js'
-import { EmailDeliveryError, type EmailMessage } from './email.js'
+import { attachmentBytes, EmailDeliveryError, type EmailMessage, type EmailSenderCapabilities } from './email.js'
 
 /** The longest subject a message may have, in UTF-16 code units: RFC 5322's line limit. */
 export const MAX_EMAIL_SUBJECT_LENGTH = 998
@@ -63,6 +63,49 @@ export function validateEmailMessage(message: EmailMessage): void {
 	}
 	if (message.replyTo !== undefined && !isValidEmailAddress(message.replyTo)) throw invalidMessage('Email reply-to address is invalid')
 	if (message.fromName !== undefined && !isValidEmailDisplayName(message.fromName)) throw invalidMessage('Email sender name is invalid')
+	if (message.unsubscribeUrl !== undefined && !isUnsubscribeUrl(message.unsubscribeUrl)) throw invalidMessage('Email unsubscribe URL is invalid')
+	const attachments = message.attachments ?? []
+	if (attachments.length > MAX_EMAIL_ATTACHMENTS) throw invalidMessage(`Email has more than ${MAX_EMAIL_ATTACHMENTS} attachments`)
+	for (const attachment of attachments) {
+		if (!isValidAttachmentFilename(attachment.filename)) throw invalidMessage('Email attachment name is invalid')
+		if (!MEDIA_TYPE.test(attachment.contentType)) throw invalidMessage('Email attachment type is invalid')
+	}
+}
+
+/**
+ * Refuses a message whose attachments `capabilities` does not carry: any attachment where the transport sends none, or
+ * more bytes together than its `maxAttachmentBytes`. `label` names the transport in the message.
+ */
+export function validateEmailAttachments(message: EmailMessage, capabilities: EmailSenderCapabilities, label: string): void {
+	if ((message.attachments ?? []).length === 0) return
+	const limit = capabilities.maxAttachmentBytes
+	if (limit === undefined) throw invalidMessage(`${label} sends no attachments`)
+	const bytes = attachmentBytes(message)
+	if (bytes > limit) throw invalidMessage(`Email attachments have ${bytes} bytes, more than the ${limit} ${label} sends`)
+}
+
+/** The most files one message carries. */
+export const MAX_EMAIL_ATTACHMENTS = 20
+
+const MEDIA_TYPE = /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}\/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}$/
+
+/** 1..255 characters, no control characters, no path separator and no `"`, so every transport can quote it. */
+export function isValidAttachmentFilename(value: string): boolean {
+	return value.length > 0 && value.length <= 255 && value.trim() === value && !containsControlCharacter(value) && !/[/\\"]/.test(value)
+}
+
+/** The longest unsubscribe URL a header carries: one header line, with room for its name. */
+export const MAX_UNSUBSCRIBE_URL_LENGTH = 2048
+
+/** An absolute `https:` URL as it is written, which a `<…>` header value carries unchanged. */
+export function isUnsubscribeUrl(value: string): boolean {
+	if (value.length > MAX_UNSUBSCRIBE_URL_LENGTH || containsControlCharacter(value) || /[\s<>"]/.test(value)) return false
+	try {
+		const url = new URL(value)
+		return url.protocol === 'https:' && url.href === value && url.username === '' && url.password === ''
+	} catch {
+		return false
+	}
 }
 
 function invalidMessage(message: string): EmailDeliveryError {