@hogsend/engine 0.10.0 → 0.12.0

package/src/lib/create-admin.ts

@@ -0,0 +1,104 @@
+import type { Auth } from "./auth.js";
+
+/**
+ * Shared admin-minting primitive used by BOTH the CLI's `admin create` and the
+ * engine's env bootstrap. Mints a credential admin via better-auth's
+ * INTERNAL ADAPTER (scrypt-identical to the running app) rather than the public
+ * sign-up endpoint — which is now blocked by `disableSignUp` (see lib/auth.ts).
+ *
+ * Why the internal adapter (not `auth.api.signUpEmail`): in better-auth 1.6.11
+ * the `disableSignUp` check lives INSIDE the sign-up endpoint handler, and
+ * `auth.api.signUpEmail` dispatches through that SAME handler — so with sign-up
+ * disabled it throws `EMAIL_PASSWORD_SIGN_UP_DISABLED` for the in-process API
+ * too. The internal adapter is NOT subject to that guard. This mirrors exactly
+ * what admin-recovery's `reset()` already does for its no-credential branch
+ * (`ctx.password.hash` + `ctx.internalAdapter.createAccount({ providerId:
+ * "credential" })`).
+ *
+ * Security invariants (acceptance gates, not preferences):
+ *  - The password is hashed via `ctx.password.hash` (scrypt, identical to the
+ *    app). There is NO raw SQL password write.
+ *  - The password is never logged and never returned in any result object.
+ *  - `emailVerified: true` because this is an operator-minted admin (CLI or
+ *    boot env), not a self-service signup.
+ *
+ * Lives in `lib/` (reachable via the `@hogsend/engine/create-admin` subpath)
+ * with a module graph that touches ONLY better-auth — it never pulls `env.ts`,
+ * Hatchet, or Resend — so the CLI can import it the same way it imports
+ * `createAuth` from `@hogsend/engine/auth`.
+ */
+
+/** A single admin row, no secrets. Shared with the CLI's `AdminSummary`. */
+export interface CreatedAdmin {
+  id: string;
+  email: string;
+  name: string;
+  createdAt: string;
+}
+
+/** Thrown when an admin with the given email already exists. */
+export class AdminAlreadyExistsError extends Error {
+  constructor(public readonly email: string) {
+    super(
+      `An admin with email "${email}" already exists. ` +
+        "Use `hogsend studio admin reset` to set a new password.",
+    );
+    this.name = "AdminAlreadyExistsError";
+  }
+}
+
+/**
+ * Create a credential admin user against a built better-auth instance. Throws
+ * {@link AdminAlreadyExistsError} if the email already exists (so callers can
+ * point the operator at `reset`). The unique constraint on `user.email` is the
+ * backstop: a concurrent racer that slips past the pre-check throws on
+ * `createUser` — callers that need idempotency should catch that.
+ */
+export async function createAdminUser(opts: {
+  auth: Auth;
+  email: string;
+  name?: string;
+  password: string;
+}): Promise<CreatedAdmin> {
+  const { auth, email, password } = opts;
+  const displayName = opts.name ?? email.split("@")[0] ?? email;
+
+  const ctx = await auth.$context;
+
+  // Pre-check for a clear error (better-auth lowercases on lookup + create).
+  const existing = await ctx.internalAdapter.findUserByEmail(email);
+  if (existing) {
+    throw new AdminAlreadyExistsError(email);
+  }
+
+  // scrypt hash — identical to the running app (admin-recovery.reset uses the
+  // same call). NO raw SQL password write.
+  const hashed = await ctx.password.hash(password);
+
+  // `createUser` returns the bare user row (createWithHooks → the created user),
+  // NOT `{ user }` — verified against better-auth@1.6.11 internal-adapter.mjs:75.
+  const created = await ctx.internalAdapter.createUser({
+    email,
+    name: displayName,
+    emailVerified: true,
+  });
+
+  await ctx.internalAdapter.createAccount({
+    userId: created.id,
+    providerId: "credential",
+    accountId: created.id,
+    password: hashed,
+  });
+
+  const createdAt =
+    created.createdAt instanceof Date
+      ? created.createdAt.toISOString()
+      : String(created.createdAt ?? new Date().toISOString());
+
+  return {
+    id: created.id,
+    email: created.email,
+    name: created.name,
+    createdAt,
+  };
+}

