@dbx-tools/email 0.3.29 → 0.3.31

package/README.md

@@ -1,24 +1,31 @@
 # @dbx-tools/email
 
-Server-side email runtime, Mastra tool, and AppKit plugin.
+Server-side email runtime, agent tools, and AppKit plugin.
 
 Import this package when an AppKit or Mastra backend needs model-drafted
 outbound email with human approval, sender derivation, SMTP dispatch, and a
-local outbox mode for development. Browser-safe message/result schemas live in
+local outbox mode for development. AppKit ships no first-party email surface,
+so this is additive rather than an alternative to a native plugin. Browser-safe
+message/result schemas live in
 [`@dbx-tools/shared-email`](../../shared/email).
 
-Key features:
+**Key features:**
 
-- AppKit plugin registration for email runtime setup and sender-option routes.
-- A Mastra `send_email` tool that suspends for human approval before delivery.
+- AppKit plugin registration that resolves config, verifies SMTP at boot, and
+  mounts a sender-options route.
+- Two agent surfaces over one runtime: a Mastra `send_email` tool that suspends
+  for human approval, and an AppKit `email.send` tool annotated as a write so a
+  host's approval gate fires.
 - SMTP delivery for production and HTML outbox delivery for local development
   and tests.
 - Sender derivation from the current Databricks user, a fixed `EMAIL_FROM`, or a
   configured domain.
-- Sender allow-list enforcement with exact addresses, domains, domain
-  wildcards, and a final `*` escape hatch.
+- Deny-by-default sender policy with exact addresses, domains, domain wildcards,
+  and a named `unrestricted` escape hatch.
 - Markdown-to-HTML rendering with a small email layout, inline styles, metadata,
   and attachment summaries.
+- Named caps on body length and attachment size, and an `AbortSignal` threaded
+  through every send.
 
 ## Register The AppKit Plugin
 
@@ -36,23 +43,65 @@ await createApp({
   plugins: [
     server(),
     lakebase(),
-    emailPlugin.email(),
+    emailPlugin.email({
+      smtp: { host: "smtp.example.com", user: "apikey", password: process.env.SMTP_KEY },
+      domain: "mail.example.com",
+    }),
     mastraPlugin.mastra({ agents: support, storage: true }),
   ],
 });
 ```
 
 `plugin.email()` validates config, primes the shared runtime, verifies SMTP when
-SMTP mode is active, and mounts a sender-options route for UIs. `tool.emailTool()`
-creates an approval-gated Mastra `send_email` tool. Approval requires Mastra
-storage, so register `lakebase()` or configure storage explicitly in the Mastra
-plugin.
+SMTP mode is active, and mounts a sender-options route for UIs. A failed verify
+fails setup, so a bad host or credential shows up in the boot logs rather than on
+the first approved send; outbox mode skips the check and logs loudly instead.
+
+`tool.emailTool()` creates an approval-gated Mastra `send_email` tool. Approval
+requires Mastra storage, so register `lakebase()` or configure storage explicitly
+in the Mastra plugin.
 
 The plugin does not decide how approval is presented. It emits a Mastra tool
 suspension and expects the host UI to resume that tool call with an approval or
 denial result. [`@dbx-tools/ui-email`](../../ui/email) provides the matching
 approval card and compose components.
 
+## Configuration
+
+| Option           | Type                            | Default                                   | Description                                                                      |
+| ---------------- | ------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------- |
+| `smtp.host`      | `string`                        | `SMTP_HOST`                               | SMTP server hostname. Omit the whole `smtp` block to run in outbox mode.         |
+| `smtp.port`      | `number`                        | `SMTP_PORT`, then `587`                   | SMTP server port.                                                                |
+| `smtp.secure`    | `boolean`                       | `SMTP_SECURE`, then `port === 465`        | TLS-on-connect socket rather than STARTTLS.                                      |
+| `smtp.user`      | `string`                        | `SMTP_USER`                               | SMTP auth username.                                                              |
+| `smtp.password`  | `string`                        | `SMTP_PASSWORD`                           | SMTP auth password or API key.                                                   |
+| `domain`         | `string`                        | `EMAIL_DOMAIN`                            | Domain the sender is derived on, as `<user-local-part>@<domain>`.                |
+| `from`           | `string`                        | `EMAIL_FROM`                              | Fixed `From` address. Skips per-user derivation.                                 |
+| `senderPolicy`   | `"allowlist" \| "unrestricted"` | `EMAIL_SENDER_POLICY`, then `"allowlist"` | How the sender is restricted when `allowedSenders` is empty.                     |
+| `allowedSenders` | `string \| string[]`            | `EMAIL_ALLOWED_SENDERS`                   | Permitted `From` patterns: exact addresses, `*@domain`, a bare `domain`, or `*`. |
+| `outDir`         | `string`                        | `EMAIL_OUTBOX_DIR`, then `<cwd>/tmp`      | Directory the outbox writes HTML previews to.                                    |
+| `brand`          | `EmailBrand`                    | none                                      | Accent color, font, display name, and header logo inlined into every message.    |
+
+Precedence per field is explicit config, then the environment variable, then the
+built-in default.
+
+| Environment variable    | Purpose                                                       |
+| ----------------------- | ------------------------------------------------------------- |
+| `SMTP_HOST`             | SMTP server hostname.                                         |
+| `SMTP_PORT`             | SMTP server port.                                             |
+| `SMTP_SECURE`           | Force or disable a TLS-on-connect socket.                     |
+| `SMTP_USER`             | SMTP auth username.                                           |
+| `SMTP_PASSWORD`         | SMTP auth password or API key.                                |
+| `EMAIL_DOMAIN`          | Domain for the derived sender address.                        |
+| `EMAIL_FROM`            | Fixed `From` address.                                         |
+| `EMAIL_SENDER_POLICY`   | `allowlist` (default) or `unrestricted`.                      |
+| `EMAIL_ALLOWED_SENDERS` | Comma- or whitespace-separated `From` allow-list.             |
+| `EMAIL_OUTBOX_MODE`     | Opt in to writing messages to disk when SMTP is unconfigured. |
+| `EMAIL_OUTBOX_DIR`      | Directory for outbox previews.                                |
+
+The `SMTP_*` names are unprefixed because SMTP is a third-party service, not a
+Databricks resource.
+
 ## Send Without An Agent
 
 ```ts
