@ultimat3/mail 23.0.0 → 25.0.0

package/src/delivery-event.ts

@@ -0,0 +1,103 @@
+// Single responsibility: the ONE shape a provider's delivery notification becomes, and the reads
+// both receivers share — the capped body, the JSON parse, the ISO instant. What a provider calls a
+// bounce or a complaint is translated in its own file; what the APP does with one (suppress the
+// address, flag the account) is the app's, and nothing here decides it.
+
+import { finiteCount, readWithinLimit } from '@ultimat3/core';
+import { isIsoDateTime } from '@ultimat3/schema';
+import { type DeliveryProvider, deliveryEventInvalid } from './delivery-event-errors';
+
+/** SNS caps a message at 256 KiB and JSON-escapes it once more inside its envelope. */
+export const DEFAULT_DELIVERY_BODY_LIMIT = 1_048_576;
+
+interface DeliveryEventBase {
+  readonly provider: DeliveryProvider;
+  /**
+   * The provider's id for the MESSAGE — `SendResult.id` from the driver that sent it (the SES
+   * `MessageId`, the Resend email id), so a notification joins the send it is about.
+   */
+  readonly messageId: string;
+  /** One recipient per event: a bounce naming three addresses is three events. */
+  readonly recipient: string;
+  /** When the provider says it happened — never when it reached this route. */
+  readonly at: Date;
+  /**
+   * The provider's id for the NOTIFICATION (SNS `MessageId`, `svix-id`), signed. With
+   * `recipient` it is the dedupe key: a provider redelivers, and a replay inside the window
+   * verifies again by design.
+   */
+  readonly eventId: string;
+  /** The verified notification as the provider sent it, parsed — every field this type drops. */
+  readonly raw: unknown;
+}
+
+export type DeliveryEvent =
+  | (DeliveryEventBase & { readonly kind: 'delivered' })
+  | (DeliveryEventBase & {
+      readonly kind: 'bounced';
+      /** `hard`: the address does not exist or refuses — stop sending. `soft`: it may clear. */
+      readonly bounce: 'hard' | 'soft';
+    })
+  | (DeliveryEventBase & { readonly kind: 'complained' })
+  | (DeliveryEventBase & { readonly kind: 'delayed' });
+
+export type DeliveryEventKind = DeliveryEvent['kind'];
+
+/** What a receiver answers. Every variant is a VERIFIED notification; a forgery is a throw. */
+export type DeliveryOutcome =
+  | { readonly type: 'events'; readonly events: readonly DeliveryEvent[] }
+  /** Authentic, of a type this normaliser does not model (`email.opened`, an SES `Send`). */
+  | { readonly type: 'ignored'; readonly eventType: string }
+  /**
+   * An SNS `SubscriptionConfirmation`. `confirmed` is true only when the receiver was built with
+   * `confirmSubscriptions: true` and the confirm request succeeded; otherwise visit `confirmUrl`.
+   */
+  | {
+      readonly type: 'subscription';
+      readonly topicArn: string;
+      readonly confirmUrl: string;
+      readonly confirmed: boolean;
+    };
+
+export interface DeliveryReceiver {
+  /** Verify, then normalise. Read the request once — its body is spent afterwards. */
+  receive(request: Request): Promise<DeliveryOutcome>;
+}
+
+const decoder = new TextDecoder('utf-8', { fatal: true });
+
+/** The body as text, through core's counting reader so an oversized one is never held whole. */
+export async function readDeliveryBody(
+  provider: DeliveryProvider,
+  request: Request,
+  maxBytes: number,
+): Promise<string> {
+  const read = await readWithinLimit(request.body, maxBytes);
+  if ('over' in read) throw deliveryEventInvalid(provider, 'too-large');
+  try {
+    return decoder.decode(read.bytes);
+  } catch {
+    throw deliveryEventInvalid(provider, 'not-utf8');
+  }
+}
+
+export function parseDeliveryJson(provider: DeliveryProvider, text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw deliveryEventInvalid(provider, 'not-json');
+  }
+}
+
+/** An ISO-8601 instant with its offset, or a refusal — `new Date('garbage')` is not one. */
+export function deliveryInstant(provider: DeliveryProvider, value: string): Date {
+  const at = isIsoDateTime(value) ? new Date(value) : undefined;
+  if (at === undefined || Number.isNaN(at.getTime())) {
+    throw deliveryEventInvalid(provider, 'timestamp');
+  }
+  return at;
+}
+
+export function resolveBodyLimit(subject: string, maxBytes: number | undefined): number {
+  return finiteCount(subject, 'maxBytes', maxBytes ?? DEFAULT_DELIVERY_BODY_LIMIT, 1);
+}

