@ultimat3/mail 23.0.0 → 25.0.0

package/src/driver.ts

@@ -13,6 +13,7 @@ import {
 } from '@ultimat3/core';
 import { driverUnavailable, mailCredentialMissing } from './errors';
 import { mailIdempotencyKey, mailMessageIdToken } from './idempotency';
+import type { RetainedMime } from './retain-mime';
 
 /** The rendered envelope. Everything a transport needs; nothing it does not. */
 export interface MailMessage {
@@ -46,6 +47,11 @@ export interface SendResult {
   /** True when the message was handed to the queue instead of a transport. */
   readonly queued: boolean;
   readonly idempotencyKey: string;
+  /**
+   * The exact MIME this process handed the provider — present only on a transport that builds it
+   * (SMTP, SES) constructed with `retainMime`. Bounded: over the cap only the digest is kept.
+   */
+  readonly mime?: RetainedMime | undefined;
 }
 
 export interface MailDriver {
@@ -62,7 +68,7 @@ export function messageHeaders(message: MailMessage): Readonly<Record<string, st
   const headers: Record<string, string> = { 'Auto-Submitted': 'auto-generated' };
   if (message.replyTo !== undefined) headers['Reply-To'] = message.replyTo;
   if (message.unsubscribeUrl !== undefined) {
-    headers['List-Unsubscribe'] = `<${message.unsubscribeUrl}>`;
+    headers['List-Unsubscribe'] = `<${unsubscribeTarget(message.unsubscribeUrl)}>`;
     if (message.unsubscribeOneClick !== false) {
       headers['List-Unsubscribe-Post'] = 'List-Unsubscribe=One-Click';
     }
@@ -70,6 +76,22 @@ export function messageHeaders(message: MailMessage): Readonly<Record<string, st
   return headers;
 }
 
+/**
+ * The url as the WHATWG serialiser writes it: host as punycode, path, query and fragment
+ * percent-encoded — 7-bit, and with no bare `>` to close the angle bracket early. It went out as
+ * written, so a non-ASCII url was raw 8-bit octets in a header. A url holding a control character
+ * is copied through UNTOUCHED: the serialiser silently drops CR, LF and tab, and a header break is
+ * refused by the CR/LF gate, never stripped into a different url. `send()` and the queue schema
+ * refuse an unparseable url first; a hand-built one is copied through and stays the caller's.
+ */
+function unsubscribeTarget(url: string): string {
+  if (CONTROL.test(url)) return url;
+  return URL.parse(url)?.href ?? url;
+}
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: the control range IS the rule.
+const CONTROL = /[\u0000-\u001f\u007f]/;
+
 /**
  * Every address the envelope is delivered to. `Bcc` is one of them and never a header —
  * an SMTP `RCPT TO` carries it, and putting it in the message would leak the blind list.
@@ -112,7 +134,7 @@ export interface MemoryMailDriver extends MailDriver {
 }
 
 /**
- * The same `{ clock }` shape `@ultimat3/jobs`' `createMemoryDriver` takes, deliberately: two
+ * The same `{ clock }` shape `@ultimat3/jobs`' `memoryJobDriver` takes, deliberately: two
  * in-memory drivers named the same thing in one test file may not want two spellings of "freeze
  * time". An options object rather than a positional argument so the next seam is additive.
  */
@@ -125,7 +147,7 @@ export interface MemoryMailDriverOptions {
  * `/_x` panel ORDER on, so a suite asserting which message is newest could only race the wall
  * clock — two sends inside one millisecond tie, and nothing could state the intended order.
  */
-export function createMemoryDriver(options: MemoryMailDriverOptions = {}): MemoryMailDriver {
+export function memoryMailDriver(options: MemoryMailDriverOptions = {}): MemoryMailDriver {
   const clock = options.clock ?? systemClock;
   const sent: SentMail[] = [];
   return {
@@ -171,7 +193,7 @@ export const UNCONFIGURED_DRIVER_NAME = 'unconfigured';
  * that does sends nothing silently. The memory driver in that position answered `accepted` for
  * every message — a password reset reported as delivered, with no error anywhere to find it by.
  */
-export function createUnconfiguredDriver(environment: Environment): MailDriver {
+export function unconfiguredMailDriver(environment: Environment): MailDriver {
   return {
     name: UNCONFIGURED_DRIVER_NAME,
     // Rejected rather than thrown: `send()` and `sendMailJob` both await this, and a synchronous
@@ -197,7 +219,7 @@ export function isUnconfiguredDriver(driver: MailDriver): boolean {
  * framework's existing spelling for the same key digested — it was written for exactly this
  * reason and says so — and it correlates just as well, because it is stable per message.
  */
-export function createLogDriver(logger = rootLogger): MailDriver {
+export function logMailDriver(logger = rootLogger): MailDriver {
   return {
     name: 'log',
     send(message: MailMessage): Promise<SendResult> {
@@ -216,7 +238,7 @@ export function createLogDriver(logger = rootLogger): MailDriver {
 
 let ambient: MailDriver | undefined;
 
-/** Set once at boot from `app.config.ts`. One driver per process, like the job driver. */
+/** Set once at boot from the environment (`selectMailDriver`). One per process, like the job driver. */
 export function setMailDriver(driver: MailDriver): void {
   ambient = driver;
 }

package/src/envelope-address.ts

@@ -4,7 +4,7 @@
 // thing only — the RFC 5322 display form down to the mailbox `RCPT TO:` can carry, always after
 // the control-character check, never before it.
 
-import { addressInvalid, type EnvelopeAddressField } from './errors';
+import { type AddressRefusal, addressInvalid, type EnvelopeAddressField } from './errors';
 import { addressSpec, hasNonAsciiAddrSpec } from './mime';
 
 /**
@@ -39,29 +39,49 @@ function hasControlCharacter(address: string): boolean {
   return false;
 }
 
+/** What `isUnsafe` and the mailbox check say of a bare addr-spec — the half both gates share. */
+function specRefusal(spec: string): AddressRefusal | undefined {
+  if (isUnsafe(spec)) return 'injection';
+  // Two reasons, checked in this order: an injection is the dangerous one and an address carrying
+  // both should say so. The addr-spec, never the phrase — `mime.ts` has an RFC 2047 encoding for a
+  // display name and none for a mailbox.
+  return hasNonAsciiAddrSpec(spec) ? 'non-ascii' : undefined;
+}
+
 /** Throws `X_MAIL_ADDRESS_INVALID` before a single byte of the envelope is written. */
 export function assertEnvelopeAddress(field: EnvelopeAddressField, address: string): void {
-  if (isUnsafe(address)) throw addressInvalid(field, 'injection');
-  // Two reasons, two `meta.reason`s, checked in this order: an injection is the dangerous one and
-  // an address carrying both should say so. The addr-spec, never the phrase — `mime.ts` has an
-  // RFC 2047 encoding for a display name and none for a mailbox.
-  if (hasNonAsciiAddrSpec(address)) throw addressInvalid(field, 'non-ascii');
+  const refusal = specRefusal(address);
+  if (refusal !== undefined) throw addressInvalid(field, refusal);
 }
 
 /**
- * The addr-spec an envelope command may carry, from whatever form the caller wrote. `Jane Doe
- * <jane@x.test>` is the ordinary RFC 5322 display form — the `To:` header carries it verbatim and
- * the resend, memory and log drivers all accept it — but `RCPT TO:` takes a mailbox, so it is
- * stripped here and the gate above runs on what is left.
+ * Why `address` cannot be a recipient, or `undefined` when it can — `envelopeAddress`'s rule without
+ * the throw, so the queue schema (`job.ts`) and `renderMessage` (`mail.ts`) ask the SAME question
+ * the SMTP envelope does. It was `t.email` on the queue and nothing inline, so a display-form
+ * recipient was `queued: true` at `send()` and then refused by the worker's parse.
  *
  * The control-character half runs on the RAW value, BEFORE the strip, and the order is the whole
  * point: `ops@x.test\r\nRCPT TO:<attacker@evil.test>` strips down to a clean-looking mailbox that
  * every later check waves through, so a strip-then-check would have turned the injection into a
  * delivery to the attacker instead of a refusal.
  */
+export function addressRefusal(address: string): AddressRefusal | undefined {
+  return hasControlCharacter(address) ? 'injection' : specRefusal(addressSpec(address));
+}
+
+/** Throws `X_MAIL_ADDRESS_INVALID` for any address `addressRefusal` refuses. */
+export function assertRecipientAddress(field: EnvelopeAddressField, address: string): void {
+  const refusal = addressRefusal(address);
+  if (refusal !== undefined) throw addressInvalid(field, refusal);
+}
+
+/**
+ * The addr-spec an envelope command may carry, from whatever form the caller wrote. `Jane Doe
+ * <jane@x.test>` is the ordinary RFC 5322 display form — the `To:` header carries it verbatim and
+ * every driver accepts it — but `RCPT TO:` takes a mailbox, so it is stripped here once
+ * `addressRefusal` has passed the raw value.
+ */
 export function envelopeAddress(field: EnvelopeAddressField, address: string): string {
-  if (hasControlCharacter(address)) throw addressInvalid(field, 'injection');
-  const spec = addressSpec(address);
-  assertEnvelopeAddress(field, spec);
-  return spec;
+  assertRecipientAddress(field, address);
+  return addressSpec(address);
 }

package/src/errors.ts

@@ -21,6 +21,9 @@ export const MAIL_ERROR_CODES = [
   'X_MAIL_ADDRESS_INVALID',
   'X_MAIL_SEND_FAILED',
   'X_MAIL_TRANSFORM_FAILED',
+  'X_MAIL_EVENT_UNVERIFIED',
+  'X_MAIL_EVENT_INVALID',
+  'X_MAIL_EVENT_PROVIDER_UNREACHABLE',
 ] as const;
 
 export type MailErrorCode = (typeof MAIL_ERROR_CODES)[number];
@@ -36,6 +39,9 @@ export const MAIL_ERROR_TITLES: Readonly<Record<MailErrorCode, string>> = {
   X_MAIL_ADDRESS_INVALID: 'an envelope address could restructure the SMTP command line',
   X_MAIL_SEND_FAILED: 'the mail transport refused the message',
   X_MAIL_TRANSFORM_FAILED: 'the app mail transform threw or returned no message',
+  X_MAIL_EVENT_UNVERIFIED: 'a delivery notification is not signed by its provider',
+  X_MAIL_EVENT_INVALID: 'a delivery notification is not a shape this receiver reads',
+  X_MAIL_EVENT_PROVIDER_UNREACHABLE: 'an SNS endpoint the receiver needed did not answer',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -159,7 +165,7 @@ export const driverUnavailable = (what: string): MailError =>
   new MailError({
     code: 'X_MAIL_DRIVER_UNAVAILABLE',
     cause: `${what} — nothing can deliver the message`,
-    fix: 'setMailDriver(createMemoryDriver()) in dev, createSmtpDriver({ url: env.SMTP_URL }) live',
+    fix: 'setMailDriver(memoryMailDriver()) in dev, smtpMailDriver({ url: env.SMTP_URL }) live',
     meta: { what },
   });
 
@@ -177,27 +183,62 @@ export const mailCredentialMissing = (environment: Environment): MailError =>
   new MailError({
     code: 'X_MAIL_CREDENTIAL_MISSING',
     cause:
-      `neither SMTP_URL nor RESEND_API_KEY is set in ${environment}, so this process has no ` +
-      'transport — the message was not delivered and was not queued anywhere',
+      `none of SMTP_URL, RESEND_API_KEY or SES_REGION is set in ${environment}, so this process ` +
+      'has no transport — the message was not delivered and was not queued anywhere',
     fix:
-      'set SMTP_URL="smtps://user:pass@host:465" (or RESEND_API_KEY=re_...) and ' +
+      'set SMTP_URL="smtps://user:pass@host:465" (or RESEND_API_KEY=re_..., or SES_REGION with ' +
+      'SES_ACCESS_KEY_ID and SES_SECRET_ACCESS_KEY) and ' +
       'MAIL_FROM="App <no-reply@yourdomain.test>" in the deployment environment, then restart',
-    meta: { environment, missing: ['SMTP_URL', 'RESEND_API_KEY'] },
+    meta: { environment, missing: ['SMTP_URL', 'RESEND_API_KEY', 'SES_REGION'] },
   });
 
+/**
+ * Why a header was refused. Two reasons, one code, as `AddressRefusal` is for the envelope: a
+ * non-ASCII MAILBOX in an address header was raised with the line-break cause, which named a
+ * character the value did not hold.
+ */
+export type HeaderRefusal = 'line-break' | 'non-ascii';
+
+/** The `send()` option each address header comes from; `From` is the transport's own config. */
+const ADDRESS_OPTION: ReadonlyMap<string, string> = new Map([
+  ['To', 'to'],
+  ['Cc', 'cc'],
+  ['Reply-To', 'replyTo'],
+]);
+
+/**
+ * The domain as punycode is the ASCII form; a non-ASCII LOCAL part has none and needs another
+ * mailbox. The example is fixed text — an address is recipient data, never echoed back.
+ */
+const nonAsciiFix = (name: string): string => {
+  const option = ADDRESS_OPTION.get(name);
+  return option === undefined
+    ? 'set mail.from in app.config.ts to an ASCII mailbox, e.g. no-reply@example.test'
+    : `pass the mailbox's ASCII form, the domain as punycode: send(mail, data, { ${option}: 'jose@xn--exmple-cua.test', locale })`;
+};
+
 /**
  * A CR or LF inside a header value ends the header early and lets whatever follows become new
  * headers — the recipient list, a forged `From`. Interpolated data reaches `Subject`, so this is
  * refused rather than stripped: silently rewriting a subject is its own surprise.
  */
-export const headerInvalid = (name: string, mailId: string): MailError =>
+export const headerInvalid = (
+  name: string,
+  mailId: string,
+  reason: HeaderRefusal = 'line-break',
+): MailError =>
   new MailError({
     code: 'X_MAIL_HEADER_INVALID',
-    cause: `the "${name}" header of mail "${mailId}" contains a CR or LF, which would inject headers`,
+    cause:
+      reason === 'line-break'
+        ? `the "${name}" header of mail "${mailId}" contains a CR or LF, which would inject headers`
+        : `the "${name}" header of mail "${mailId}" holds a non-ASCII byte in its mailbox, and this package negotiates no SMTPUTF8, so the address cannot be written as a header`,
     fix:
-      `strip line breaks from the value before it reaches the header: ` +
-      `t('mail.${mailId}.subject', { ...data, x: String(x).replace(/[\\r\\n]+/g, ' ') })`,
-    meta: { header: name, mailId },
+      reason === 'line-break'
+        ? `strip line breaks from the value before it reaches the header: ` +
+          `t('mail.${mailId}.subject', { ...data, x: String(x).replace(/[\\r\\n]+/g, ' ') })`
+        : nonAsciiFix(name),
+    meta: { header: name, mailId, reason },
   });
 
 /**
@@ -275,7 +316,7 @@ export type SendStage =
  * code or an HTTP status — because "mail failed" without either is not a diagnosis.
  */
 export interface SendFailure {
-  readonly driver: 'smtp' | 'resend';
+  readonly driver: 'smtp' | 'resend' | 'ses';
   readonly stage: SendStage;
   readonly detail: string;
   /** SMTP reply code (4xx/5xx) or HTTP status. Absent when the socket never answered. */

package/src/events.ts

@@ -0,0 +1,28 @@
+// Single responsibility: the public API of `@ultimat3/mail/events` — the delivery-notification
+// receivers and their verification. A subpath and not the barrel because only an app's webhook
+// route uses them, and every serving role (worker, scheduler, migrate) loads the barrel to send.
+
+export type {
+  DeliveryEvent,
+  DeliveryEventKind,
+  DeliveryOutcome,
+  DeliveryReceiver,
+} from './delivery-event';
+export { DEFAULT_DELIVERY_BODY_LIMIT } from './delivery-event';
+export type {
+  DeliveryProvider,
+  DeliveryRefusal,
+  DeliveryShapeProblem,
+  ResendRefusal,
+} from './delivery-event-errors';
+export {
+  deliveryEventInvalid,
+  deliveryEventUnverified,
+  deliveryProviderUnreachable,
+} from './delivery-event-errors';
+export type { ResendEventReceiverOptions } from './resend-event-receiver';
+export { resendEventReceiver } from './resend-event-receiver';
+export { DEFAULT_SVIX_TOLERANCE_MS } from './resend-signature';
+export type { SesEventReceiverOptions } from './ses-event-receiver';
+export { DEFAULT_SNS_TOLERANCE_MS, sesEventReceiver } from './ses-event-receiver';
+export type { SnsCertificateFetch } from './sns-certificate-cache';

package/src/html.ts

@@ -1,19 +1,8 @@
-// Single responsibility: turning untrusted values into inert HTML. Mail bodies interpolate
-// user-supplied names, org names and URLs; an unescaped one is a phishing vector that also
-// renders in the recipient's client forever, so escaping lives in exactly one place.
+// Single responsibility: the mail-specific half of making untrusted values inert — which URLs a
+// link may carry and how a style attribute is written. The character escaping is core's
+// `escapeHtml`, the one table: an unescaped name in a mail is a phishing vector forever.
 
-const ESCAPES: Readonly<Record<string, string>> = {
-  '&': '&amp;',
-  '<': '&lt;',
-  '>': '&gt;',
-  '"': '&quot;',
-  "'": '&#39;',
-};
-
-/** Escape text content AND attribute values — the same set covers both in mail. */
-export function escapeHtml(value: string): string {
-  return value.replace(/[&<>"']/g, (char) => ESCAPES[char] ?? char);
-}
+import { escapeHtml } from '@ultimat3/core';
 
 const SAFE_PROTOCOLS: readonly string[] = ['http:', 'https:', 'mailto:'];
 
@@ -21,7 +10,7 @@ const SAFE_PROTOCOLS: readonly string[] = ['http:', 'https:', 'mailto:'];
  * `javascript:` and `data:` hrefs are stripped rather than escaped: some clients still
  * follow them, and a link the recipient cannot trust is worse than a dead one.
  */
-export function safeUrl(value: string): string {
+export function safeMailHref(value: string): string {
   let parsed: URL;
   try {
     parsed = new URL(value);

package/src/index.ts

@@ -6,8 +6,15 @@ export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
 export type { CalloutTone, MailBlock, MailTemplate, TemplateArgs } from './blocks';
 export { blocks } from './blocks';
-
-export { MAIL_CATALOG, MAIL_CATALOG_LOCALE } from './catalog';
+export { MAIL_CATALOG } from './catalog';
+// Type-only, so a sender can name an event without loading a receiver; the receivers are
+// `@ultimat3/mail/events`, kept off the barrel every serving role evaluates.
+export type {
+  DeliveryEvent,
+  DeliveryEventKind,
+  DeliveryOutcome,
+  DeliveryReceiver,
+} from './delivery-event';
 export type {
   MailDriver,
   MailMessage,
@@ -17,23 +24,25 @@ export type {
   SentMail,
 } from './driver';
 export {
-  createLogDriver,
-  createMemoryDriver,
-  createUnconfiguredDriver,
   isMemoryDriver,
   isUnconfiguredDriver,
+  logMailDriver,
   mailDriver,
+  memoryMailDriver,
   messageHeaders,
   resetMailDriver,
   setMailDriver,
   tryMailDriver,
+  unconfiguredMailDriver,
 } from './driver';
-export type { MailEnvironment, MailSelection } from './driver-env';
+export type { MailEnvironment, MailSelection, MailSelectOptions } from './driver-env';
 export { selectMailDriver } from './driver-env';
 export type { MailFetch, ResendDriverOptions } from './driver-resend';
-export { createResendDriver } from './driver-resend';
+export { resendMailDriver } from './driver-resend';
+export type { SesDriverOptions } from './driver-ses';
+export { sesEndpoint, sesMailDriver } from './driver-ses';
 export type { SmtpDriverOptions } from './driver-smtp';
-export { createSmtpDriver } from './driver-smtp';
+export { smtpMailDriver } from './driver-smtp';
 export { assertEnvelopeAddress } from './envelope-address';
 export type {
   AddressRefusal,
@@ -61,8 +70,7 @@ export {
   transformFailed,
 } from './errors';
 export { assertHeaderSafe } from './header-safety';
-
-export { escapeHtml, safeUrl } from './html';
+export { safeMailHref } from './html';
 
 export { mailIdempotencyKey, mailMessageIdToken } from './idempotency';
 export { mailMessageSchema, sendMailJob } from './job';
@@ -96,6 +104,8 @@ export {
 } from './mail';
 export type { RenderableMail, RenderedMail, RenderOptions } from './render';
 export { renderMail, textOf } from './render';
+export type { RetainedMime, RetainedMimeEntry, RetainMimeOptions } from './retain-mime';
+export { DEFAULT_RETAIN_MIME_MAX_BYTES, RETAIN_MIME_CEILING_BYTES } from './retain-mime';
 export type { SmtpConnector, SmtpStream } from './smtp-client';
 export {
   FRAMEWORK_MAILS,

package/src/job.ts

@@ -5,21 +5,33 @@
 import { type JobHandle, job } from '@ultimat3/jobs';
 import { type StandardSchemaV1, t } from '@ultimat3/schema';
 import { type MailMessage, mailDriver, type SendResult } from './driver';
+import { addressRefusal } from './envelope-address';
 import { assertHeaderSafe } from './header-safety';
 import { mailIdempotencyKey } from './idempotency';
 
+/**
+ * A recipient by the rule the SMTP envelope applies (`addressRefusal`), never `t.email`: the
+ * inline path takes the RFC 5322 display form, so a stricter queue schema turned a `send()` that
+ * answered `queued: true` into a worker that refused the row it had just been handed.
+ */
+const mailAddress = t.refine(t.string, {
+  name: 'mail-address',
+  message: 'a mailbox or a display-form address, with no control character or non-ASCII mailbox',
+  check: (address) => addressRefusal(address) === undefined,
+});
+
 /** The queue payload is the already-rendered envelope: rendering happens once, at send time. */
 export const mailMessageSchema: StandardSchemaV1<unknown, MailMessage> = t.object({
   mailId: t.string,
-  to: t.array(t.email),
+  to: t.array(mailAddress),
   subject: t.string,
   html: t.string,
   text: t.string,
   locale: t.locale,
   tz: t.timezone,
-  replyTo: t.email.optional(),
-  cc: t.array(t.email).optional(),
-  bcc: t.array(t.email).optional(),
+  replyTo: mailAddress.optional(),
+  cc: t.array(mailAddress).optional(),
+  bcc: t.array(mailAddress).optional(),
   unsubscribeUrl: t.url.optional(),
   unsubscribeOneClick: t.boolean.optional(),
   idempotencyKey: t.string.optional(),

package/src/layout.ts

@@ -3,8 +3,9 @@
 // renderer, because email clients drop <style> and templates must never carry a raw hex.
 // Table-based and 600px wide: Outlook still renders with Word's HTML engine.
 
+import { escapeHtml } from '@ultimat3/core';
 import { mailLayoutDuplicate } from './errors';
-import { escapeHtml, safeUrl, styleAttr } from './html';
+import { safeMailHref, styleAttr } from './html';
 
 export type ColorScheme = 'light' | 'dark';
 
@@ -199,7 +200,7 @@ function footerHtml(input: LayoutInput): string {
   const lines = input.footer.map((line) => `<div>${escapeHtml(line)}</div>`);
   const slot = input.unsubscribe;
   if (slot !== undefined) {
-    const href = escapeHtml(safeUrl(slot.url));
+    const href = escapeHtml(safeMailHref(slot.url));
     const label = escapeHtml(slot.label);
     lines.push(`<div><a data-x="a" href="${href}" ${UNSUBSCRIBE_STYLE}>${label}</a></div>`);
   }

package/src/mail.ts

@@ -4,10 +4,11 @@
 // piece of context that a background send cannot recover after the fact.
 
 import { assert, DEFAULT_TIME_ZONE, tryUseContext } from '@ultimat3/core';
-import { jobDriver } from '@ultimat3/jobs';
-import { parse, type StandardSchemaV1 } from '@ultimat3/schema';
+import { jobDriver, jobsFacade } from '@ultimat3/jobs';
+import { parse, type StandardSchemaV1, t } from '@ultimat3/schema';
 import type { MailTemplate } from './blocks';
-import { type MailMessage, mailDriver, type SendResult } from './driver';
+import { envelopeRecipients, type MailMessage, mailDriver, type SendResult } from './driver';
+import { assertRecipientAddress } from './envelope-address';
 import { localeMissing, mailDuplicate, templateUnknown } from './errors';
 import { assertHeaderSafe } from './header-safety';
 import { mailIdempotencyKey } from './idempotency';
@@ -90,7 +91,9 @@ export function mailFor(id: string): AnyMailDefinition | undefined {
 }
 
 export function registeredMails(): readonly AnyMailDefinition[] {
-  return [...registry.values()].sort((a, b) => a.id.localeCompare(b.id));
+  // Through `registeredMailIds`, so the two views share ONE order: the code-unit sort. It was
+  // `localeCompare` here, which puts `welcome` before `Zeta` where the id list puts it after.
+  return registeredMailIds().flatMap((id) => registry.get(id) ?? []);
 }
 
 export function registeredMailIds(): readonly string[] {
@@ -123,6 +126,11 @@ export function renderMessage<I>(
   );
 
   const input = parse(mail.input, data, `${mail.id}.input`);
+  // The queue schema's own rule (`t.url`), so an unparseable url is refused here rather than
+  // delivered inline as `List-Unsubscribe: <not a url>` and refused by a worker when queued.
+  if (options.unsubscribeUrl !== undefined) {
+    parse(t.url, options.unsubscribeUrl, `${mail.id}.unsubscribeUrl`);
+  }
   const tz = options.tz ?? tryUseContext()?.tz ?? DEFAULT_TIME_ZONE;
   const rendered = renderMail(mail, input, {
     locale: options.locale,
@@ -150,6 +158,13 @@ export function renderMessage<I>(
   // Checked before the queue too, so the refusal lands on the `send()` call site that made it
   // rather than on a worker three retries later.
   assertHeaderSafe(message);
+  // The recipient rule, after the header gate so a line break keeps its own code: what the queue
+  // schema refuses is refused HERE, on every driver, rather than answered `queued: true` and then
+  // refused by the worker's parse — one rule on both paths (`s1-t4 #3`).
+  const replyTo = message.replyTo === undefined ? [] : [message.replyTo];
+  for (const address of [...envelopeRecipients(message), ...replyTo]) {
+    assertRecipientAddress('recipient', address);
+  }
   return message;
 }
 
@@ -167,21 +182,17 @@ export async function send<I>(
   // and the job never re-runs the hook. Not in `renderMessage`, which previews call.
   const message = await applyMailTransform(renderMessage(mail, data, options));
   const key = mailIdempotencyKey(message);
-  const queue = jobDriver();
 
-  if (options.sync === true || queue === undefined) {
+  if (options.sync === true || jobDriver() === undefined) {
     // The key is reported even inline, so a caller can dedupe its own retries either way.
     return { ...(await mailDriver().send(message)), idempotencyKey: key };
   }
 
-  const enqueued = await queue.enqueue({
-    name: sendMailJob.name,
-    queue: sendMailJob.queue,
-    input: message,
-    idempotencyKey: key,
-    maxAttempts: sendMailJob.retry.attempts,
-    onConflict: 'dedupe',
-  });
+  // Through the facade, never `queue.enqueue`: inside a transaction the row is STAGED on the
+  // caller's connection and published after COMMIT, so a handler that rolls back after sending
+  // mails nobody (`s1-con #3`). Outside one, the facade publishes straight to the same driver.
+  // The key is the handle's own `mailIdempotencyKey`, and the driver dedupes on it by default.
+  const enqueued = await jobsFacade().enqueue(sendMailJob, message);
 
   return {
     id: enqueued.id,

package/src/mime.ts

@@ -67,7 +67,7 @@ export function buildMimeMessage(message: MailMessage, options: MimeOptions): st
       // none for the addr-spec, and this package negotiates no SMTPUTF8 — so a UTF-8 mailbox would
       // go out as raw 8-bit octets in a header AND in the envelope beside it.
       if (mode === 'address' && hasNonAsciiAddrSpec(part))
-        throw headerInvalid(name, message.mailId);
+        throw headerInvalid(name, message.mailId, 'non-ascii');
     }
     headerLines.push(foldHeaderLine(name, parts.map((part) => encodeAs(mode, part)).join(', ')));
   };
@@ -79,9 +79,12 @@ export function buildMimeMessage(message: MailMessage, options: MimeOptions): st
   header('Date', rfc5322Date(options.date));
   header('Message-ID', options.messageId);
   header('MIME-Version', '1.0');
-  // RFC 8058 one-click unsubscribe and friends: computed once in driver.ts, emitted verbatim
-  // here so there is exactly one place that decides which of these headers a message gets.
-  for (const [name, value] of Object.entries(messageHeaders(message))) header(name, value);
+  // RFC 8058 one-click unsubscribe and friends: computed once in driver.ts so there is exactly one
+  // place that decides which of these headers a message gets. `Reply-To` is an ADDRESS and takes
+  // the address path — it went out verbatim, a non-ASCII display name as raw 8-bit octets.
+  for (const [name, value] of Object.entries(messageHeaders(message))) {
+    header(name, value, ADDRESS_HEADERS.has(name) ? 'address' : 'verbatim');
+  }
   header('Content-Type', `multipart/alternative; boundary="${options.boundary}"`);
 
   return `${headerLines.join(CRLF)}${CRLF}${CRLF}${buildBody(message, options.boundary)}`;
@@ -107,6 +110,9 @@ function bodyPart(contentType: string, text: string): string {
   );
 }
 
+/** The computed headers (`messageHeaders`) whose value is an address, not a 7-bit token. */
+const ADDRESS_HEADERS: ReadonlySet<string> = new Set(['Reply-To']);
+
 /**
  * How a header VALUE reaches the wire. `verbatim` is a value that is 7-bit by construction (a
  * date, a boundary, a message id); `value` is RFC 2047 over the whole string; `address` encodes
@@ -126,7 +132,7 @@ function encodeAs(mode: HeaderMode, value: string): string {
  * an 8-bit octet on a wire this package never negotiates SMTPUTF8 for, so it is the display name
  * that gets encoded — the addr-spec is copied through untouched, because a mailbox is the
  * server's to parse and an encoded word is not one. An address with no phrase, or an ASCII
- * phrase, comes back byte-identical.
+ * phrase with no special in it, comes back byte-identical; an ASCII phrase holding one is quoted.
  *
  * The MAILBOX is a different question and `hasNonAsciiAddrSpec` is where it is asked: RFC 2047
  * encoded words are legal in a phrase and nowhere else, so there is no encoding this function
@@ -136,8 +142,23 @@ export function encodeAddressPhrase(address: string): string {
   const match = ADDRESS_SPEC.exec(address);
   if (match === null) return address;
   const phrase = address.slice(0, match.index).trim();
-  if (phrase === '' || isPureAscii(phrase)) return address;
-  return `${encodeHeaderValue(phrase)} <${match[1] ?? ''}>`;
+  if (phrase === '') return address;
+  if (!isPureAscii(phrase)) return `${encodeHeaderValue(phrase)} <${match[1] ?? ''}>`;
+  if (!needsQuoting(phrase)) return address;
+  return `"${phrase.replace(/["\\]/g, (char) => `\\${char}`)}" <${match[1] ?? ''}>`;
+}
+
+/**
+ * RFC 5322 `specials` that end an atom, `.` aside (`obs-phrase` admits it, and `Jane Q. Doe` is
+ * every client's ordinary output). Unquoted, `Doe, Jane <jane@x.test>` is TWO list entries to the
+ * receiver — `Doe` and `Jane <jane@x.test>` — so the phrase is quoted rather than sent as written.
+ */
+const PHRASE_SPECIALS = /[(),:;<>@[\]\\"]/;
+
+/** A phrase that is already one whole quoted-string is the caller's own quoting, left alone. */
+function needsQuoting(phrase: string): boolean {
+  if (/^"(?:[^"\\]|\\.)*"$/.test(phrase)) return false;
+  return PHRASE_SPECIALS.test(phrase);
 }
 
 /**