@hogsend/engine 0.11.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -40,14 +40,14 @@
     "svix": "^1.95.1",
     "winston": "^3.19.0",
     "zod": "^4.4.3",
-    "@hogsend/core": "^0.11.0",
-    "@hogsend/db": "^0.11.0",
-    "@hogsend/email": "^0.11.0",
-    "@hogsend/plugin-posthog": "^0.11.0",
-    "@hogsend/plugin-resend": "^0.11.0"
+    "@hogsend/core": "^0.12.1",
+    "@hogsend/db": "^0.12.1",
+    "@hogsend/email": "^0.12.1",
+    "@hogsend/plugin-posthog": "^0.12.1",
+    "@hogsend/plugin-resend": "^0.12.1"
   },
   "optionalDependencies": {
-    "@hogsend/plugin-postmark": "^0.11.0"
+    "@hogsend/plugin-postmark": "^0.12.1"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/container.ts

@@ -27,6 +27,10 @@ import type { DefinedJourney } from "./journeys/define-journey.js";
 import { buildJourneyRegistry } from "./journeys/registry.js";
 import { setAnalytics } from "./lib/analytics-singleton.js";
 import { type Auth, createAuth } from "./lib/auth.js";
+import {
+  createDomainStatusService,
+  type DomainStatusService,
+} from "./lib/domain-status.js";
 import { setEmailService } from "./lib/email.js";
 import { EmailProviderRegistry } from "./lib/email-provider-registry.js";
 import { emailProvidersFromEnv } from "./lib/email-providers-from-env.js";
@@ -73,6 +77,14 @@ export interface HogsendClient {
    * defaulting to the env-built Resend provider for byte-for-byte parity.
    */
   emailProvider: EmailProvider;
+  /**
+   * Cached sending-domain status for the ACTIVE provider. Consumed by the
+   * mailer's test-mode check (F3 — sync `testModeCached()` per send), the
+   * `GET/POST /v1/admin/domain` routes, and (via HTTP) the CLI
+   * (`hogsend domain`) + Studio Setup view. In-memory cache only; the per-send
+   * path never awaits a provider call.
+   */
+  domainStatus: DomainStatusService;
   /**
    * The app's template registry (key → component + subject + category +
    * optional preview/examples). Same object threaded into the engine mailer;
@@ -345,6 +357,16 @@ export function createHogsendClient(
     );
   }
 
+  // Cached sending-domain status for the active provider. Constructed right
+  // after provider resolution so it binds the SAME provider the mailer sends
+  // through. One non-blocking warm-up refresh primes the cache at boot —
+  // fire-and-forget, swallowed errors, must never block or fail boot. Skipped
+  // under NODE_ENV=test so test runs stay hermetic (no real provider HTTP).
+  const domainStatus = createDomainStatusService({ provider, env, logger });
+  if (env.NODE_ENV !== "test") {
+    domainStatus.refreshIfStale();
+  }
+
   const defaults: HogsendDefaults = {
     timezone: opts.defaults?.timezone ?? "UTC",
     sendWindow: opts.defaults?.sendWindow,
@@ -375,6 +397,11 @@ export function createHogsendClient(
       {
         provider,
         prepareTrackedHtml,
+        // Test-mode redirect: the mailer reads `domainStatus.testModeCached()`
+        // (sync, cache-only) per send to decide whether to redirect to the safe
+        // inbox. Constructed above (right after provider resolution) so it binds
+        // the SAME active provider the mailer sends through.
+        domainStatus,
       },
     );
 
@@ -498,6 +525,7 @@ export function createHogsendClient(
     emailService,
     emailProviders,
     emailProvider: provider,
+    domainStatus,
     templates,
     analytics,
     registry,

package/src/env.ts

@@ -53,6 +53,29 @@ export const env = createEnv({
     // `EMAIL_FROM ?? RESEND_FROM_EMAIL`, so an unset EMAIL_FROM keeps today's
     // Resend-named default.
     EMAIL_FROM: z.string().email().optional(),
+    // The sending domain the domain-status service reports on. OVERRIDES the
+    // default derivation (host part of EMAIL_FROM, falling back to the host of
+    // RESEND_FROM_EMAIL) — set it when you send from a subaddress domain that
+    // differs from the one registered at the provider.
+    EMAIL_DOMAIN: z.string().optional(),
+    // --- Test mode (provider-neutral send redirect) ---
+    // Controls whether the engine redirects every send to a safe inbox while the
+    // sending domain isn't verified yet:
+    //   auto  (default) — test mode iff the active provider supports domains AND
+    //                      an EMAIL_DOMAIN is configured AND it is UNVERIFIED per
+    //                      the cached DomainStatusService. Fail-OPEN: a cache miss
+    //                      or provider outage resolves to LIVE (never silently
+    //                      redirects prod mail). With no domains capability or no
+    //                      EMAIL_DOMAIN, `auto` stays LIVE — existing deploys are
+    //                      unaffected.
+    //   true            — always redirect (reason: "env_flag").
+    //   false           — never redirect, even with an unverified domain.
+    HOGSEND_TEST_MODE: z.enum(["auto", "true", "false"]).default("auto"),
+    // The safe inbox every redirected send is delivered to in test mode. Falls
+    // back to STUDIO_ADMIN_EMAIL when unset; when NEITHER resolves while test
+    // mode is active, the send is BLOCKED (recorded, never delivered to the real
+    // recipient) with a loud, actionable log.
+    HOGSEND_TEST_EMAIL: z.string().email().optional(),
     // --- Postmark (opt-in BYO provider) ---
     // Postmark stays OPT-IN: a preset is built only when POSTMARK_SERVER_TOKEN
     // is present, and it NEVER changes the default active provider — set
@@ -60,6 +83,11 @@ export const env = createEnv({
     // authenticity is HTTP Basic creds in the webhook URL — fail-closed when
     // unset (status updates rejected).
     POSTMARK_SERVER_TOKEN: z.string().min(1).optional(),
+    // Postmark ACCOUNT token (X-Postmark-Account-Token) — unlocks the Domains
+    // API capability on the Postmark provider. Optional: without it the
+    // provider still sends, it just can't manage sending domains
+    // (`supported: false` on /v1/admin/domain).
+    POSTMARK_ACCOUNT_TOKEN: z.string().min(1).optional(),
     POSTMARK_MESSAGE_STREAM: z.string().min(1).optional(),
     POSTMARK_WEBHOOK_USER: z.string().min(1).optional(),
     POSTMARK_WEBHOOK_PASS: z.string().min(1).optional(),

package/src/index.ts

@@ -3,9 +3,18 @@
 // Content (journeys, webhook sources, workflows) is injected into these
 // factories by client app code; the engine never imports content.
 
+// Sending-domain capability contract (presence of `EmailProvider.domains` is
+// the gate). Already covered by the `export * from "@hogsend/core"` above —
+// re-named here for discoverability.
 export type {
   BatchEmailItem,
   CaptureOptions,
+  DnsRecord,
+  DnsRecordPurpose,
+  DnsRecordStatus,
+  DomainStatus,
+  DomainsCapability,
+  DomainVerificationState,
   EmailEvent,
   EmailEventType,
   EmailProvider,
@@ -161,6 +170,13 @@ export {
 } from "./lib/create-admin.js";
 // --- Infrastructure singletons ---
 export { getDb } from "./lib/db.js";
+// --- Sending-domain status service (cached; container-held) ---
+export {
+  createDomainStatusService,
+  type DomainStatusService,
+  type EngineDomainStatus,
+  type TestModeState,
+} from "./lib/domain-status.js";
 // --- Email ---
 export {
   type SendEmailOptions,

package/src/lib/boot.ts

@@ -81,6 +81,12 @@ export function reportApiReady(info: ApiReadyInfo): void {
   const templates = Object.keys(client.templates).length;
   const localUrl = `http://localhost:${port}`;
 
+  // Cache-only, sync, never throws — so reading it here adds no boot latency.
+  // Loud when env-flag-forced (resolves even with a cold cache); the
+  // domain-unverified auto banner is additionally fired as a transition WARN by
+  // the warm-up refresh in the container.
+  const testMode = client.domainStatus.testModeCached();
+
   if (!bannerMode(client)) {
     client.logger.info("Hogsend API ready", {
       engineVersion,
@@ -91,6 +97,14 @@ export function reportApiReady(info: ApiReadyInfo): void {
       buckets,
       templates,
       schema: info.schemaVersion ?? undefined,
+      ...(testMode.active
+        ? {
+            testMode: {
+              redirectTo: testMode.redirectTo,
+              reason: testMode.reason,
+            },
+          }
+        : {}),
     });
     return;
   }
@@ -104,6 +118,13 @@ export function reportApiReady(info: ApiReadyInfo): void {
   ].join(dim(" · "));
   const label = (text: string) => dim(text.padEnd(7));
 
+  const testModeLine = testMode.active
+    ? `  ${color.bgYellow(color.black(" TEST MODE "))} ${color.yellow(
+        `all sends → ${testMode.redirectTo ?? "(no redirect address — sends will fail!)"} ` +
+          dim(`(${testMode.reason ?? "unknown"})`),
+      )}`
+    : null;
+
   writeBanner([
     `${BADGE} ${dim(`engine ${engineVersion} · api ${API_VERSION}`)}`,
     "",
@@ -111,6 +132,7 @@ export function reportApiReady(info: ApiReadyInfo): void {
     info.schemaVersion
       ? `  ${ok} schema in sync ${dim(`(${info.schemaVersion})`)}`
       : null,
+    testModeLine,
     "",
     `  ${label("API")}${color.cyan(localUrl)}`,
     `  ${label("Docs")}${color.cyan(`${localUrl}/docs`)}`,

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),

package/src/lib/test-mode.ts

@@ -0,0 +1,123 @@
+import { normalizeRecipients } from "@hogsend/core";
+import type { TestModeState } from "./domain-status.js";
+import type { Logger } from "./logger.js";
+
+/**
+ * Test-mode redirect helpers — the provider-neutral safety net that protects an
+ * operator from sending real mail before their DNS verifies. The active
+ * {@link TestModeState} is resolved ONCE per send by the mailer (cache-only,
+ * zero provider latency) and threaded here; these helpers are pure transforms.
+ *
+ * Why the redirect lives in the engine (not the provider): any `EmailProvider`
+ * is a dumb HTML wire; test mode must protect Postmark/SES users identically.
+ * Only `fromOverride` is provider-aware (Resend's `onboarding@resend.dev`), and
+ * that knowledge sits in the domain-status resolver, keyed on `providerId`.
+ */
+
+/** The structured WARN event name fired per redirected send. */
+export const TEST_MODE_REDIRECT_EVENT = "email.test_mode_redirect";
+
+/** The actionable error message when test mode is active but unaddressable. */
+export const NO_REDIRECT_MESSAGE =
+  "test mode active but no redirect address — set HOGSEND_TEST_EMAIL " +
+  "(or STUDIO_ADMIN_EMAIL); the send was BLOCKED, not delivered to the real recipient";
+
+/**
+ * Thrown by the no-db raw send paths (`sendRaw`/`sendBatch`) when test mode is
+ * active but no redirect address resolves. The tracked (DB) path does NOT throw
+ * — it records a `failed` row and returns a skipped result, mirroring the
+ * suppression branch — but the raw paths have no row to write, so they fail
+ * loudly rather than silently delivering to the real recipient.
+ */
+export class TestModeNoRedirectError extends Error {
+  constructor() {
+    super(NO_REDIRECT_MESSAGE);
+    this.name = "TestModeNoRedirectError";
+  }
+}
+
+/** The redirected wire fields for a single message. */
+export interface RedirectedFields {
+  /** Always the single redirect inbox (cc/bcc are dropped). */
+  to: string[];
+  /** The single redirect address (`to[0]`), for the `email_sends.toEmail` column. */
+  redirectTo: string;
+  /** Prefixed `[TEST → <originalRecipients>] <subject>`. */
+  subject: string;
+  /** `fromOverride ?? originalFrom` (Resend ⇒ onboarding@resend.dev). */
+  from: string;
+  /** Comma-joined ORIGINAL recipients, for the WARN log + email_sends marker. */
+  originalTo: string;
+  /** The flattened original recipient list (to + cc + bcc). */
+  originalRecipients: string[];
+}
+
+/**
+ * Resolve the active {@link TestModeState} for a send. Returns the cached state
+ * when `active`, else `null` (live send). ALWAYS fires the fire-and-forget
+ * `refreshIfStale()` first — the ONLY cache-refresh trigger on the send path,
+ * never awaited. `domainStatus` is optional so direct mailer construction
+ * (tests) without it keeps today's behavior.
+ */
+export function resolveTestMode(domainStatus?: {
+  testModeCached(): TestModeState;
+  refreshIfStale(): void;
+}): TestModeState | null {
+  if (!domainStatus) return null;
+  domainStatus.refreshIfStale();
+  const state = domainStatus.testModeCached();
+  return state.active ? state : null;
+}
+
+/**
+ * Build the redirected wire fields for one message under an active test mode.
+ * `to`/`cc`/`bcc` flatten into the subject prefix; the wire `to` becomes the
+ * single redirect inbox and cc/bcc are dropped entirely (never leak the test
+ * mail to an original cc/bcc recipient). Caller MUST have checked
+ * `state.redirectTo !== null` first (use {@link isUnaddressable}).
+ */
+export function buildRedirect(opts: {
+  from: string;
+  to: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  subject: string;
+  state: TestModeState;
+}): RedirectedFields {
+  const originalRecipients = [
+    ...normalizeRecipients(opts.to),
+    ...normalizeRecipients(opts.cc),
+    ...normalizeRecipients(opts.bcc),
+  ];
+  const originalTo = originalRecipients.join(",");
+  // redirectTo is non-null here — the caller gates on isUnaddressable first.
+  const redirectTo = opts.state.redirectTo as string;
+  return {
+    to: [redirectTo],
+    redirectTo,
+    subject: `[TEST → ${originalTo}] ${opts.subject}`,
+    from: opts.state.fromOverride ?? opts.from,
+    originalTo,
+    originalRecipients,
+  };
+}
+
+/** True when test mode is active but no redirect address resolves. */
+export function isUnaddressable(state: TestModeState): boolean {
+  return state.active && state.redirectTo === null;
+}
+
+/** Fire the per-send structured WARN for a redirected send. */
+export function logRedirect(
+  logger: Logger | undefined,
+  meta: {
+    originalTo: string;
+    redirectTo: string | null;
+    reason: string | null;
+  },
+): void {
+  logger?.warn(TEST_MODE_REDIRECT_EVENT, {
+    event: TEST_MODE_REDIRECT_EVENT,
+    ...meta,
+  });
+}

package/src/lib/tracked.ts

@@ -14,6 +14,7 @@ import {
 } from "@hogsend/email";
 import { eq } from "drizzle-orm";
 import { getListRegistry } from "../lists/registry-singleton.js";
+import type { TestModeState } from "./domain-status.js";
 import {
   type FrequencyCapConfig,
   type SendTrackedEmailOptions,
@@ -24,6 +25,12 @@ import { isFrequencyCapped } from "./frequency-cap.js";
 import { hatchet } from "./hatchet.js";
 import { createLogger, type Logger } from "./logger.js";
 import { emitOutbound } from "./outbound.js";
+import {
+  buildRedirect,
+  isUnaddressable,
+  logRedirect,
+  NO_REDIRECT_MESSAGE,
+} from "./test-mode.js";
 
 // Module-level fallback logger for the outbound emit — the tracked-mailer's
 // `logger` dep is optional, but `emitOutbound` requires one. Mirrors the
@@ -49,6 +56,13 @@ interface TrackedEmailDeps {
   frequencyCap?: FrequencyCapConfig;
   /** Optional structured logger for operational events (e.g. cap skips). */
   logger?: Logger;
+  /**
+   * The active test-mode state, resolved ONCE by the mailer (cache-only) and
+   * threaded in so this module stays domainStatus-unaware. `null` ⇒ live send.
+   * When active, suppression/frequency/unsubscribe still key to the ORIGINAL
+   * recipient (`options.to`); only the wire + `email_sends` row are redirected.
+   */
+  testMode?: TestModeState | null;
 }
 
 export async function sendTrackedEmail<K extends TemplateName>(
@@ -61,9 +75,19 @@ export async function sendTrackedEmail<K extends TemplateName>(
     prepareTrackedHtml,
     frequencyCap,
     logger,
+    testMode,
     options,
   } = opts;
 
+  // Test-mode redirect (resolved by the mailer; null ⇒ live). When active, the
+  // wire `to`/`from`/`subject` + the email_sends row are redirected, but EVERY
+  // preference statement below (suppression, frequency cap, unsubscribe token)
+  // still keys to the ORIGINAL recipient `options.to` — preferences belong to
+  // the real user, never the shared test inbox. Resolved lazily after the
+  // suppression/frequency-cap branch so the original recipient's preferences are
+  // honored first.
+  const redirectActive = Boolean(testMode?.active);
+
   // The idempotency-collision result, built identically whether the prior row is
   // found by the up-front short-circuit select OR the concurrent-insert loser
   // path below: surface the winner's send id, mapping "sent" → sent and anything
@@ -220,17 +244,80 @@ export async function sendTrackedEmail<K extends TemplateName>(
         }).element
       : element;
 
+  // Test-mode redirect — resolved AFTER the original-recipient preference checks
+  // above (suppression/frequency/unsubscribe), so preferences belong to the real
+  // user. Hard-fail branch: active but unaddressable ⇒ write a `failed` row with
+  // the metadata marker (so Studio surfaces the blocked send) and return a
+  // skipped result. The provider is NEVER reached — the real recipient must not
+  // receive mail from an unverified domain just because no test inbox is set.
+  if (redirectActive && testMode && isUnaddressable(testMode)) {
+    (logger ?? emitLogger).error(NO_REDIRECT_MESSAGE, {
+      originalTo: options.to,
+      templateKey: options.templateKey,
+    });
+    const rows = await db
+      .insert(emailSends)
+      .values({
+        templateKey: options.templateKey,
+        fromEmail: options.from,
+        toEmail: options.to,
+        subject: options.subject ?? "",
+        category: effectiveCategory,
+        journeyStateId: options.journeyStateId,
+        userId: options.userId,
+        userEmail: options.userEmail ?? options.to,
+        status: "failed",
+        metadata: { testMode: true, originalTo: options.to },
+      })
+      .returning({ id: emailSends.id });
+    const blockedRow = rows[0];
+    if (!blockedRow) throw new Error("Failed to insert email_sends row");
+    return trackedSendResult({
+      emailSendId: blockedRow.id,
+      messageId: "",
+      status: "skipped",
+      reason: "test_mode_blocked",
+    });
+  }
+
+  // Active + addressable: compute the redirected wire fields ONCE. `email_sends`
+  // records what ACTUALLY went out the wire (redirect inbox, prefixed subject,
+  // effective from) plus the `metadata.originalTo` marker, while preferences
+  // above stayed keyed to `options.to`.
+  const redirect =
+    redirectActive && testMode
+      ? buildRedirect({
+          from: options.from,
+          to: options.to,
+          subject,
+          state: testMode,
+        })
+      : null;
+  if (redirect && testMode) {
+    logRedirect(logger ?? emitLogger, {
+      originalTo: redirect.originalTo,
+      redirectTo: testMode.redirectTo,
+      reason: testMode.reason,
+    });
+  }
+  const wireTo = redirect ? redirect.to : options.to;
+  const wireSubject = redirect ? redirect.subject : subject;
+  const wireFrom = redirect ? redirect.from : options.from;
+
   const baseInsert = db.insert(emailSends).values({
     templateKey: options.templateKey,
-    fromEmail: options.from,
-    toEmail: options.to,
-    subject,
+    fromEmail: wireFrom,
+    toEmail: redirect ? redirect.redirectTo : options.to,
+    subject: wireSubject,
     category: effectiveCategory,
     journeyStateId: options.journeyStateId,
     userId: options.userId,
     userEmail: options.userEmail ?? options.to,
     status: "queued",
     idempotencyKey: options.idempotencyKey,
+    ...(redirect
+      ? { metadata: { testMode: true, originalTo: options.to } }
+      : {}),
   });
 
   // With an idempotency key, swallow a concurrent-insert collision on the unique
@@ -274,9 +361,9 @@ export async function sendTrackedEmail<K extends TemplateName>(
         : rawHtml;
 
     const result = await provider.send({
-      from: options.from,
-      to: options.to,
-      subject,
+      from: wireFrom,
+      to: wireTo,
+      subject: wireSubject,
       html,
       tags: options.tags,
       headers: sendHeaders,

package/src/routes/admin/domain.ts

@@ -0,0 +1,222 @@
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import type { AppEnv } from "../../app.js";
+import { errorSchema } from "../../lib/schemas.js";
+
+/**
+ * Admin sending-domain routes. The provider's optional `domains` capability is
+ * the gate: when the active provider has none, the POSTs return 501
+ * `{ error: "provider_unsupported" }` and the GET reports `supported: false`.
+ * Provider API keys never leave the server — the CLI (`hogsend domain`) and
+ * Studio's Setup view only ever talk to these routes.
+ */
+
+// Mirrors the pinned `DnsRecord` shape (@hogsend/core providers/domains.ts).
+const DnsRecordSchema = z.object({
+  type: z.enum(["TXT", "CNAME", "MX"]),
+  name: z.string(),
+  value: z.string(),
+  ttl: z.number().optional(),
+  priority: z.number().optional(),
+  purpose: z.enum([
+    "verification",
+    "spf",
+    "dkim",
+    "return_path",
+    "tracking",
+    "mx",
+    "other",
+  ]),
+  status: z.enum(["pending", "verified", "failed", "unknown"]),
+});
+
+// Mirrors the pinned `DomainStatus` shape.
+const DomainStatusSchema = z.object({
+  domain: z.string(),
+  state: z.enum(["not_found", "pending", "verified", "failed"]),
+  records: z.array(DnsRecordSchema),
+  providerId: z.string(),
+  checkedAt: z.string(),
+  raw: z.unknown().optional(),
+});
+
+// Mirrors the pinned `TestModeState` shape (stubbed inactive until F3).
+const TestModeStateSchema = z.object({
+  active: z.boolean(),
+  reason: z.enum(["env_flag", "domain_unverified"]).nullable(),
+  redirectTo: z.string().nullable(),
+  fromOverride: z.string().nullable(),
+});
+
+// Mirrors the pinned `EngineDomainStatus` shape.
+const EngineDomainStatusSchema = z.object({
+  domain: z.string().nullable(),
+  providerId: z.string(),
+  supported: z.boolean(),
+  status: DomainStatusSchema.nullable(),
+  testMode: TestModeStateSchema,
+});
+
+/** Pinned domain validation regex (PROJECT_SPEC §e). */
+const DOMAIN_RE = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/i;
+
+/**
+ * Provider domains calls can fail for configuration reasons the operator must
+ * act on (e.g. a send-only restricted Resend key cannot read the domains API).
+ * Surface those as 502 with the provider's message — `hogsend domain` and
+ * Studio render this string directly — instead of an opaque 500.
+ */
+const providerErrorBody = (providerId: string, err: unknown) => ({
+  error: `domains request to provider "${providerId}" failed: ${
+    err instanceof Error ? err.message : String(err)
+  }`,
+});
+
+const providerErrorResponse = {
+  content: { "application/json": { schema: errorSchema } },
+  description: "The provider rejected or failed the domains request",
+} as const;
+
+const getDomainRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Admin — Domain"],
+  summary: "Sending-domain status (records, verification state, test mode)",
+  request: {
+    query: z.object({
+      refresh: z.coerce.boolean().optional(),
+    }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": { schema: EngineDomainStatusSchema },
+      },
+      description:
+        "Cached domain status for the active email provider; ?refresh=true forces a provider round-trip",
+    },
+    502: providerErrorResponse,
+  },
+});
+
+const addDomainRoute = createRoute({
+  method: "post",
+  path: "/",
+  tags: ["Admin — Domain"],
+  summary: "Register the sending domain with the active email provider",
+  request: {
+    body: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            domain: z.string().regex(DOMAIN_RE, "invalid domain"),
+          }),
+        },
+      },
+    },
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": { schema: EngineDomainStatusSchema },
+      },
+      description: "Domain registered (idempotent) — fresh status",
+    },
+    501: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "The active provider has no domains capability",
+    },
+    502: providerErrorResponse,
+  },
+});
+
+const verifyDomainRoute = createRoute({
+  method: "post",
+  path: "/verify",
+  tags: ["Admin — Domain"],
+  summary: "Trigger a provider-side verification pass for the sending domain",
+  responses: {
+    200: {
+      content: {
+        "application/json": { schema: EngineDomainStatusSchema },
+      },
+      description: "Verification pass triggered — fresh status",
+    },
+    400: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "No sending domain configured (EMAIL_DOMAIN / EMAIL_FROM)",
+    },
+    501: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "The active provider has no domains capability",
+    },
+    502: providerErrorResponse,
+  },
+});
+
+export const domainRouter = new OpenAPIHono<AppEnv>()
+  .openapi(getDomainRoute, async (c) => {
+    const { domainStatus, emailProvider } = c.get("container");
+    const { refresh } = c.req.valid("query");
+    try {
+      const status = await domainStatus.getStatus({ refresh });
+      return c.json(status, 200);
+    } catch (err) {
+      return c.json(
+        providerErrorBody(emailProvider.meta?.id ?? "email", err),
+        502,
+      );
+    }
+  })
+  .openapi(addDomainRoute, async (c) => {
+    const { domainStatus, emailProvider } = c.get("container");
+    const { domain } = c.req.valid("json");
+
+    if (!emailProvider.domains) {
+      return c.json({ error: "provider_unsupported" }, 501);
+    }
+
+    try {
+      // Idempotent at the provider (an existing domain falls through to lookup).
+      await emailProvider.domains.create(domain);
+
+      // Bust + refresh the cached snapshot so the response reflects the create.
+      const status = await domainStatus.getStatus({ refresh: true });
+      return c.json(status, 200);
+    } catch (err) {
+      return c.json(
+        providerErrorBody(emailProvider.meta?.id ?? "email", err),
+        502,
+      );
+    }
+  })
+  .openapi(verifyDomainRoute, async (c) => {
+    const { domainStatus, emailProvider } = c.get("container");
+
+    if (!emailProvider.domains) {
+      return c.json({ error: "provider_unsupported" }, 501);
+    }
+
+    try {
+      const current = await domainStatus.getStatus();
+      if (!current.domain) {
+        return c.json({ error: "no_domain_configured" }, 400);
+      }
+
+      // Prefer the provider's explicit verification pass; fall back to a plain
+      // status fetch for providers without one.
+      const capability = emailProvider.domains;
+      if (capability.verify) {
+        await capability.verify(current.domain);
+      } else {
+        await capability.get(current.domain);
+      }
+
+      const status = await domainStatus.getStatus({ refresh: true });
+      return c.json(status, 200);
+    } catch (err) {
+      return c.json(
+        providerErrorBody(emailProvider.meta?.id ?? "email", err),
+        502,
+      );
+    }
+  });

package/src/routes/admin/index.ts

@@ -10,6 +10,7 @@ import { bucketsRouter } from "./buckets.js";
 import { bulkRouter } from "./bulk.js";
 import { contactsRouter } from "./contacts.js";
 import { dlqRouter } from "./dlq.js";
+import { domainRouter } from "./domain.js";
 import { emailsRouter } from "./emails.js";
 import { eventsRouter } from "./events.js";
 import { journeyLogsRouter } from "./journey-logs.js";
@@ -44,3 +45,4 @@ adminRouter.route("/webhooks", webhooksRouter);
 adminRouter.route("/audit-logs", auditLogsRouter);
 adminRouter.route("/alerts", alertsRouter);
 adminRouter.route("/dlq", dlqRouter);
+adminRouter.route("/domain", domainRouter);