package/src/driver-env.ts

@@ -5,16 +5,46 @@
 // deploys to every environment.
 
 import { ConfigInvalidError, isLocal, resolveEnvironment } from '@ultimat3/core';
-import { createMemoryDriver, createUnconfiguredDriver, type MailDriver } from './driver';
-import { createResendDriver } from './driver-resend';
-import { createSmtpDriver } from './driver-smtp';
+import { type MailDriver, memoryMailDriver, unconfiguredMailDriver } from './driver';
+import { resendMailDriver } from './driver-resend';
+import { sesMailDriver } from './driver-ses';
+import { smtpMailDriver } from './driver-smtp';
+import { type RetainMimeOptions, resolveRetainMime } from './retain-mime';
 
 /**
  * The MAIL keys read here, and nothing else. Named once so docs and tests cannot drift from the
  * code. `ULTIMATE_ENV`/`NODE_ENV` are deliberately absent: which deploy this is belongs to core's
  * one resolver, and restating it as a mail key would make it two settings with one meaning.
  */
-export const MAIL_ENV_KEYS = ['SMTP_URL', 'RESEND_API_KEY', 'MAIL_FROM', 'MAIL_POOL_SIZE'] as const;
+export const MAIL_ENV_KEYS = [
+  'SMTP_URL',
+  'RESEND_API_KEY',
+  'MAIL_FROM',
+  'MAIL_POOL_SIZE',
+  'SES_REGION',
+  'SES_ACCESS_KEY_ID',
+  'SES_SECRET_ACCESS_KEY',
+  'SES_SESSION_TOKEN',
+  'SES_ENDPOINT',
+  'SES_CONFIGURATION_SET',
+] as const;
+
+/** The key that SELECTS each transport. More than one set at once is refused, never resolved. */
+const SELECTING_KEYS = ['SMTP_URL', 'RESEND_API_KEY', 'SES_REGION'] as const;
+
+/**
+ * What a boot passes that an environment cannot: a function. `retainMime` reaches the transports
+ * that build the MIME (SMTP, SES); Resend builds it on its own side, so asking for it there is
+ * refused rather than silently keeping nothing.
+ */
+export interface MailSelectOptions {
+  readonly retainMime?: RetainMimeOptions | undefined;
+  /**
+   * Where `retainMime` was written, named in a refusal so it points at the line to edit. Default
+   * `retainMime`; `@ultimat3/cli`'s boot passes `mail.retainMime`, the `app.config.ts` key.
+   */
+  readonly retainMimeKey?: string | undefined;
+}
 
 export type MailEnvironment = Readonly<Record<string, string | undefined>>;
 