package/src/lib/domain-status.ts

@@ -0,0 +1,327 @@
+import type { DomainStatus, EmailProvider } from "@hogsend/core";
+import type { env as envSchema } from "../env.js";
+import type { Logger } from "./logger.js";
+
+/**
+ * Per-send test-mode snapshot (PROJECT_SPEC pinned shape).
+ *
+ * F1 ships the FULL shape STUBBED INACTIVE — `testModeCached()` and the
+ * `testMode` block of `getStatus()` always return
+ * `{ active: false, reason: null, redirectTo: null, fromOverride: null }`.
+ * F3 test-mode-sends replaces this stub with the real env-flag +
+ * domain-unverified logic; every surface that renders the block (admin route,
+ * CLI, Studio) lights up with zero further changes.
+ */
+export interface TestModeState {
+  active: boolean;
+  reason: "env_flag" | "domain_unverified" | null;
+  /** HOGSEND_TEST_EMAIL ?? STUDIO_ADMIN_EMAIL ?? null (F3). */
+  redirectTo: string | null;
+  /** "onboarding@resend.dev" when providerId==="resend" && active (F3); else null. */
+  fromOverride: string | null;
+}
+
+/**
+ * The engine-level domain snapshot every surface consumes: the admin route
+ * (`GET /v1/admin/domain`), the CLI (`hogsend domain status`), Studio's Setup
+ * view, and (cached, F3) the mailer's test-mode check.
+ */
+export interface EngineDomainStatus {
+  /**
+   * EMAIL_DOMAIN ?? host part of EMAIL_FROM (?? RESEND_FROM_EMAIL); `null`
+   * when underivable.
+   */
+  domain: string | null;
+  providerId: string;
+  /** `!!provider.domains` — presence of the capability is the gate. */
+  supported: boolean;
+  /** `null` when `!supported || !domain` (the provider is never called then). */
+  status: DomainStatus | null;
+  testMode: TestModeState;
+}
+
+/**
+ * Cached domain-status service. The per-send safety contract:
+ * `isVerifiedCached()`/`testModeCached()` are SYNC and cache-only (never await
+ * a provider call, never throw), and `refreshIfStale()` is fire-and-forget —
+ * so the mailer's hot path adds zero provider latency.
+ */
+export interface DomainStatusService {
+  /** `refresh: true` bypasses + busts the cache (admin `?refresh=true`, CLI `domain check`). */
+  getStatus(opts?: { refresh?: boolean }): Promise<EngineDomainStatus>;
+  /**
+   * Cache-only, NEVER awaits a provider call, never throws. FAIL-OPEN: no
+   * cache entry / unknown ⇒ `true`, so a provider outage can never silently
+   * redirect production mail.
+   */
+  isVerifiedCached(): boolean;
+  /** Sync snapshot for the per-send path (mailer). Cache-only. */
+  testModeCached(): TestModeState;
+  /**
+   * Fire-and-forget refresh when the cache is stale; called by the mailer per
+   * send and once at boot. Cheap no-op when fresh; concurrent refreshes are
+   * deduped; errors are swallowed + `logger.warn`ed.
+   */
+  refreshIfStale(): void;
+}
+
+/** TTL once the domain is verified — re-checks are cheap insurance only. */
+const VERIFIED_TTL_MS = 10 * 60 * 1000;
+/** TTL while unverified/failed/unknown — keeps test-mode auto-exit ≤60 s. */
+const UNVERIFIED_TTL_MS = 60 * 1000;
+
+/** Extract the host part of an email address ("hello@x.com" → "x.com"). */
+function hostPartOf(email: string | undefined): string | null {
+  if (!email) return null;
+  const at = email.lastIndexOf("@");
+  if (at === -1 || at === email.length - 1) return null;
+  return email.slice(at + 1).toLowerCase();
+}
+
+/** The Resend unverified-domain from-address fallback (so a redirected mail
+ * still delivers while the real sending domain isn't verified yet). */
+const RESEND_UNVERIFIED_FROM = "onboarding@resend.dev";
+
+/** Inputs to the pure test-mode resolver — single-object-in/result-object-out. */
+interface ResolveTestModeDeps {
+  /** env.HOGSEND_TEST_MODE. */
+  mode: "auto" | "true" | "false";
+  /**
+   * Whether the sending domain is verified per the CACHE. FAIL-OPEN: a cache
+   * miss / provider outage / `!supported` / no domain resolves to `true`
+   * (verified assumed), so a provider outage can never silently redirect prod
+   * mail (inherits {@link DomainStatusService.isVerifiedCached}).
+   */
+  verifiedCached: boolean;
+  /**
+   * Whether `auto` is allowed to ARM at all. `auto` only redirects when an
+   * EMAIL_DOMAIN is explicitly configured AND the provider supports domains —
+   * a bare deploy (no domain / no capability) keeps today's LIVE behavior, so
+   * existing users' sends are never silently redirected.
+   */
+  autoArmable: boolean;
+  providerId: string;
+  /** env.HOGSEND_TEST_EMAIL. */
+  testEmail?: string;
+  /** env.STUDIO_ADMIN_EMAIL (the fallback redirect target). */
+  adminEmail?: string;
+}
+
+/**
+ * Pure resolver for the {@link TestModeState} (PROJECT_SPEC §b, frozen rules):
+ * - `active` = `mode === "true"` OR (`mode === "auto"` AND `autoArmable` AND
+ *   `!verifiedCached`). `mode === "false"` ⇒ never active.
+ * - `reason` = `"env_flag"` when forced by `mode === "true"`, else
+ *   `"domain_unverified"` when auto-activated, else `null`.
+ * - `redirectTo` = `testEmail ?? adminEmail ?? null`.
+ * - `fromOverride` = `onboarding@resend.dev` iff `active && providerId === "resend"`,
+ *   else `null` (Postmark et al. get a provider-neutral redirect, no from-override).
+ */
+function resolveTestMode(deps: ResolveTestModeDeps): TestModeState {
+  const {
+    mode,
+    verifiedCached,
+    autoArmable,
+    providerId,
+    testEmail,
+    adminEmail,
+  } = deps;
+
+  const forced = mode === "true";
+  const autoActive = mode === "auto" && autoArmable && !verifiedCached;
+  const active = forced || autoActive;
+
+  const reason: TestModeState["reason"] = forced
+    ? "env_flag"
+    : autoActive
+      ? "domain_unverified"
+      : null;
+
+  return {
+    active,
+    reason,
+    redirectTo: active ? (testEmail ?? adminEmail ?? null) : null,
+    fromOverride:
+      active && providerId === "resend" ? RESEND_UNVERIFIED_FROM : null,
+  };
+}
+
+/**
+ * Build the cached {@link DomainStatusService} for the active email provider.
+ * In-memory cache ONLY (one process = one cache; the API and worker each keep
+ * their own) — no Redis dependency.
+ */
+export function createDomainStatusService(deps: {
+  provider: EmailProvider;
+  env: typeof envSchema;
+  logger: Logger;
+}): DomainStatusService {
+  const { provider, env, logger } = deps;
+
+  const providerId = provider.meta?.id ?? "resend";
+  const supported = Boolean(provider.domains);
+  const domain =
+    env.EMAIL_DOMAIN ??
+    hostPartOf(env.EMAIL_FROM) ??
+    hostPartOf(env.RESEND_FROM_EMAIL);
+
+  // `auto` only ARMS when an EMAIL_DOMAIN is explicitly configured AND the
+  // provider has the domains capability. A deploy with no EMAIL_DOMAIN or no
+  // capability keeps today's LIVE behavior under `auto` — this is the critical
+  // back-compat guard, NOT to be broadened.
+  const autoArmable = supported && Boolean(env.EMAIL_DOMAIN);
+  const mode = env.HOGSEND_TEST_MODE;
+
+  let cache: { snapshot: EngineDomainStatus; fetchedAt: number } | null = null;
+  let inflight: Promise<EngineDomainStatus> | null = null;
+
+  const isFresh = (): boolean => {
+    if (!cache) return false;
+    const ttl =
+      cache.snapshot.status?.state === "verified"
+        ? VERIFIED_TTL_MS
+        : UNVERIFIED_TTL_MS;
+    return Date.now() - cache.fetchedAt < ttl;
+  };
+
+  // FAIL-OPEN verified check against the live cache (shared by the resolver and
+  // the public `isVerifiedCached`): no cache entry, or nothing to verify
+  // (unsupported provider / underivable domain), ⇒ verified-assumed.
+  const verifiedCachedNow = (): boolean => {
+    if (!cache || cache.snapshot.status === null) return true;
+    return cache.snapshot.status.state === "verified";
+  };
+
+  /** Compute the CURRENT live test-mode snapshot off the cache + env. Pure +
+   * synchronous; never throws (fail-open inherits from `verifiedCachedNow`). */
+  const computeTestMode = (): TestModeState =>
+    resolveTestMode({
+      mode,
+      verifiedCached: verifiedCachedNow(),
+      autoArmable,
+      providerId,
+      testEmail: env.HOGSEND_TEST_EMAIL,
+      adminEmail: env.STUDIO_ADMIN_EMAIL,
+    });
+
+  // Previous-active flag drives one transition log per flip. Seeded `false` so
+  // the FIRST resolution that activates test mode logs the entering banner once
+  // (the boot warm-up refresh IS the banner — no separate boot code path).
+  let previousActive = false;
+
+  /** Log the entering/exiting transition exactly once per flip of `active`. */
+  const logTransition = (testMode: TestModeState): void => {
+    if (testMode.active === previousActive) return;
+    if (testMode.active) {
+      logger.warn(
+        "test mode ACTIVE — domain unverified, redirecting all sends",
+        { redirectTo: testMode.redirectTo, reason: testMode.reason },
+      );
+    } else {
+      logger.info("test mode exited — domain verified, sends are LIVE", {
+        domain,
+      });
+    }
+    previousActive = testMode.active;
+  };
+
+  /**
+   * Refill the cache snapshot with the resolved `status`, then compute the live
+   * `testMode` off the JUST-written cache and fire the transition log on a flip.
+   * Test mode is computed last so it reads the fresh verification state.
+   */
+  const commitSnapshot = (status: DomainStatus | null): EngineDomainStatus => {
+    // Seed the cache with a placeholder testMode so `computeTestMode` reads the
+    // fresh `status`, then overwrite the block with the resolved state.
+    const snapshot: EngineDomainStatus = {
+      domain,
+      providerId,
+      supported,
+      status,
+      testMode: {
+        active: false,
+        reason: null,
+        redirectTo: null,
+        fromOverride: null,
+      },
+    };
+    cache = { snapshot, fetchedAt: Date.now() };
+    const testMode = computeTestMode();
+    snapshot.testMode = testMode;
+    logTransition(testMode);
+    return snapshot;
+  };
+
+  /** Always queries the provider (when supported) and refills the cache. */
+  const fetchSnapshot = async (): Promise<EngineDomainStatus> => {
+    // No capability / no derivable domain: resolve instantly, NEVER call the
+    // provider. status stays null per the pinned EngineDomainStatus contract.
+    if (!supported || !domain) {
+      return commitSnapshot(null);
+    }
+
+    // biome-ignore lint/style/noNonNullAssertion: `supported` guarantees it.
+    const capability = provider.domains!;
+    const providerStatus = await capability.get(domain);
+    return commitSnapshot(
+      // Provider doesn't know the domain yet → an explicit not_found status
+      // (the Studio Setup view keys its add-domain form off this).
+      providerStatus ?? {
+        domain,
+        state: "not_found",
+        records: [],
+        providerId,
+        checkedAt: new Date().toISOString(),
+      },
+    );
+  };
+
+  /** Deduped fetch: concurrent callers share one in-flight provider call. */
+  const fetchDeduped = (): Promise<EngineDomainStatus> => {
+    if (!inflight) {
+      inflight = fetchSnapshot().finally(() => {
+        inflight = null;
+      });
+    }
+    return inflight;
+  };
+
+  return {
+    async getStatus(opts?: { refresh?: boolean }): Promise<EngineDomainStatus> {
+      if (opts?.refresh) {
+        // Bypass + bust: drop the cache so a failed refresh can't leave a
+        // stale "fresh" entry, then force a provider round-trip.
+        cache = null;
+        return fetchDeduped();
+      }
+      if (isFresh() && cache) return cache.snapshot;
+      return fetchDeduped();
+    },
+
+    isVerifiedCached(): boolean {
+      // FAIL-OPEN: no cache entry, or nothing to verify (unsupported provider /
+      // underivable domain) ⇒ treat as verified so a provider outage or a bare
+      // deploy can never silently redirect production mail.
+      return verifiedCachedNow();
+    },
+
+    testModeCached(): TestModeState {
+      // Sync, cache-only, never throws. Recomputed off the CURRENT cache so the
+      // per-send path always sees the freshest verification state without
+      // awaiting (env-flag mode resolves even with a cold cache; auto fails open
+      // to LIVE while the cache is empty/unknown).
+      return computeTestMode();
+    },
+
+    refreshIfStale(): void {
+      if (isFresh()) return;
+      void fetchDeduped().catch((error: unknown) => {
+        logger.warn("domain-status refresh failed", {
+          domain,
+          providerId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      });
+    },
+  };
+}

package/src/lib/email-providers-from-env.ts

@@ -27,6 +27,7 @@ type CreatePostmarkProvider = (cfg: {
   serverToken: string;
   messageStream?: string;
   webhookBasicAuth?: { user: string; pass: string };
+  accountToken?: string;
 }) => EmailProvider;
 
 const POSTMARK_PACKAGE = ["@hogsend", "plugin-postmark"].join("/");
@@ -78,6 +79,10 @@ export function emailProvidersFromEnv(env: typeof envSchema): EmailProvider[] {
         ...(env.POSTMARK_MESSAGE_STREAM
           ? { messageStream: env.POSTMARK_MESSAGE_STREAM }
           : {}),
+        // Account token unlocks the Domains API capability (optional).
+        ...(env.POSTMARK_ACCOUNT_TOKEN
+          ? { accountToken: env.POSTMARK_ACCOUNT_TOKEN }
+          : {}),
         ...(env.POSTMARK_WEBHOOK_USER && env.POSTMARK_WEBHOOK_PASS
           ? {
               webhookBasicAuth: {

package/src/lib/email-service-types.ts

@@ -73,8 +73,14 @@ export interface TrackedSendResult {
    */
   resendId: string;
   status: "sent" | "suppressed" | "unsubscribed" | "skipped";
-  /** Present only when `status === "skipped"` by the frequency cap. */
-  reason?: "frequency_capped";
+  /**
+   * Present only when `status === "skipped"`:
+   * - `"frequency_capped"` — the per-recipient frequency cap was hit.
+   * - `"test_mode_blocked"` — test mode was active but no redirect address
+   *   resolved (no `HOGSEND_TEST_EMAIL` / `STUDIO_ADMIN_EMAIL`), so the send was
+   *   blocked rather than delivered to the real recipient.
+   */
+  reason?: "frequency_capped" | "test_mode_blocked";
 }
 
 /**

package/src/lib/mailer.ts

@@ -14,6 +14,7 @@ import type {
 } from "@hogsend/email";
 import { getTemplate, renderToHtml, renderToPlainText } from "@hogsend/email";
 import { eq, inArray, sql } from "drizzle-orm";
+import type { DomainStatusService } from "./domain-status.js";
 import {
   type EmailService,
   type EmailServiceConfig,
@@ -27,6 +28,14 @@ import {
 import { hatchet } from "./hatchet.js";
 import { createLogger } from "./logger.js";
 import { emitOutbound } from "./outbound.js";
+import {
+  buildRedirect,
+  isUnaddressable,
+  logRedirect,
+  NO_REDIRECT_MESSAGE,
+  resolveTestMode,
+  TestModeNoRedirectError,
+} from "./test-mode.js";
 import type { PrepareTrackedHtmlFn } from "./tracked.js";
 import { sendTrackedEmail } from "./tracked.js";
 import { resolveEmailSendContextByMessageId } from "./tracking-events.js";
@@ -71,12 +80,20 @@ export function createTrackedMailer(
   deps: {
     provider: EmailProvider;
     prepareTrackedHtml?: PrepareTrackedHtmlFn;
+    /**
+     * Cached sending-domain status, injected by the container. Drives test-mode
+     * redirect: when `testModeCached().active`, every send is redirected to the
+     * safe inbox before reaching the provider. OPTIONAL — direct construction
+     * without it (tests) keeps today's behavior; the container always passes it.
+     */
+    domainStatus?: DomainStatusService;
   },
 ): EmailService {
-  const { provider } = deps;
+  const { provider, domainStatus } = deps;
   const db = config.db as Database | undefined;
   const retryDefaults = config.retryOptions;
   const registry = config.templates;
+  const logger = config.logger ?? emitLogger;
 
   function resolveFrom(overrideFrom?: string): string {
     return overrideFrom ?? config.defaultFrom;
@@ -109,6 +126,11 @@ export function createTrackedMailer(
     ): Promise<TrackedSendResult> {
       const from = resolveFrom(options.from);
 
+      // Resolve test mode ONCE (cache-only, fires the fire-and-forget refresh).
+      // The DB path threads the resolved state into sendTrackedEmail so
+      // tracked.ts stays domainStatus-unaware; the no-db path applies it inline.
+      const testMode = resolveTestMode(domainStatus);
+
       if (db) {
         return sendTrackedEmail({
           db,
@@ -118,6 +140,7 @@ export function createTrackedMailer(
           prepareTrackedHtml: deps.prepareTrackedHtml,
           frequencyCap: config.frequencyCap,
           logger: config.logger,
+          testMode,
           options: {
             templateKey: options.template,
             props: options.props,
@@ -143,14 +166,47 @@ export function createTrackedMailer(
         props: options.props,
         registry,
       });
+      const subject = options.subject ?? defaultSubject;
       // HTML-ONLY wire — the engine ALWAYS renders React → HTML itself before
       // the provider. React Email stays first-class for authoring/Studio; it
       // never crosses the provider boundary.
       const html = await renderToHtml(element);
+
+      // Test-mode redirect on the no-db path. Hard-fail (no row to write here)
+      // by returning a skipped result rather than reaching the real recipient.
+      let wireTo: string | string[] = options.to;
+      let wireSubject = subject;
+      let wireFrom = from;
+      if (testMode) {
+        if (isUnaddressable(testMode)) {
+          logger.error(NO_REDIRECT_MESSAGE, { originalTo: options.to });
+          return trackedSendResult({
+            emailSendId: "",
+            messageId: "",
+            status: "skipped",
+            reason: "test_mode_blocked",
+          });
+        }
+        const r = buildRedirect({
+          from,
+          to: options.to,
+          subject,
+          state: testMode,
+        });
+        wireTo = r.to;
+        wireSubject = r.subject;
+        wireFrom = r.from;
+        logRedirect(logger, {
+          originalTo: r.originalTo,
+          redirectTo: testMode.redirectTo,
+          reason: testMode.reason,
+        });
+      }
+
       const result = await provider.send({
-        from,
-        to: options.to,
-        subject: options.subject ?? defaultSubject,
+        from: wireFrom,
+        to: wireTo,
+        subject: wireSubject,
         html,
         tags: options.tags,
         headers: options.headers,
@@ -166,12 +222,82 @@ export function createTrackedMailer(
 
     async sendRaw(options: SendRawOptions): Promise<SendResult> {
       const gated = applyScheduledAtGate(options);
-      return provider.send({ ...gated, from: resolveFrom(options.from) });
+      const from = resolveFrom(options.from);
+
+      const testMode = resolveTestMode(domainStatus);
+      if (testMode) {
+        // Raw sends have no email_sends row to record a skip against, so an
+        // unaddressable test mode THROWS loudly rather than silently delivering.
+        if (isUnaddressable(testMode)) {
+          logger.error(NO_REDIRECT_MESSAGE, { originalTo: gated.to });
+          throw new TestModeNoRedirectError();
+        }
+        const r = buildRedirect({
+          from,
+          to: gated.to,
+          cc: gated.cc,
+          bcc: gated.bcc,
+          subject: gated.subject,
+          state: testMode,
+        });
+        logRedirect(logger, {
+          originalTo: r.originalTo,
+          redirectTo: testMode.redirectTo,
+          reason: testMode.reason,
+        });
+        // Drop cc/bcc entirely — never leak the test mail to an original recipient.
+        const { cc: _cc, bcc: _bcc, ...rest } = gated;
+        return provider.send({
+          ...rest,
+          from: r.from,
+          to: r.to,
+          subject: r.subject,
+        });
+      }
+
+      return provider.send({ ...gated, from });
     },
 
     async sendBatch(options: {
       emails: BatchEmailItem[];
     }): Promise<{ results: SendResult[] }> {
+      const testMode = resolveTestMode(domainStatus);
+
+      if (testMode) {
+        // Unaddressable ⇒ throw before any item reaches the provider.
+        if (isUnaddressable(testMode)) {
+          logger.error(NO_REDIRECT_MESSAGE, {
+            count: options.emails.length,
+          });
+          throw new TestModeNoRedirectError();
+        }
+        // Each item gets its OWN [TEST → …] prefix; ONE structured WARN for the
+        // whole batch (never N log lines for a 1000-item batch).
+        const originalTos: string[] = [];
+        const emails = options.emails.map((e) => {
+          const from = resolveFrom(e.from);
+          const r = buildRedirect({
+            from,
+            to: e.to,
+            cc: e.cc,
+            bcc: e.bcc,
+            subject: e.subject,
+            state: testMode,
+          });
+          originalTos.push(r.originalTo);
+          const { cc: _cc, bcc: _bcc, ...rest } = e;
+          return { ...rest, from: r.from, to: r.to, subject: r.subject };
+        });
+        logger.warn("email.test_mode_redirect", {
+          event: "email.test_mode_redirect",
+          count: emails.length,
+          redirectTo: testMode.redirectTo,
+          reason: testMode.reason,
+          originalTo: originalTos,
+        });
+        return provider.sendBatch(emails);
+      }
+
       const emails = options.emails.map((e) => ({
         ...e,
         from: resolveFrom(e.from),