@@ -71,7 +120,35 @@ const result = await transport.sendEmail(
 ```
 
 Use direct sends for operational mail, tests, or admin flows where a model is not
-involved. The same resolved runtime is used by the AppKit plugin and tool.
+involved. The same resolved runtime is used by the AppKit plugin and both agent
+tools, so every path shares one connection pool, one sender policy, and one set
+of caps. A third argument accepts an `AbortSignal` when the caller wants to stop
+waiting on SMTP.
+
+The plugin export is equivalent and resolves the sender for you when the caller
+is a Databricks user:
+
+```ts
+const appkit = await createApp({ plugins: [server(), emailPlugin.email()] });
+await appkit.email.sendEmail(message, "reports@example.com");
+```
+
+## How Sends Reach AppKit's Interceptors
+
+Every send runs through AppKit's interceptor chain (timeout, telemetry, and the
+retry / cache posture in `defaults`), including sends from the Mastra tool, which
+has no plugin instance in scope. The runtime carries an executor slot for this:
+registering the plugin installs its own `Plugin.execute()` there at setup, and
+`sendEmail()` routes through whatever is installed.
+
+Nothing else has to be wired up. Two consequences are worth knowing:
+
+- In a plain Mastra app with no AppKit plugin registered, the slot falls back to
+  running the send directly, so the tool still works without interceptors.
+- Recipient, cap, and sender-policy checks run _before_ the chain, so a rejected
+  message keeps its specific status and actionable message. A failure inside the
+  chain is re-raised as a stable `ExecutionError`, so an SMTP relay's own wording
+  never becomes the caller's or the model's error text.
 
 ## Resolve SMTP Or Outbox Mode
 
@@ -83,15 +160,16 @@ const resolved = config.resolveEmailConfig({
   domain: "mail.example.com",
 });
 
-const runtime = transport.getEmailRuntime(resolved);
+const runtime = transport.getEmailRuntime({
+  smtp: { host: "smtp.example.com", user: "apikey", password: secret },
+  domain: "mail.example.com",
+});
 ```
 
-Resolution order is explicit config first, then env vars:
-
-- `SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURE`, `SMTP_USER`, `SMTP_PASSWORD`;
-- `EMAIL_DOMAIN` or `EMAIL_FROM`;
-- `EMAIL_OUTBOX_MODE`, `EMAIL_OUTBOX_DIR`;
-- `EMAIL_ALLOWED_SENDERS`.
+`resolveEmailConfig()` returns the validated `ResolvedEmailConfig` for
+inspection. `getEmailRuntime()` takes the same plugin config, resolves it, and
+memoizes the transport process-wide; the plugin primes it at setup, so later
+callers pass nothing and get the same instance.
 
 SMTP mode requires host, user, password, and a sender source. Outbox mode writes
 HTML files to disk when SMTP credentials are absent and `EMAIL_OUTBOX_MODE=1`.
@@ -99,15 +177,44 @@ HTML files to disk when SMTP credentials are absent and `EMAIL_OUTBOX_MODE=1`.
 Use SMTP mode for deployed apps. Use outbox mode for local demos, automated
 tests, and development loops where sending real mail would be risky.
 
+## Agent Tools
+
+Two tools expose the same send capability, one per agent runtime. Both are
+gated: the Mastra tool suspends for approval, and the AppKit tool is annotated
+`{ effect: "write", requiresUserContext: true }` so a host's approval gate fires.
+The AppKit tool is deliberately not `autoInheritable`, so an agent reaches it
+only by wiring it explicitly.
+
+| Tool         | Runtime | Wiring                                                                   |
+| ------------ | ------- | ------------------------------------------------------------------------ |
+| `send_email` | Mastra  | `tools: () => ({ send_email: emailTool.emailTool() })`                   |
+| `email.send` | AppKit  | `plugins.email.toolkit()` in code, or a `plugin:email` frontmatter entry |
+
+```ts
+import { createApp, server } from "@databricks/appkit";
+import { agents, createAgent } from "@databricks/appkit/beta";
+import { plugin as emailPlugin } from "@dbx-tools/email";
+
+const support = createAgent({
+  instructions: "Draft emails, but wait for approval before sending.",
+  tools: (plugins) => ({ ...plugins.email.toolkit() }),
+});
+
+await createApp({
+  plugins: [server(), emailPlugin.email(), agents({ agents: { support } })],
+});
+```
+
 ## AppKit Routes
 
-The plugin exposes a sender-options route for browser clients. The response
-matches `email.emailSendersSchema` from
-[`@dbx-tools/shared-email`](../../shared/email) and includes:
+| Method | Path                 | Response                                                   |
+| ------ | -------------------- | ---------------------------------------------------------- |
+| `GET`  | `/api/email/senders` | `email.emailSendersSchema` from `@dbx-tools/shared-email`. |
 
-- the concrete sender addresses the current user may choose;
-- the default sender address;
-- whether the list was restricted by policy.
+The response includes the concrete sender addresses the current user may choose,
+the default sender address, and whether the list was restricted by policy. The
+route runs in the on-behalf-of user scope so domain wildcards resolve against the
+caller's own local part.
 
 Use this route to populate a `From` dropdown in a compose UI. If no dropdown is
 shown, the server can still derive the sender from the active user and config.
@@ -115,19 +222,23 @@ shown, the server can still derive the sender from the active user and config.
 ## Derive And Restrict Senders
 
 ```ts
-import { sender } from "@dbx-tools/email";
+import { config, sender } from "@dbx-tools/email";
 
-const from = sender.resolveSenderAddress({
-  userEmail: "alice@databricks.com",
-  domain: "mail.example.com",
-});
+const resolved = config.resolveEmailConfig({ domain: "mail.example.com" });
+const from = sender.resolveSenderAddress(resolved, "alice@databricks.com");
 
-sender.assertSenderAllowed(from, ["*@mail.example.com", "alerts@example.com"]);
+sender.assertSenderAllowed(from, resolved.allowedSenders);
 ```
 
 Sender helpers support exact addresses, domain wildcards, bare domains, and `*`.
-`sender.listSenderOptions()` produces the concrete `From` choices for the
-current user, which is what the AppKit plugin exposes to clients.
+`sender.listSenderOptions(resolved, userEmail)` produces the concrete `From`
+choices for the current user, which is what the AppKit plugin exposes to clients.
+
+The default `senderPolicy: "allowlist"` is deny-by-default: with no explicit
+`allowedSenders`, the effective allow-list is the configured sender source, so a
+deployment that only sets `EMAIL_DOMAIN` rejects a `From` on any other domain.
+Set `senderPolicy: "unrestricted"` to accept any `From` a caller supplies. The
+effective policy is logged at boot.
 
 ## Render Markdown Email
 
@@ -136,13 +247,17 @@ import { emailHtml, markdown } from "@dbx-tools/email";
 
 const html = emailHtml.renderEmailHtml({
   subject: "Incident update",
-  body: markdown.markdownToHtml("## Status\nResolved."),
+  body: "## Status\nResolved.",
 });
+
+const fragment = markdown.markdownToHtml("## Status\nResolved.");
 ```
 
-`markdown.normalizeMarkdown()` trims common indentation and fenced-text noise.
-`markdown.markdownToHtml()` renders Markdown. `emailHtml.renderEmailHtml()` wraps
-the rendered body in the package layout and inlines CSS for mail clients.
+`renderEmailHtml()` takes a Markdown `body`, renders it, wraps it in the package
+layout, and inlines the CSS for mail clients. Pass Markdown, not HTML: the
+renderer runs `markdownToHtml()` itself. `markdown.normalizeMarkdown()` trims
+common indentation and repairs fenced-text noise, and
+`markdown.markdownToHtml()` renders a Markdown fragment on its own.
 
 ## Brand The Email
 
@@ -183,26 +298,46 @@ font but no logo.
 ```ts
 import { outbox } from "@dbx-tools/email";
 
-await outbox.writeOutboxEmail({
-  dir: "tmp/email-outbox",
-  message,
-  from: "bot@example.com",
-});
+const path = await outbox.writeOutboxEmail(message, "bot@example.com", "tmp/email-outbox");
 ```
 
-Outbox files are HTML previews with metadata in the header. Attachments are
-listed in the preview, but attachment bytes are not copied to disk.
+Outbox files are HTML previews with metadata in the header, written to
+`<dir>/<from>/<timestamp>-<subject-slug>.html`. A fourth argument accepts an
+`EmailBrand`. Attachments are listed in the preview, but attachment bytes are not
+copied to disk.
+
+## Limits
+
+| Constant                      | Value   | Bounds                                   |
+| ----------------------------- | ------- | ---------------------------------------- |
+| `MAX_BODY_CHARS`              | 200,000 | Markdown body length.                    |
+| `MAX_ATTACHMENT_BYTES`        | 10 MiB  | One attachment's decoded inline content. |
+| `MAX_ATTACHMENTS_TOTAL_BYTES` | 20 MiB  | Combined decoded attachment content.     |
+| `MAX_ATTACHMENT_COUNT`        | 20      | Attachments on one message.              |
+| `SEND_TIMEOUT_MS`             | 30,000  | One SMTP conversation.                   |
+| `VERIFY_TIMEOUT_MS`           | 15,000  | The setup-time SMTP handshake.           |
+
+An oversized payload is rejected with a `ValidationError` before anything is
+handed to SMTP. The constants and the plugin's interceptor settings live in the
+`defaults` module.
 
 ## Modules
 
-- `plugin` - `EmailPlugin`, `email()` AppKit plugin factory, and sender route.
-- `tool` - approval-gated `emailTool()` Mastra tool.
-- `transport` - shared runtime, `getEmailRuntime()`, `resetEmailRuntime()`, and
-  `sendEmail()`.
-- `config` - SMTP/outbox config types, JSON schema, and `resolveEmailConfig()`.
+- `plugin` - `EmailPlugin`, the `email()` AppKit plugin factory, the sender
+  route, and the `email.send` AppKit agent tool.
+- `tool` - approval-gated `emailTool()` Mastra tool and the shared
+  `SEND_EMAIL_DESCRIPTION`.
+- `transport` - shared runtime, `getEmailRuntime()`, `resetEmailRuntime()`,
+  `verifyEmailTransport()`, `sendEmail()`, and the executor slot
+  (`setEmailExecutor()`, `executeWrite()`) that puts every send on AppKit's
+  interceptor chain.
+- `config` - SMTP/outbox config types, sender policy, JSON schema, and
+  `resolveEmailConfig()`.
+- `defaults` - execution settings for the interceptor chain and the payload caps.
 - `sender` - sender derivation, allow-list parsing, and sender-option listing.
 - `markdown` / `emailHtml` - Markdown normalization/rendering and HTML layout.
 - `outbox` - local HTML file writer for development and tests.
+- `brand` - `EmailBrand`, `emailBrandFromContext()`, and `defaultEmailBrand`.
 
 Pair this package with [`@dbx-tools/shared-email`](../../shared/email) when a UI
 or tool schema needs to validate the same email payload.

package/index.ts

@@ -4,6 +4,7 @@
 
 export * as brand from "./src/brand";
 export * as config from "./src/config";
+export * as defaults from "./src/defaults";
 export * as emailHtml from "./src/email-html";
 export * as markdown from "./src/markdown";
 export * as outbox from "./src/outbox";
@@ -12,7 +13,8 @@ export * as sender from "./src/sender";
 export * as tool from "./src/tool";
 export * as transport from "./src/transport";
 export type { EmailBrand } from "./src/brand";
-export type { SmtpConfig, EmailPluginConfig, ResolvedSmtpConfig, ResolvedFileConfig, ResolvedEmailConfig } from "./src/config";
+export type { SenderPolicy, SmtpConfig, EmailPluginConfig, ResolvedSmtpConfig, ResolvedFileConfig, ResolvedEmailConfig } from "./src/config";
+export type { EmailExecuteConfig, EmailExecutionSettings } from "./src/defaults";
 export type { EmailHtmlOptions } from "./src/email-html";
 export type { EmailToolOptions } from "./src/tool";
-export type { EmailRuntime } from "./src/transport";
+export type { EmailExecutor, EmailRuntime } from "./src/transport";

package/package.json

@@ -19,15 +19,15 @@
     "juice": "^12.1.1",
     "marked": "^18.0.5",
     "nodemailer": "^7.0.13",
-    "@dbx-tools/shared-core": "0.3.29",
-    "@dbx-tools/shared-email": "0.3.29"
+    "@dbx-tools/shared-core": "0.3.31",
+    "@dbx-tools/shared-email": "0.3.31"
   },
   "main": "index.ts",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.29",
+  "version": "0.3.31",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/config.ts

@@ -18,24 +18,49 @@
  * to a single SMTP server (e.g. SMTP2GO): `SMTP_HOST`, `SMTP_PORT`,
  * `SMTP_SECURE`, `SMTP_USER`, `SMTP_PASSWORD`, plus `EMAIL_DOMAIN` for
  * the derived sender's domain, `EMAIL_FROM` for an explicit override,
- * and `EMAIL_OUTBOX_DIR` for the outbox directory.
+ * `EMAIL_SENDER_POLICY` for the sender restriction mode, and
+ * `EMAIL_OUTBOX_DIR` for the outbox directory.
  *
  * @module
  */
 import { resolve } from "node:path";
-import type { BasePluginConfig } from "@databricks/appkit";
+import { ConfigurationError, ValidationError, type BasePluginConfig } from "@databricks/appkit";
 import { object } from "@dbx-tools/shared-core";
 import type { JSONSchema7 } from "json-schema";
 import type { EmailBrand } from "./brand";
 import { parseAllowedSenders } from "./sender";
 
+/** SMTP submission port used when none is configured. */
+export const DEFAULT_SMTP_PORT = 587;
+
+/** SMTP port that implies a TLS-on-connect socket rather than STARTTLS. */
+export const IMPLICIT_TLS_SMTP_PORT = 465;
+
+/**
+ * How the sender (`From`) address is restricted.
+ *
+ * `"allowlist"` is the default and the deny-by-default posture: a send is
+ * permitted only from an address the configuration names, either through
+ * {@link EmailPluginConfig.allowedSenders} or, when that is empty, through
+ * the configured sender source ({@link EmailPluginConfig.from} as an exact
+ * address, {@link EmailPluginConfig.domain} as a `*@domain` wildcard).
+ *
+ * `"unrestricted"` is the explicit opt-out: any `From` a caller supplies is
+ * accepted. Only reach for it when an upstream system already vets the
+ * sender.
+ */
+export type SenderPolicy = "allowlist" | "unrestricted";
+
 /** SMTP connection + credentials. All fields fall back to env when unset. */
 export interface SmtpConfig {
   /** SMTP server hostname (`SMTP_HOST`). */
   host?: string;
-  /** SMTP server port (`SMTP_PORT`). Defaults to 587. */
+  /** SMTP server port (`SMTP_PORT`). Defaults to {@link DEFAULT_SMTP_PORT}. */
   port?: number;
-  /** Use a TLS-on-connect socket (`SMTP_SECURE`). Defaults to `port === 465`. */
+  /**
+   * Use a TLS-on-connect socket (`SMTP_SECURE`). Defaults to
+   * `port === ` {@link IMPLICIT_TLS_SMTP_PORT}.
+   */
   secure?: boolean;
   /** SMTP auth username (`SMTP_USER`). */
   user?: string;
@@ -66,15 +91,22 @@ export interface EmailPluginConfig extends BasePluginConfig {
    */
   outDir?: string;
   /**
-   * Optional allow-list restricting the sender (`From`) address. Each
-   * entry is an exact address (`user@domain.com`), a domain wildcard
-   * (`*@domain.com` or the bare `domain.com`, matching any local part on
-   * that domain), or `*` (any). A resolved / chosen sender that matches
-   * no entry is rejected at send time. Accepts a `string[]` or a single
-   * comma- / whitespace-separated string; falls back to
-   * `EMAIL_ALLOWED_SENDERS`. Omit (or leave empty) for no restriction.
+   * Allow-list restricting the sender (`From`) address. Each entry is an
+   * exact address (`user@domain.com`), a domain wildcard (`*@domain.com`
+   * or the bare `domain.com`, matching any local part on that domain), or
+   * `*` (any). A resolved / chosen sender that matches no entry is
+   * rejected at send time. Accepts a `string[]` or a single comma- /
+   * whitespace-separated string; falls back to `EMAIL_ALLOWED_SENDERS`.
+   * When empty, the {@link senderPolicy} decides what is permitted.
    */
   allowedSenders?: string | string[];
+  /**
+   * How the sender address is restricted when {@link allowedSenders} is
+   * empty (`EMAIL_SENDER_POLICY`). Defaults to `"allowlist"`, which
+   * narrows sends to the configured sender source. See
+   * {@link SenderPolicy}.
+   */
+  senderPolicy?: SenderPolicy;
   /**
    * Optional brand styling (accent, font, header logo) applied to the
    * rendered HTML of every message. Omit for the neutral default layout.
@@ -91,10 +123,14 @@ interface ResolvedSender {
   /** Explicit sender override; present skips per-user derivation. */
   from?: string;
   /**
-   * Normalized sender allow-list (see {@link EmailPluginConfig.allowedSenders}).
-   * Empty means no restriction.
+   * Effective sender allow-list: the configured patterns when any were
+   * given, else the patterns implied by the sender source under an
+   * `"allowlist"` policy. Empty means unenforceable (an `"unrestricted"`
+   * policy, or an outbox with no sender source to narrow to).
    */
   allowedSenders: string[];
+  /** The restriction mode the allow-list was resolved under. */
+  senderPolicy: SenderPolicy;
   /** Brand styling applied to rendered HTML; absent for the default layout. */
   brand?: EmailBrand;
 }
@@ -126,14 +162,20 @@ export const EMAIL_CONFIG_SCHEMA: JSONSchema7 = {
       type: "object",
       description: "SMTP connection and credentials (env fallbacks: SMTP_*).",
       properties: {
-        host: { type: "string", description: "SMTP server hostname." },
-        port: { type: "number", description: "SMTP server port (default 587)." },
+        host: { type: "string", description: "SMTP server hostname (SMTP_HOST)." },
+        port: {
+          type: "number",
+          description: `SMTP server port (SMTP_PORT). Defaults to ${DEFAULT_SMTP_PORT}.`,
+        },
         secure: {
           type: "boolean",
-          description: "TLS-on-connect socket (default: port === 465).",
+          description: `TLS-on-connect socket (SMTP_SECURE). Defaults to port === ${IMPLICIT_TLS_SMTP_PORT}.`,
+        },
+        user: { type: "string", description: "SMTP auth username (SMTP_USER)." },
+        password: {
+          type: "string",
+          description: "SMTP auth password / API key (SMTP_PASSWORD).",
         },
-        user: { type: "string", description: "SMTP auth username." },
-        password: { type: "string", description: "SMTP auth password / API key." },
       },
     },
     domain: {
@@ -154,15 +196,72 @@ export const EMAIL_CONFIG_SCHEMA: JSONSchema7 = {
       type: "array",
       items: { type: "string" },
       description:
-        'Allow-list of permitted sender (From) patterns: exact addresses ("user@domain.com"), domain wildcards ("*@domain.com"), or "*". Also accepts a comma/space-separated string. Falls back to EMAIL_ALLOWED_SENDERS. Empty = unrestricted.',
+        'Allow-list of permitted sender (From) patterns: exact addresses ("user@domain.com"), domain wildcards ("*@domain.com"), or "*". Also accepts a comma/space-separated string. Falls back to EMAIL_ALLOWED_SENDERS. When empty, senderPolicy decides.',
+    },
+    senderPolicy: {
+      type: "string",
+      enum: ["allowlist", "unrestricted"],
+      description:
+        'How the sender is restricted when allowedSenders is empty (EMAIL_SENDER_POLICY). "allowlist" (default) narrows sends to the configured sender source; "unrestricted" accepts any From.',
+    },
+    brand: {
+      type: "object",
+      description:
+        "Brand styling inlined into every rendered message. Omit for the neutral default layout.",
+      properties: {
+        accent: {
+          type: "string",
+          description: 'Header-band background and body link color (e.g. "#FF3621").',
+        },
+        onAccent: {
+          type: "string",
+          description: "Text and logo color rendered on the accent band. Defaults to white.",
+        },
+        fontFamily: {
+          type: "string",
+          description: 'Body font stack (e.g. "Inter, ui-sans-serif, system-ui, sans-serif").',
+        },
+        name: {
+          type: "string",
+          description: "Product / display name used as the header text and the logo alt text.",
+        },
+        logoUrl: {
+          type: "string",
+          description:
+            "Logo image for the header band. Only an http(s): or data: URL renders; other values are dropped because a mail client cannot load them.",
+        },
+      },
+      required: ["accent", "fontFamily"],
     },
   },
 };
 
-/** Parse the `SMTP_SECURE` env / config flag, defaulting to `port === 465`. */
+/** Parse the `SMTP_SECURE` env / config flag, defaulting by port. */
 function resolveSecure(flag: boolean | undefined, port: number): boolean {
   if (typeof flag === "boolean") return flag;
-  return object.toBoolean(process.env.SMTP_SECURE) ?? port === 465;
+  return object.toBoolean(process.env.SMTP_SECURE) ?? port === IMPLICIT_TLS_SMTP_PORT;
+}
+
+/** Parse the `EMAIL_SENDER_POLICY` env / config value, defaulting to deny-by-default. */
+function resolveSenderPolicy(policy: SenderPolicy | undefined): SenderPolicy {
+  const raw = policy ?? process.env.EMAIL_SENDER_POLICY?.trim().toLowerCase();
+  if (raw === "unrestricted") return "unrestricted";
+  if (raw === undefined || raw === "" || raw === "allowlist") return "allowlist";
+  throw ValidationError.invalidValue("senderPolicy", raw, '"allowlist" or "unrestricted"');
+}
+
+/**
+ * Effective allow-list for an `"allowlist"` policy with no explicit patterns:
+ * the sender source itself, so a configured domain or fixed address is the
+ * boundary rather than "anything goes". Yields nothing when neither is set,
+ * which only happens in outbox mode (where the sender falls back to the
+ * on-behalf-of user's own address and cannot be enumerated up front).
+ */
+function impliedSenderPatterns(domain: string | undefined, from: string | undefined): string[] {
+  const patterns: string[] = [];
+  if (from) patterns.push(from.trim().toLowerCase());
+  if (domain) patterns.push(`*@${domain.trim().toLowerCase()}`);
+  return patterns;
 }
 
 /** Whether `EMAIL_OUTBOX_MODE` explicitly opts into the file/outbox fallback. */
@@ -194,6 +293,11 @@ function missingSmtpFields(
  * outbox falls back to the OBO user's own address). Partial SMTP
  * configuration or a send with no credentials and no outbox opt-in
  * throws.
+ *
+ * The sender allow-list is resolved here too: under the default
+ * `"allowlist"` policy an empty list is filled in from the sender source,
+ * so a deployment that only sets `EMAIL_DOMAIN` still rejects a `From` on
+ * any other domain. See {@link SenderPolicy}.
  */
 export function resolveEmailConfig(config: EmailPluginConfig = {}): ResolvedEmailConfig {
   const smtp = config.smtp ?? {};
@@ -202,13 +306,19 @@ export function resolveEmailConfig(config: EmailPluginConfig = {}): ResolvedEmai
   const pass = smtp.password ?? process.env.SMTP_PASSWORD;
   const domain = config.domain ?? process.env.EMAIL_DOMAIN;
   const from = config.from ?? process.env.EMAIL_FROM;
-  const allowedSenders = parseAllowedSenders(
+  const senderPolicy = resolveSenderPolicy(config.senderPolicy);
+  const configuredSenders = parseAllowedSenders(
     config.allowedSenders ?? process.env.EMAIL_ALLOWED_SENDERS,
   );
+  const allowedSenders =
+    configuredSenders.length > 0 || senderPolicy === "unrestricted"
+      ? configuredSenders
+      : impliedSenderPatterns(domain, from);
   const sender: ResolvedSender = {
     ...(domain ? { domain } : {}),
     ...(from ? { from } : {}),
     allowedSenders,
+    senderPolicy,
     ...(config.brand ? { brand: config.brand } : {}),
   };
 
@@ -216,19 +326,18 @@ export function resolveEmailConfig(config: EmailPluginConfig = {}): ResolvedEmai
   const hasAnySmtp = Boolean(host || user || pass);
 
   if (hasAnySmtp && !hasAllSmtp) {
-    throw new Error(
-      `email: incomplete SMTP configuration - set ${missingSmtpFields(host, user, pass).join(", ")}`,
-    );
+    throw ValidationError.missingEnvVars(missingSmtpFields(host, user, pass));
   }
 
   if (hasAllSmtp) {
     if (!domain && !from) {
-      throw new Error(
-        "email: SMTP is configured but no sender source - set EMAIL_DOMAIN (to derive <user>@<domain>) or EMAIL_FROM (a fixed address)",
+      throw ConfigurationError.resourceNotFound(
+        "Email sender source",
+        "Set EMAIL_DOMAIN to derive <user-local-part>@<domain>, or EMAIL_FROM for a fixed address.",
       );
     }
     const portRaw = smtp.port ?? Number(process.env.SMTP_PORT);
-    const port = Number.isFinite(portRaw) && portRaw ? Number(portRaw) : 587;
+    const port = Number.isFinite(portRaw) && portRaw ? Number(portRaw) : DEFAULT_SMTP_PORT;
     return {
       mode: "smtp",
       host: host!,
@@ -240,8 +349,9 @@ export function resolveEmailConfig(config: EmailPluginConfig = {}): ResolvedEmai
   }
 
   if (!isOutboxModeEnabled()) {
-    throw new Error(
-      `email: SMTP is not configured - set ${SMTP_REQUIRED_FIELDS.join(", ")} (or EMAIL_OUTBOX_MODE=1 for local outbox testing)`,
+    throw ConfigurationError.invalidConnection(
+      "SMTP",
+      `Set ${SMTP_REQUIRED_FIELDS.join(", ")}, or EMAIL_OUTBOX_MODE=1 to write messages to a local outbox instead.`,
     );
   }