@@ -40,7 +70,7 @@ function requireFrom(env: MailEnvironment, selectedBy: string): string {
   if (from === undefined) {
     throw new ConfigInvalidError({
       cause: `${selectedBy} selects a mail transport, but MAIL_FROM is unset — no envelope sender`,
-      fix: 'set MAIL_FROM="App <no-reply@yourdomain.test>" in .env.production',
+      fix: 'MAIL_FROM="App <no-reply@yourdomain.test>" — in .env.production',
       meta: { selectedBy, missing: 'MAIL_FROM' },
     });
   }
@@ -59,7 +89,7 @@ function poolSizeFrom(env: MailEnvironment): number | undefined {
   if (!Number.isInteger(parsed) || parsed < 1) {
     throw new ConfigInvalidError({
       cause: `MAIL_POOL_SIZE is "${raw}", which is not a whole number of connections >= 1`,
-      fix: 'set MAIL_POOL_SIZE=4 in .env.production, or unset it to keep the default',
+      fix: 'MAIL_POOL_SIZE=4 — in .env.production, or unset it to keep the default',
       meta: { MAIL_POOL_SIZE: raw },
     });
   }
@@ -79,47 +109,90 @@ function poolSizeFrom(env: MailEnvironment): number | undefined {
  * and no error anywhere to find it by. `isLocal` is core's one reader of that question, so mail
  * cannot disagree with storage about which deploy this is.
  */
-export function selectMailDriver(env: MailEnvironment): MailSelection {
-  const smtpUrl = nonEmpty(env['SMTP_URL']);
-  const resendKey = nonEmpty(env['RESEND_API_KEY']);
-
-  if (smtpUrl !== undefined && resendKey !== undefined) {
+export function selectMailDriver(
+  env: MailEnvironment,
+  options: MailSelectOptions = {},
+): MailSelection {
+  // The cap first, before any branch: only SMTP and SES build a retaining transport, so a cap
+  // above the ceiling booted on memory, unconfigured and Resend, and the same options refused the
+  // boot the day `SMTP_URL` was set. One check, `resolveRetainMime`, the transports' own.
+  resolveRetainMime('selectMailDriver', options.retainMime, options.retainMimeKey);
+  const selected = SELECTING_KEYS.filter((key) => nonEmpty(env[key]) !== undefined);
+  if (selected.length > 1) {
     throw new ConfigInvalidError({
-      cause: 'SMTP_URL and RESEND_API_KEY are both set — two transports claim the same mail',
+      cause: `${selected.join(' and ')} are ${selected.length === 2 ? 'both' : 'all'} set — ${selected.length} transports claim the same mail`,
       fix: 'unset one of them in .env.production: a process delivers through exactly one transport',
-      meta: { selected: ['SMTP_URL', 'RESEND_API_KEY'] },
+      meta: { selected },
     });
   }
 
+  const smtpUrl = nonEmpty(env['SMTP_URL']);
   if (smtpUrl !== undefined) {
     const poolSize = poolSizeFrom(env);
     return {
-      driver: createSmtpDriver({
+      driver: smtpMailDriver({
         url: smtpUrl,
         from: requireFrom(env, 'SMTP_URL'),
         ...(poolSize === undefined ? {} : { poolSize }),
+        retainMime: options.retainMime,
       }),
       detail: 'SMTP_URL',
     };
   }
 
+  const resendKey = nonEmpty(env['RESEND_API_KEY']);
   if (resendKey !== undefined) {
+    if (options.retainMime !== undefined) throw retainOnResend();
     return {
-      driver: createResendDriver({ apiKey: resendKey, from: requireFrom(env, 'RESEND_API_KEY') }),
+      driver: resendMailDriver({ apiKey: resendKey, from: requireFrom(env, 'RESEND_API_KEY') }),
       detail: 'RESEND_API_KEY',
     };
   }
 
+  const sesRegion = nonEmpty(env['SES_REGION']);
+  if (sesRegion !== undefined) {
+    return { driver: sesFrom(env, sesRegion, options), detail: 'SES_REGION' };
+  }
+
   if (isLocal({ env })) {
     return {
-      driver: createMemoryDriver(),
-      detail: 'caught in memory — set SMTP_URL or RESEND_API_KEY to deliver',
+      driver: memoryMailDriver(),
+      detail: 'caught in memory — set SMTP_URL, RESEND_API_KEY or SES_REGION to deliver',
     };
   }
 
   const environment = resolveEnvironment({ env });
   return {
-    driver: createUnconfiguredDriver(environment),
-    detail: `no transport configured for ${environment} — set SMTP_URL or RESEND_API_KEY`,
+    driver: unconfiguredMailDriver(environment),
+    detail: `no transport configured for ${environment} — set SMTP_URL, RESEND_API_KEY or SES_REGION`,
   };
 }
+
+/** The credential pair is required by `sesMailDriver`, which names whichever half is missing. */
+function sesFrom(env: MailEnvironment, region: string, options: MailSelectOptions): MailDriver {
+  const sessionToken = nonEmpty(env['SES_SESSION_TOKEN']);
+  const endpoint = nonEmpty(env['SES_ENDPOINT']);
+  const configurationSet = nonEmpty(env['SES_CONFIGURATION_SET']);
+  return sesMailDriver({
+    region,
+    credentials: {
+      accessKeyId: nonEmpty(env['SES_ACCESS_KEY_ID']) ?? '',
+      secretAccessKey: nonEmpty(env['SES_SECRET_ACCESS_KEY']) ?? '',
+      ...(sessionToken === undefined ? {} : { sessionToken }),
+    },
+    from: requireFrom(env, 'SES_REGION'),
+    ...(endpoint === undefined ? {} : { endpoint }),
+    ...(configurationSet === undefined ? {} : { configurationSet }),
+    retainMime: options.retainMime,
+  });
+}
+
+function retainOnResend(): ConfigInvalidError {
+  return new ConfigInvalidError({
+    cause:
+      'retainMime was asked for, and RESEND_API_KEY selects resend — which builds the MIME on ' +
+      "Resend's side, so this process never holds the bytes it would keep",
+    fix: 'selectMailDriver(env) — drop retainMime for resend, or select SMTP_URL or SES_REGION instead',
+    meta: { selected: 'RESEND_API_KEY' },
+  });
+}

package/src/driver-resend.ts

@@ -127,7 +127,7 @@ function bodyFor(message: MailMessage, from: string): ResendRequestBody {
   };
 }
 
-export function createResendDriver(options: ResendDriverOptions): MailDriver {
+export function resendMailDriver(options: ResendDriverOptions): MailDriver {
   const apiKey = requireApiKey(options.apiKey);
   const from = requireFrom(options.from);
   const baseUrl = options.baseUrl ?? RESEND_BASE_URL;
@@ -137,7 +137,7 @@ export function createResendDriver(options: ResendDriverOptions): MailDriver {
   // the queue retried it to the dead-letter table for a value no network could change. `0` is not
   // "no deadline" either: the signal aborts on the next tick, before a byte leaves the host.
   const timeoutMs = finiteCount(
-    'createResendDriver',
+    'resendMailDriver',
     'timeoutMs',
     options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
     1,

package/src/driver-ses.ts

@@ -0,0 +1,205 @@
+// Single responsibility: the Amazon SES transport. One SES v2 `SendEmail` per message, the body
+// the raw MIME `mime.ts` builds, signed with core's one SigV4 signer and sent over `fetch` — no
+// SDK. Construction refuses a missing credential, an unusable region or a bad endpoint, so a
+// misconfiguration never waits for the first send.
+
+import {
+  type AwsCredentials,
+  type Clock,
+  ConfigInvalidError,
+  EnvMissingError,
+  finiteCount,
+  isUltimateError,
+  nanoid,
+  renderFixShellArg,
+  renderThrowable,
+  signAwsRequest,
+  systemClock,
+} from '@ultimat3/core';
+import { base64Utf8 } from './base64';
+import type { MailDriver, MailMessage, SendResult } from './driver';
+import { resultFor } from './driver';
+import type { MailFetch } from './driver-resend';
+import { sendFailed } from './errors';
+import { mailMessageIdToken } from './idempotency';
+import { addressDomain, buildMimeMessage } from './mime';
+import { type RetainMimeOptions, resolveRetainMime, withRetainedMime } from './retain-mime';
+import { sesFailure } from './ses-failure';
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+const SEND_PATH = '/v2/email/outbound-emails';
+/** `us-east-1`, `eu-west-2`, `us-gov-west-1` — what AWS calls a region, and nothing a URL could hide in. */
+const REGION = /^[a-z]{2}(-[a-z]+)+-\d{1,2}$/;
+
+export interface SesDriverOptions {
+  /** Read from `SES_REGION`. The endpoint is `https://email.<region>.amazonaws.com`. */
+  readonly region: string;
+  /** Read from `SES_ACCESS_KEY_ID` / `SES_SECRET_ACCESS_KEY` (/ `SES_SESSION_TOKEN`). */
+  readonly credentials: AwsCredentials;
+  /** `Postly <no-reply@postly.test>`. Must be an identity verified in this region. */
+  readonly from: string;
+  /** A VPC endpoint or a local stand-in. Defaults to the region's public endpoint. */
+  readonly endpoint?: string | undefined;
+  /** `ConfigurationSetName` — the set whose event destination publishes Bounce/Complaint/Delivery. */
+  readonly configurationSet?: string | undefined;
+  readonly timeoutMs?: number | undefined;
+  readonly clock?: Clock | undefined;
+  /** Keep the exact MIME of every accepted send on `SendResult.mime` and hand it to `onRetained`. */
+  readonly retainMime?: RetainMimeOptions | undefined;
+  /** Injected in tests; production uses the global. */
+  readonly fetch?: MailFetch | undefined;
+}
+
+export const sesEndpoint = (region: string): string => `https://email.${region}.amazonaws.com`;
+
+function requireRegion(region: string): string {
+  if (REGION.test(region)) return region;
+  throw new ConfigInvalidError({
+    cause:
+      'SES_REGION is not an AWS region name, so no SES endpoint or signing scope exists for it',
+    fix: 'SES_REGION=us-east-1 — the region your sending identity is verified in',
+    meta: { key: 'SES_REGION' },
+  });
+}
+
+function requireCredentials(credentials: AwsCredentials): AwsCredentials {
+  const missing = [
+    ...(credentials.accessKeyId.trim() === '' ? ['SES_ACCESS_KEY_ID'] : []),
+    ...(credentials.secretAccessKey.trim() === '' ? ['SES_SECRET_ACCESS_KEY'] : []),
+  ];
+  if (missing.length === 0) return credentials;
+  throw new EnvMissingError({
+    cause: `${missing.join(' and ')} ${missing.length === 1 ? 'is' : 'are'} not set, so the ses driver cannot sign a request`,
+    fix: "SES_ACCESS_KEY_ID=<key id> SES_SECRET_ACCESS_KEY=<secret> — in .env or the container's secret store, then re-run",
+    meta: { missing },
+  });
+}
+
+function requireEndpoint(endpoint: string): string {
+  const url = URL.parse(endpoint);
+  if (
+    url !== null &&
+    (url.protocol === 'https:' || url.protocol === 'http:') &&
+    url.search === ''
+  ) {
+    return url.origin;
+  }
+  throw new ConfigInvalidError({
+    cause: 'SES_ENDPOINT is not an http(s) origin, so no SendEmail URL can be built from it',
+    fix: 'SES_ENDPOINT=https://email.us-east-1.amazonaws.com — or unset it for the region default',
+    meta: { key: 'SES_ENDPOINT' },
+  });
+}
+
+function requireFrom(from: string): string {
+  if (from.trim() !== '') return from;
+  throw new ConfigInvalidError({
+    cause: 'the ses driver was configured without a from address',
+    fix: 'aws sesv2 list-email-identities — then set MAIL_FROM to one verified in this region',
+  });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * `Destination` is the envelope, and it is sent even though the raw message holds `To:` and `Cc:`
+ * — `Bcc` is never a header (`mime.ts`), so without it the blind list would receive nothing.
+ */
+function bodyFor(message: MailMessage, from: string, raw: string, set: string | undefined): string {
+  return JSON.stringify({
+    FromEmailAddress: from,
+    Destination: {
+      ToAddresses: message.to,
+      ...(message.cc === undefined ? {} : { CcAddresses: message.cc }),
+      ...(message.bcc === undefined ? {} : { BccAddresses: message.bcc }),
+    },
+    Content: { Raw: { Data: base64Utf8(raw) } },
+    ...(set === undefined ? {} : { ConfigurationSetName: set }),
+  });
+}
+
+export function sesMailDriver(options: SesDriverOptions): MailDriver {
+  const region = requireRegion(options.region);
+  const credentials = requireCredentials(options.credentials);
+  const from = requireFrom(options.from);
+  const origin = requireEndpoint(options.endpoint ?? sesEndpoint(region));
+  const timeoutMs = finiteCount(
+    'sesMailDriver',
+    'timeoutMs',
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    1,
+  );
+  const retain = resolveRetainMime('sesMailDriver', options.retainMime);
+  const clock = options.clock ?? systemClock;
+  const doFetch: MailFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+
+  return { name: 'ses', send };
+
+  async function send(message: MailMessage): Promise<SendResult> {
+    // Content-derived like SMTP's, so every attempt presents one id. SES rewrites `Message-ID` to
+    // its own on the way out, and SES has no idempotency header: a retry after a timeout that SES
+    // had in fact accepted is a second email. That is SMTP's gap, not Resend's guarantee.
+    const raw = buildMimeMessage(message, {
+      from,
+      messageId: `<${message.mailId}.${mailMessageIdToken(message)}@${addressDomain(from)}>`,
+      date: clock.now(),
+      boundary: `x-ultimate-${nanoid(20)}`,
+    });
+    const body = bodyFor(message, from, raw, options.configurationSet);
+
+    let response: Response;
+    try {
+      const signed = await signAwsRequest({
+        method: 'POST',
+        url: `${origin}${SEND_PATH}`,
+        headers: { 'content-type': 'application/json' },
+        payload: { body },
+        credentials,
+        region,
+        service: 'ses',
+        clock,
+      });
+      response = await doFetch(signed.url, {
+        method: 'POST',
+        headers: signed.headers,
+        body,
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch (error) {
+      // The signer's own refusals are coded and say which input to fix; only the network is left.
+      if (isUltimateError(error)) throw error;
+      throw sendFailed({
+        driver: 'ses',
+        stage: 'request',
+        detail: `${renderThrowable(error)} — nothing left this host for ${origin}${SEND_PATH} (egress, DNS or TLS)`,
+        retryable: true,
+        fix: `curl -sS -m 5 -o /dev/null ${renderFixShellArg(origin, '<SES endpoint>')}/`,
+      });
+    }
+
+    if (!response.ok) {
+      const failure = await sesFailure(response, region);
+      throw sendFailed({
+        driver: 'ses',
+        stage: 'request',
+        detail: failure.detail,
+        status: response.status,
+        retryable: failure.retryable,
+        fix: failure.fix,
+      });
+    }
+
+    const parsed: unknown = await response.json().catch(() => undefined);
+    const id = isRecord(parsed) ? parsed['MessageId'] : undefined;
+    // A 2xx is acceptance. The id is what SNS notifications name the message by, so a local one
+    // is a correlation lost — but never a reason to report an accepted send as failed.
+    const result = resultFor(
+      'ses',
+      message,
+      typeof id === 'string' && id !== '' ? id : `ses_${nanoid(12)}`,
+    );
+    return withRetainedMime(retain, result, message.mailId, raw);
+  }
+}

package/src/driver-smtp.ts

@@ -8,6 +8,7 @@ import {
   finiteCount,
   isUltimateError,
   nanoid,
+  renderFixShellArg,
   renderThrowable,
   systemClock,
 } from '@ultimat3/core';
@@ -16,6 +17,7 @@ import { envelopeRecipients, type MailDriver, type MailMessage, resultFor } from
 import { sendFailed } from './errors';
 import { mailMessageIdToken } from './idempotency';
 import { addressDomain, buildMimeMessage } from './mime';
+import { type RetainMimeOptions, resolveRetainMime, withRetainedMime } from './retain-mime';
 import {
   type SmtpConnector,
   type SmtpSessionOptions,
@@ -43,6 +45,8 @@ export interface SmtpDriverOptions {
   /** Speak to a server that offers no STARTTLS. Off by default: mail and password in the clear. */
   readonly allowInsecure?: boolean | undefined;
   readonly clock?: Clock | undefined;
+  /** Keep the exact MIME of every accepted send on `SendResult.mime` and hand it to `onRetained`. */
+  readonly retainMime?: RetainMimeOptions | undefined;
   /** Injected in tests; production dials with `Bun.connect`. */
   readonly connect?: SmtpConnector | undefined;
 }
@@ -84,11 +88,29 @@ function parseSmtpUrl(raw: string): SmtpUrl {
     port: url.port === '' ? (tls ? IMPLICIT_TLS_PORT : SUBMISSION_PORT) : Number(url.port),
     tls,
     // Credentials are percent-encoded in a URL; a password with `@` or `/` is otherwise unusable.
-    ...(url.username === '' ? {} : { user: decodeURIComponent(url.username) }),
-    ...(url.password === '' ? {} : { password: decodeURIComponent(url.password) }),
+    ...(url.username === '' ? {} : { user: decodedCredential('user', url.username) }),
+    ...(url.password === '' ? {} : { password: decodedCredential('password', url.password) }),
   };
 }
 
+/**
+ * `decodeURIComponent` throws a bare `URIError` for a `%` that starts no escape, which escaped
+ * `smtpMailDriver` as the one SMTP_URL mistake that was not a config error. The value is a
+ * credential, so neither the cause nor the fix ever carries it.
+ */
+function decodedCredential(part: 'user' | 'password', raw: string): string {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    throw new ConfigInvalidError({
+      cause: `the SMTP_URL ${part} holds a "%" that starts no percent-escape, so it cannot be decoded`,
+      // `prompt`, so the credential reaches neither shell history nor this message.
+      fix: `percent-encode the ${part} and put the output in SMTP_URL: bun -e 'console.log(encodeURIComponent(prompt("${renderFixShellArg(part, 'value')}:") ?? ""))'`,
+      meta: { part },
+    });
+  }
+}
+
 /**
  * `poolSize: 0` is the one config mistake this driver could not report: the limiter would park
  * every send on a slot that is never handed out, with no deadline on the wait, so the job would
@@ -130,7 +152,7 @@ function createLimiter(size: number): (run: () => Promise<SendResult>) => Promis
   };
 }
 
-export function createSmtpDriver(options: SmtpDriverOptions): MailDriver {
+export function smtpMailDriver(options: SmtpDriverOptions): MailDriver {
   const target = parseSmtpUrl(options.url);
   if (options.from.trim() === '') {
     throw new ConfigInvalidError({
@@ -145,12 +167,13 @@ export function createSmtpDriver(options: SmtpDriverOptions): MailDriver {
   // non-finite deadline does not disable itself, it fires on the next tick and every send fails
   // "the server sent nothing for NaNms". `0` is the same failure spelled deliberately.
   const timeoutMs = finiteCount(
-    'createSmtpDriver',
+    'smtpMailDriver',
     'timeoutMs',
     options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
     1,
   );
   const limit = createLimiter(resolvePoolSize(options.poolSize));
+  const retain = resolveRetainMime('smtpMailDriver', options.retainMime);
   const session: SmtpSessionOptions = {
     clientName: options.clientName ?? addressDomain(options.from),
     secure: target.tls,
@@ -205,7 +228,6 @@ export function createSmtpDriver(options: SmtpDriverOptions): MailDriver {
         { from: options.from, recipients: envelopeRecipients(message), data },
         session,
       );
-      return resultFor('smtp', message, messageId);
     } catch (error) {
       // A framework error already names its stage; anything else (a socket reset mid-DATA) would
       // otherwise escape as a bare Error and lose the code the queue's dead-letter view reads.
@@ -220,6 +242,9 @@ export function createSmtpDriver(options: SmtpDriverOptions): MailDriver {
     } finally {
       stream.close();
     }
+    // Past the try on purpose: the server took the message, so nothing from here on may be
+    // reported as a send failure — a retry of an accepted send is a second email.
+    return withRetainedMime(retain, resultFor('smtp', message, messageId), message.mailId, data);
   }
 }