@dbx-tools/email 0.1.9

package/README.md

@@ -0,0 +1,174 @@
+# @dbx-tools/node-email
+
+Server-side email runtime, Mastra tool, 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
+[`@dbx-tools/shared-email`](../../shared/email).
+
+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.
+- 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.
+- Markdown-to-HTML rendering with a small email layout, inline styles, metadata,
+  and attachment summaries.
+
+## Register The AppKit Plugin
+
+```ts
+import { createApp, lakebase, server } from "@databricks/appkit";
+import { plugin as emailPlugin, tool as emailTool } from "@dbx-tools/node-email";
+import { agents, plugin as mastraPlugin } from "@dbx-tools/node-appkit-mastra";
+
+const support = agents.createAgent({
+  instructions: "Draft emails, but wait for approval before sending.",
+  tools: () => ({ send_email: emailTool.emailTool() }),
+});
+
+await createApp({
+  plugins: [
+    server(),
+    lakebase(),
+    emailPlugin.email(),
+    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.
+
+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.
+
+## Send Without An Agent
+
+```ts
+import { transport } from "@dbx-tools/node-email";
+
+const result = await transport.sendEmail(
+  {
+    to: ["alice@example.com"],
+    cc: ["team@example.com"],
+    subject: "Daily report",
+    body: "# Report\nEverything completed.",
+    attachments: [{ filename: "report.csv", content: "a,b\n1,2\n" }],
+  },
+  "reports@example.com",
+);
+```
+
+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.
+
+## Resolve SMTP Or Outbox Mode
+
+```ts
+import { config, transport } from "@dbx-tools/node-email";
+
+const resolved = config.resolveEmailConfig({
+  smtp: { host: "smtp.example.com", user: "apikey", password: secret },
+  domain: "mail.example.com",
+});
+
+const runtime = transport.getEmailRuntime(resolved);
+```
+
+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`.
+
+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`.
+
+Use SMTP mode for deployed apps. Use outbox mode for local demos, automated
+tests, and development loops where sending real mail would be risky.
+
+## 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:
+
+- the concrete sender addresses the current user may choose;
+- the default sender address;
+- whether the list was restricted by policy.
+
+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.
+
+## Derive And Restrict Senders
+
+```ts
+import { sender } from "@dbx-tools/node-email";
+
+const from = sender.resolveSenderAddress({
+  userEmail: "alice@databricks.com",
+  domain: "mail.example.com",
+});
+
+sender.assertSenderAllowed(from, ["*@mail.example.com", "alerts@example.com"]);
+```
+
+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.
+
+## Render Markdown Email
+
+```ts
+import { emailHtml, markdown } from "@dbx-tools/node-email";
+
+const html = emailHtml.renderEmailHtml({
+  subject: "Incident update",
+  body: 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.
+
+## Use The Outbox In Tests
+
+```ts
+import { outbox } from "@dbx-tools/node-email";
+
+await outbox.writeOutboxEmail({
+  dir: "tmp/email-outbox",
+  message,
+  from: "bot@example.com",
+});
+```
+
+Outbox files are HTML previews with metadata in the header. Attachments are
+listed in the preview, but attachment bytes are not copied to disk.
+
+## 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()`.
+- `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.
+
+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

@@ -0,0 +1,16 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as config from "./src/config";
+export * as emailHtml from "./src/email-html";
+export * as markdown from "./src/markdown";
+export * as outbox from "./src/outbox";
+export * as plugin from "./src/plugin";
+export * as sender from "./src/sender";
+export * as tool from "./src/tool";
+export * as transport from "./src/transport";
+export type { SmtpConfig, EmailPluginConfig, ResolvedSmtpConfig, ResolvedFileConfig, ResolvedEmailConfig } from "./src/config";
+export type { EmailHtmlOptions } from "./src/email-html";
+export type { EmailToolOptions } from "./src/tool";
+export type { EmailRuntime } from "./src/transport";

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@dbx-tools/email",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "workspaces/node/email"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.5",
+    "@types/json-schema": "^7",
+    "@types/node": "^24.6.0",
+    "@types/nodemailer": "^7",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@databricks/appkit": "^0.43.0",
+    "@mastra/core": "^1.47.0",
+    "juice": "^12.1.1",
+    "marked": "^18.0.5",
+    "nodemailer": "^7.0.13",
+    "@dbx-tools/shared-core": "0.1.9",
+    "@dbx-tools/shared-email": "0.1.9"
+  },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "version": "0.1.9",
+  "types": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "dbxToolsConfig": {
+    "tags": [
+      "node"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  }
+}

package/src/config.ts

@@ -0,0 +1,241 @@
+/**
+ * SMTP configuration for the email plugin: the typed
+ * {@link EmailPluginConfig} (the plugin's slice of AppKit config), the
+ * JSON Schema the manifest publishes for it, and {@link resolveEmailConfig}
+ * which layers that config over environment defaults into the concrete
+ * {@link ResolvedEmailConfig} the runtime needs.
+ *
+ * Two modes fall out of the resolution. When SMTP credentials (host +
+ * user + password) are all present it resolves to `mode: "smtp"` and
+ * mail is sent for real. When they are absent and `EMAIL_OUTBOX_MODE`
+ * is explicitly enabled it resolves to `mode: "file"` (an "outbox")
+ * and each message is written to disk as HTML instead of sent. Any
+ * partial SMTP configuration or a send attempt with no credentials and
+ * no outbox opt-in throws.
+ *
+ * Precedence per field: explicit plugin config wins, then the matching
+ * environment variable. Env names are unprefixed because the app talks
+ * 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.
+ */
+import type { BasePluginConfig } from "@databricks/appkit";
+import type { JSONSchema7 } from "json-schema";
+import { resolve } from "node:path";
+import { parseAllowedSenders } from "./sender";
+
+/** 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. */
+  port?: number;
+  /** Use a TLS-on-connect socket (`SMTP_SECURE`). Defaults to `port === 465`. */
+  secure?: boolean;
+  /** SMTP auth username (`SMTP_USER`). */
+  user?: string;
+  /** SMTP auth password / API key (`SMTP_PASSWORD`). */
+  password?: string;
+}
+
+/** AppKit config accepted by the email plugin. */
+export interface EmailPluginConfig extends BasePluginConfig {
+  /** SMTP connection + credentials. Omit to run in file/outbox mode. */
+  smtp?: SmtpConfig;
+  /**
+   * Domain used to build the sender address from the on-behalf-of user
+   * (`<local-part>@<domain>`). Falls back to `EMAIL_DOMAIN`. Required in
+   * SMTP mode unless {@link from} is set; optional in file mode (the
+   * outbox falls back to the user's own email address).
+   */
+  domain?: string;
+  /**
+   * Explicit `From` address. When set, the sender is used verbatim and
+   * the per-user derivation is skipped. Falls back to `EMAIL_FROM`.
+   */
+  from?: string;
+  /**
+   * Directory for the file/outbox fallback. Falls back to
+   * `EMAIL_OUTBOX_DIR`, then `<cwd>/tmp`. Only used when SMTP
+   * credentials are absent.
+   */
+  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.
+   */
+  allowedSenders?: string | string[];
+}
+
+/** Sender source shared by both resolved modes. */
+interface ResolvedSender {
+  /** Sender domain; present whenever {@link from} is absent. */
+  domain?: string;
+  /** Explicit sender override; present skips per-user derivation. */
+  from?: string;
+  /**
+   * Normalized sender allow-list (see {@link EmailPluginConfig.allowedSenders}).
+   * Empty means no restriction.
+   */
+  allowedSenders: string[];
+}
+
+/** Resolved config for real SMTP delivery. */
+export interface ResolvedSmtpConfig extends ResolvedSender {
+  mode: "smtp";
+  host: string;
+  port: number;
+  secure: boolean;
+  auth: { user: string; pass: string };
+}
+
+/** Resolved config for the file/outbox fallback (no SMTP credentials). */
+export interface ResolvedFileConfig extends ResolvedSender {
+  mode: "file";
+  /** Absolute directory messages are written under. */
+  outDir: string;
+}
+
+/** Concrete, validated config the runtime dispatches through. */
+export type ResolvedEmailConfig = ResolvedSmtpConfig | ResolvedFileConfig;
+
+/** JSON Schema published on the manifest's `config.schema`. */
+export const EMAIL_CONFIG_SCHEMA: JSONSchema7 = {
+  type: "object",
+  properties: {
+    smtp: {
+      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)." },
+        secure: {
+          type: "boolean",
+          description: "TLS-on-connect socket (default: port === 465).",
+        },
+        user: { type: "string", description: "SMTP auth username." },
+        password: { type: "string", description: "SMTP auth password / API key." },
+      },
+    },
+    domain: {
+      type: "string",
+      description:
+        "Domain for the derived sender address (<user-local-part>@<domain>). Falls back to EMAIL_DOMAIN.",
+    },
+    from: {
+      type: "string",
+      description: "Explicit From address; skips per-user derivation. Falls back to EMAIL_FROM.",
+    },
+    outDir: {
+      type: "string",
+      description:
+        "Directory for the file/outbox fallback when SMTP is unconfigured. Falls back to EMAIL_OUTBOX_DIR, then <cwd>/tmp.",
+    },
+    allowedSenders: {
+      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.',
+    },
+  },
+};
+
+/** Parse the `SMTP_SECURE` env / config flag, defaulting to `port === 465`. */
+function resolveSecure(flag: boolean | undefined, port: number): boolean {
+  if (typeof flag === "boolean") return flag;
+  const env = process.env["SMTP_SECURE"];
+  if (env !== undefined) return /^(1|true|yes)$/i.test(env.trim());
+  return port === 465;
+}
+
+/** Whether `EMAIL_OUTBOX_MODE` explicitly opts into the file/outbox fallback. */
+function isOutboxModeEnabled(): boolean {
+  const env = process.env["EMAIL_OUTBOX_MODE"];
+  return env !== undefined && /^(1|true|yes)$/i.test(env.trim());
+}
+
+const SMTP_REQUIRED_FIELDS = ["SMTP_HOST", "SMTP_USER", "SMTP_PASSWORD"] as const;
+
+/** List env keys for SMTP fields that are unset in the resolved credential set. */
+function missingSmtpFields(
+  host: string | undefined,
+  user: string | undefined,
+  pass: string | undefined,
+): string[] {
+  const values = [host, user, pass] as const;
+  return SMTP_REQUIRED_FIELDS.filter((_, index) => !values[index]);
+}
+
+/**
+ * Resolve plugin config over environment defaults.
+ *
+ * When SMTP host + user + password are all present, returns `mode:
+ * "smtp"` for real delivery (and throws if no sender source - domain or
+ * from - is configured, since SMTP can't derive one from nothing).
+ * When all three are absent and `EMAIL_OUTBOX_MODE` is enabled, returns
+ * `mode: "file"` so the runtime writes messages to the outbox directory
+ * for local testing; in that mode a sender source is optional (the
+ * 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.
+ */
+export function resolveEmailConfig(config: EmailPluginConfig = {}): ResolvedEmailConfig {
+  const smtp = config.smtp ?? {};
+  const host = smtp.host ?? process.env["SMTP_HOST"];
+  const user = smtp.user ?? process.env["SMTP_USER"];
+  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(
+    config.allowedSenders ?? process.env["EMAIL_ALLOWED_SENDERS"],
+  );
+  const sender: ResolvedSender = {
+    ...(domain ? { domain } : {}),
+    ...(from ? { from } : {}),
+    allowedSenders,
+  };
+
+  const hasAllSmtp = Boolean(host && user && pass);
+  const hasAnySmtp = Boolean(host || user || pass);
+
+  if (hasAnySmtp && !hasAllSmtp) {
+    throw new Error(
+      `email: incomplete SMTP configuration - set ${missingSmtpFields(host, user, pass).join(", ")}`,
+    );
+  }
+
+  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)",
+      );
+    }
+    const portRaw = smtp.port ?? Number(process.env["SMTP_PORT"]);
+    const port = Number.isFinite(portRaw) && portRaw ? Number(portRaw) : 587;
+    return {
+      mode: "smtp",
+      host: host!,
+      port,
+      secure: resolveSecure(smtp.secure, port),
+      auth: { user: user!, pass: pass! },
+      ...sender,
+    };
+  }
+
+  if (!isOutboxModeEnabled()) {
+    throw new Error(
+      `email: SMTP is not configured - set ${SMTP_REQUIRED_FIELDS.join(", ")} (or EMAIL_OUTBOX_MODE=1 for local outbox testing)`,
+    );
+  }
+
+  const outDir = resolve(
+    config.outDir ?? process.env["EMAIL_OUTBOX_DIR"] ?? resolve(process.cwd(), "tmp"),
+  );
+  return { mode: "file", outDir, ...sender };
+}

package/src/email-html.ts

@@ -0,0 +1,130 @@
+/**
+ * Email HTML assembly: render a markdown body into a branded, responsive
+ * email layout and inline the stylesheet with `juice`.
+ *
+ * The layout is the classic email-safe pattern (a centered 600px
+ * table-based container with a header band, content card, and optional
+ * footer) - the same shape MJML emits, hand-built here because MJML's
+ * toolchain pulls fast-moving browser-data deps (caniuse-lite,
+ * baseline-browser-mapping) that are awkward to install behind a
+ * locked-down registry. Inlining matters because real clients (Gmail,
+ * Outlook) strip `<style>` blocks and ignore class selectors; the same
+ * renderer feeds both the local outbox preview and the SMTP HTML part,
+ * so a browser and an inbox show the same thing.
+ */
+
+import { string } from "@dbx-tools/shared-core";
+import juice from "juice";
+import { markdownToHtml } from "./markdown";
+
+/** Accent color for the header band and links. */
+const ACCENT = "#0b6bcb";
+
+/** Escape HTML-significant characters (re-exported from `@dbx-tools/shared`). */
+export const escapeHtml = string.escapeHtml;
+
+/**
+ * Content stylesheet inlined onto the markdown body (juice maps these
+ * onto elements). Outer layout styling is written inline directly so it
+ * survives even if inlining is skipped; the `@media` rule is preserved
+ * by juice for clients that honor it.
+ */
+const CONTENT_CSS = `
+    .email-body { font-size: 15px; line-height: 1.55; color: #1a1a1a; }
+    .email-body p { margin: 0 0 1rem; }
+    .email-body a { color: ${ACCENT}; }
+    .email-body h1, .email-body h2, .email-body h3 { margin: 1.4rem 0 0.6rem; line-height: 1.25; }
+    .email-body ul, .email-body ol { margin: 0 0 1rem; padding-left: 1.4rem; }
+    .email-body table { border-collapse: collapse; margin: 1rem 0; width: 100%; font-size: 14px; }
+    .email-body th, .email-body td { border: 1px solid #d0d7de; padding: 6px 10px; text-align: left; }
+    .email-body th { background: #f6f8fa; font-weight: 600; }
+    .email-body code { background: #f1f3f5; padding: 2px 5px; border-radius: 4px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.9em; }
+    .email-body pre { background: #f1f3f5; padding: 12px; border-radius: 6px; overflow-x: auto; }
+    .email-body pre code { background: none; padding: 0; }
+    .email-body blockquote { margin: 1rem 0; padding: 0 1rem; color: #57606a; border-left: 3px solid #d0d7de; }
+    .email-body img { max-width: 100%; height: auto; }
+    .meta { border-collapse: collapse; font-size: 13px; margin-bottom: 4px; }
+    .meta th { text-align: left; padding: 2px 12px 2px 0; vertical-align: top; color: #6b7280; font-weight: 600; white-space: nowrap; }
+    .meta td { padding: 2px 0; color: #374151; }
+    @media only screen and (max-width: 620px) {
+      .container { width: 100% !important; }
+      .gutter { padding-left: 20px !important; padding-right: 20px !important; }
+    }`;
+
+/** Options for {@link renderEmailHtml}. */
+export interface EmailHtmlOptions {
+  /** Markdown body. Rendered to HTML, then wrapped in the layout. */
+  body: string;
+  /** Header-band title and document `<title>`. Defaults to "Message". */
+  subject?: string;
+  /**
+   * Optional `[label, value]` envelope rows shown above the body (used
+   * by the outbox preview; omitted for SMTP sends, where the mail client
+   * shows the envelope itself).
+   */
+  headers?: ReadonlyArray<readonly [string, string]>;
+  /** Optional small-print footer line. Omitted when unset. */
+  footer?: string;
+}
+
+/** Render the optional envelope-header table block. */
+function metaBlock(headers: EmailHtmlOptions["headers"]): string {
+  if (!headers || headers.length === 0) return "";
+  const rows = headers
+    .map(([label, value]) => `<tr><th>${escapeHtml(label)}</th><td>${escapeHtml(value)}</td></tr>`)
+    .join("");
+  return `<table role="presentation" class="meta"><tbody>${rows}</tbody></table>`;
+}
+
+/** Render the optional footer row. */
+function footerRow(footer: string | undefined): string {
+  if (!footer) return "";
+  return `
+          <tr>
+            <td class="gutter" style="padding: 16px 32px; border-top: 1px solid #eaecef; color: #9aa0a6; font-size: 12px; line-height: 1.5;">
+              ${escapeHtml(footer)}
+            </td>
+          </tr>`;
+}
+
+/**
+ * Render `body` (markdown) into a complete, style-inlined email document
+ * using the branded responsive layout.
+ */
+export function renderEmailHtml(opts: EmailHtmlOptions): string {
+  const title = opts.subject?.trim() || "Message";
+  const doc = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="light only" />
+    <title>${escapeHtml(title)}</title>
+    <style>${CONTENT_CSS}
+    </style>
+  </head>
+  <body style="margin: 0; padding: 0; background-color: #f4f5f7; -webkit-text-size-adjust: 100%;">
+    <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="background-color: #f4f5f7;">
+      <tr>
+        <td align="center" style="padding: 24px 12px;">
+          <table role="presentation" class="container" width="600" cellpadding="0" cellspacing="0" style="width: 600px; max-width: 100%; background-color: #ffffff; border-radius: 10px; overflow: hidden; box-shadow: 0 1px 3px rgba(0,0,0,0.08); font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;">
+            <tr>
+              <td class="gutter" style="padding: 20px 32px; background-color: ${ACCENT};">
+                <span style="color: #ffffff; font-size: 18px; font-weight: 700; line-height: 1.3;">${escapeHtml(title)}</span>
+              </td>
+            </tr>
+            <tr>
+              <td class="gutter" style="padding: 24px 32px 8px;">
+                ${metaBlock(opts.headers)}
+                <div class="email-body">${markdownToHtml(opts.body)}</div>
+              </td>
+            </tr>${footerRow(opts.footer)}
+          </table>
+        </td>
+      </tr>
+    </table>
+  </body>
+</html>
+`;
+  return juice(doc);
+}

package/src/juice.d.ts

@@ -0,0 +1,17 @@
+// Minimal ambient types for `juice` (no `@types/juice` is published).
+// We only use the default export: inline a stylesheet found in the
+// document's <style> tags into element `style` attributes.
+declare module "juice" {
+  interface JuiceOptions {
+    applyStyleTags?: boolean;
+    removeStyleTags?: boolean;
+    preserveImportant?: boolean;
+    preserveMediaQueries?: boolean;
+    preserveFontFaces?: boolean;
+    inlinePseudoElements?: boolean;
+    xmlMode?: boolean;
+    [option: string]: unknown;
+  }
+  function juice(html: string, options?: JuiceOptions): string;
+  export = juice;
+}

package/src/markdown.ts

@@ -0,0 +1,92 @@
+/**
+ * Server-side markdown -> HTML rendering for email bodies. The model
+ * drafts bodies in markdown; this turns them into real HTML (GFM tables,
+ * lists, code, links). {@link normalizeMarkdown} first repairs the two
+ * structures LLMs most often emit as plain text instead of markdown -
+ * `=====` divider rules and pipe tables missing their `| --- |`
+ * separator row - so they render as a `<hr>` / `<table>` rather than
+ * literal text. The prompt steers the model away from ASCII art; this is
+ * the belt-and-suspenders fallback.
+ */
+
+import { marked } from "marked";
+
+/** A line of only `=` or `_` (length >= 3): an ASCII divider rule. */
+function isAsciiRule(line: string): boolean {
+  return /^[ \t]*[=_]{3,}[ \t]*$/.test(line);
+}
+
+/** A line that participates in a markdown pipe table (has a `|`). */
+function isPipeRow(line: string): boolean {
+  return line.includes("|") && line.trim().length > 0;
+}
+
+/** A markdown table separator row, e.g. `| --- | :--: |`. */
+function isSeparatorRow(line: string): boolean {
+  return /^[ \t]*\|?[ \t]*:?-{2,}:?[ \t]*(\|[ \t]*:?-{2,}:?[ \t]*)+\|?[ \t]*$/.test(line);
+}
+
+/** Column count of a pipe row (outer pipes optional). */
+function pipeColumns(line: string): number {
+  return line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").length;
+}
+
+/** A GFM separator row with `columns` cells. */
+function separatorRow(columns: number): string {
+  return `| ${Array.from({ length: columns }, () => "---").join(" | ")} |`;
+}
+
+/**
+ * Repair common LLM "looks-like-markdown-but-isn't" output: convert
+ * standalone `=====` / `_____` rules to a `---` thematic break (leaving
+ * genuine setext-heading underlines intact), and insert a `| --- |`
+ * separator after the first row of a pipe block that lacks one so GFM
+ * renders it as a table.
+ */
+export function normalizeMarkdown(src: string): string {
+  const lines = src.split("\n");
+  const out: string[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    const prev = i > 0 ? lines[i - 1]! : "";
+    const next = i + 1 < lines.length ? lines[i + 1]! : "";
+
+    if (isAsciiRule(line)) {
+      // A run of `=` directly under a non-blank text line is a setext H1
+      // underline - keep it. Anything else is a decorative divider.
+      const isSetextUnderline =
+        /^[ \t]*={3,}[ \t]*$/.test(line) && prev.trim() !== "" && !isPipeRow(prev);
+      out.push(isSetextUnderline ? line : "---");
+      continue;
+    }
+
+    // First row of a pipe block (prev is not itself a pipe row) followed
+    // by another aligned pipe row, with no separator and no `###` bar-
+    // chart fill: treat as a table header and inject the separator.
+    const startsPipeBlock = isPipeRow(line) && !isPipeRow(prev);
+    if (
+      startsPipeBlock &&
+      isPipeRow(next) &&
+      !isSeparatorRow(next) &&
+      !/#{3,}/.test(line) &&
+      pipeColumns(line) >= 2 &&
+      pipeColumns(line) === pipeColumns(next)
+    ) {
+      out.push(line);
+      out.push(separatorRow(pipeColumns(line)));
+      continue;
+    }
+
+    out.push(line);
+  }
+  return out.join("\n");
+}
+
+/** Render a markdown body to an HTML fragment (GFM tables enabled). */
+export function markdownToHtml(body: string): string {
+  return marked.parse(normalizeMarkdown(body), {
+    async: false,
+    gfm: true,
+    breaks: true,
+  });
+}

package/src/outbox.ts

@@ -0,0 +1,64 @@
+/**
+ * Filesystem outbox for the no-SMTP fallback: {@link writeOutboxEmail}
+ * persists one drafted message as a standalone HTML file under
+ * `<dir>/<from>/<timestamp>-<subject-slug>.html` instead of sending it.
+ * This lets the approval flow and agents be exercised end-to-end with
+ * zero email configuration - open the file in a browser to see exactly
+ * what would have gone out (the HTML matches the SMTP send, headers
+ * table aside). The body is rendered + style-inlined by
+ * {@link renderEmailHtml}. Attachments are listed by filename in the
+ * header table but not written to disk - the outbox previews the
+ * envelope, it doesn't reproduce the wire payload.
+ */
+
+import type { EmailMessage } from "@dbx-tools/shared-email";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { renderEmailHtml } from "./email-html";
+
+/** Filesystem-safe slug of the subject for the file name. */
+function subjectSlug(subject: string): string {
+  const slug = subject
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return (slug || "email").slice(0, 48);
+}
+
+/** The envelope rows shown above the body in the preview file. */
+function headerRows(message: EmailMessage, from: string): Array<readonly [string, string]> {
+  const rows: Array<readonly [string, string | undefined]> = [
+    ["From", from],
+    ["To", message.to.join(", ")],
+    ["Cc", message.cc?.join(", ")],
+    ["Bcc", message.bcc?.join(", ")],
+    ["Subject", message.subject],
+    ["Attachments", message.attachments?.map((att) => att.filename).join(", ")],
+    ["Date", new Date().toISOString()],
+  ];
+  return rows.filter((row): row is [string, string] => Boolean(row[1]));
+}
+
+/**
+ * Write one message as HTML under `<dir>/<from>/` and return the
+ * absolute path. The per-sender folder mirrors the SMTP `From`, so test
+ * output groups by who the message would have been sent as.
+ */
+export async function writeOutboxEmail(
+  message: EmailMessage,
+  from: string,
+  dir: string,
+): Promise<string> {
+  const folder = resolve(dir, from);
+  await mkdir(folder, { recursive: true });
+  const path = join(folder, `${Date.now()}-${subjectSlug(message.subject)}.html`);
+  const html = renderEmailHtml({
+    subject: message.subject,
+    headers: headerRows(message, from),
+    body: message.body,
+    footer: "Local outbox preview - written to disk, not sent (no SMTP credentials configured).",
+  });
+  await writeFile(path, html, "utf8");
+  return path;
+}

package/src/plugin.ts

@@ -0,0 +1,161 @@
+/**
+ * AppKit plugin (registered name: `email`) that owns the SMTP runtime
+ * for outbound mail. Registering it validates the SMTP configuration
+ * and verifies connectivity at startup, so a bad host / credential
+ * surfaces in the boot logs instead of on the first approved send. The
+ * actual send happens through the approval-gated {@link emailTool}
+ * spread into an agent; this plugin primes the shared transport the
+ * tool reuses and exposes a direct {@link sendEmail} for non-agent
+ * callers.
+ *
+ * Configuration is the manifest-published {@link EmailPluginConfig}
+ * (SMTP host/port/credentials, sender domain or explicit `from`, and an
+ * optional `allowedSenders` restriction), with unprefixed `SMTP_*` /
+ * `EMAIL_*` environment fallbacks.
+ *
+ * The plugin mounts one route under its base path (`/api/email`):
+ * `GET /senders` returns the permitted `From` options for the calling
+ * user, so a compose UI can offer them in a dropdown.
+ */
+
+import {
+  getExecutionContext,
+  Plugin,
+  toPlugin,
+  type IAppRouter,
+  type PluginManifest,
+} from "@databricks/appkit";
+import type { EmailMessage, EmailResult, EmailSenders } from "@dbx-tools/shared-email";
+import { error, log } from "@dbx-tools/shared-core";
+import type express from "express";
+import { EMAIL_CONFIG_SCHEMA, type EmailPluginConfig } from "./config";
+import { isSenderAllowed, listSenderOptions, resolveSenderAddress } from "./sender";
+import { getEmailRuntime, sendEmail } from "./transport";
+
+/** Mount-relative route (under `/api/email`) for the sender-options lookup. */
+const SENDERS_ROUTE = "/senders";
+
+/**
+ * AppKit plugin that configures and verifies the SMTP transport used by
+ * the `send_email` tool.
+ */
+export class EmailPlugin extends Plugin<EmailPluginConfig> {
+  static manifest = {
+    name: "email",
+    displayName: "Email",
+    description:
+      "Sends approval-gated email over SMTP, with the sender derived from " +
+      "the on-behalf-of user's address on a configured domain.",
+    stability: "beta",
+    resources: {
+      required: [],
+      optional: [],
+    },
+    config: { schema: EMAIL_CONFIG_SCHEMA },
+  } satisfies PluginManifest<"email">;
+
+  private logger = log.logger(this);
+
+  /**
+   * Prime the shared runtime from this plugin's config (over env). In
+   * SMTP mode, verify connectivity - a failed verify is logged as a
+   * warning rather than thrown, so the app still boots and the first
+   * send surfaces the real error via the approval flow. With no SMTP
+   * credentials the runtime is in file/outbox mode (only when
+   * `EMAIL_OUTBOX_MODE` is set), logged here so it's obvious mail is
+   * being written to disk rather than sent.
+   */
+  override async setup(): Promise<void> {
+    const { transporter, config } = getEmailRuntime(this.config);
+    if (config.mode === "file") {
+      this.logger.warn("outbox:enabled", {
+        dir: config.outDir,
+        reason: "no SMTP credentials configured; emails are written to disk instead of sent",
+      });
+      return;
+    }
+    try {
+      await transporter?.verify();
+      this.logger.info("smtp:ready", {
+        host: config.host,
+        port: config.port,
+        secure: config.secure,
+      });
+    } catch (err) {
+      this.logger.warn("smtp:unverified", { error: error.errorMessage(err) });
+    }
+  }
+
+  /**
+   * Expose the sender-options lookup so UI compose views can populate a
+   * `From` dropdown from the configured allow-list. Mounted under the
+   * plugin base path, i.e. `GET /api/email/senders`. Runs in the OBO
+   * user scope so domain wildcards resolve against the caller's own
+   * local part.
+   */
+  override injectRoutes(router: IAppRouter): void {
+    router.get(SENDERS_ROUTE, (req, res, next) => {
+      this.userScopedSelf(req)
+        .listSenders()
+        .then((senders) => res.json(senders))
+        .catch(next);
+    });
+  }
+
+  override exports() {
+    return {
+      /**
+       * Send a message immediately from `from` through the shared
+       * transport, bypassing the approval flow. For agent-driven sends
+       * use {@link emailTool} instead.
+       */
+      sendEmail: (message: EmailMessage, from: string): Promise<EmailResult> =>
+        sendEmail(message, from),
+      /**
+       * Sender options for the current user (the `GET /senders` payload).
+       * AppKit wraps this with `asUser(req)` for OBO scoping.
+       */
+      listSenders: (): Promise<EmailSenders> => this.listSenders(),
+    };
+  }
+
+  /**
+   * Compute the `From` options offered to the current user: the concrete
+   * addresses the configured allow-list permits (domain wildcards
+   * expanded against the OBO user's local part), the default among them,
+   * and whether the list is an enforced restriction. See
+   * {@link listSenderOptions}.
+   */
+  private async listSenders(): Promise<EmailSenders> {
+    const { config } = getEmailRuntime();
+    const ctx = getExecutionContext();
+    const userEmail = "isUserContext" in ctx ? ctx.userEmail : undefined;
+    const senders = listSenderOptions(config, userEmail);
+    // Prefer the address a send would actually default to; fall back to
+    // the first offered option when that can't be resolved / permitted.
+    let defaultSender = senders[0];
+    try {
+      const resolved = resolveSenderAddress(config, userEmail).toLowerCase();
+      if (isSenderAllowed(resolved, config.allowedSenders)) defaultSender = resolved;
+    } catch {
+      // Keep the first offered option (or none) as the default.
+    }
+    return {
+      senders,
+      ...(defaultSender ? { defaultSender } : {}),
+      restricted: config.allowedSenders.length > 0,
+    };
+  }
+
+  /**
+   * Return `this.asUser(req)` when the request carries an OBO token,
+   * otherwise `this`. Avoids the noisy AppKit "asUser without token"
+   * warning on every request in local dev; behavior is unchanged in
+   * production where a missing token means a real OBO call.
+   */
+  private userScopedSelf(req: express.Request): this {
+    return req.header("x-forwarded-access-token") ? (this.asUser(req) as this) : this;
+  }
+}
+
+export const email = toPlugin(EmailPlugin);

package/src/sender.ts

@@ -0,0 +1,152 @@
+/**
+ * Sender-address policy: turn the on-behalf-of user's email into an
+ * outbound `From`, and (optionally) restrict which addresses may send.
+ *
+ * The default `From` re-homes the local part (everything before `@`) of
+ * the OBO email on the configured sending domain, so `alice@databricks.com`
+ * through a domain of `mail.example.com` goes out as
+ * `alice@mail.example.com`. An explicit `from` short-circuits that; the
+ * file/outbox fallback (no domain) keeps the user's address verbatim so
+ * test artifacts land under a recognizable folder.
+ *
+ * When an allow-list is configured (see {@link parseAllowedSenders}) the
+ * resolved `From` is constrained to it: a pattern is either 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). {@link listSenderOptions} expands the allow-list into the
+ * concrete addresses a UI dropdown can offer for the current user.
+ */
+
+import { net } from "@dbx-tools/shared-core";
+
+import type { ResolvedEmailConfig } from "./config";
+
+/**
+ * Re-home the OBO user's local part on `domain`. Throws when no usable
+ * local part is available (e.g. a service-context call with no user).
+ */
+export function deriveSenderAddress(userEmail: string | undefined, domain: string): string {
+  const local = userEmail?.split("@")[0]?.trim();
+  if (!local) {
+    throw new Error(
+      "email: cannot derive sender address - no on-behalf-of user email is available; set `from` / EMAIL_FROM to send from a fixed address",
+    );
+  }
+  return `${local}@${domain}`;
+}
+
+/**
+ * Normalize a sender allow-list from config (a `string[]`) or an env var
+ * (a CSV / whitespace-separated string). Delegates to the shared
+ * {@link net.parseEmails} so allow-list patterns are read exactly
+ * like recipient lists elsewhere: entries are trimmed, lower-cased (so
+ * matching in {@link isSenderAllowed} is case-insensitive), and
+ * de-duplicated; empties are dropped. An empty result means "no
+ * restriction".
+ */
+export function parseAllowedSenders(raw: string | string[] | undefined): string[] {
+  return net.parseEmails(raw, { lowercase: true });
+}
+
+/** The `@domain` suffix a wildcard / bare-domain pattern matches, else null. */
+function patternDomainSuffix(pattern: string): string | null {
+  if (pattern.startsWith("*@")) return `@${pattern.slice(2)}`;
+  if (!pattern.includes("@")) return `@${pattern}`;
+  return null;
+}
+
+/** Whether `address` (already lower-cased) satisfies a single pattern. */
+function matchesPattern(address: string, pattern: string): boolean {
+  if (pattern === "*") return true;
+  const suffix = patternDomainSuffix(pattern);
+  if (suffix) return address.length > suffix.length && address.endsWith(suffix);
+  return address === pattern;
+}
+
+/**
+ * Whether `from` is permitted by the allow-list. An empty (or absent)
+ * allow-list permits everything.
+ */
+export function isSenderAllowed(from: string, patterns: string[]): boolean {
+  if (patterns.length === 0) return true;
+  const address = from.trim().toLowerCase();
+  return patterns.some((pattern) => matchesPattern(address, pattern));
+}
+
+/**
+ * Throw when `from` is not permitted by the allow-list. No-op when the
+ * allow-list is empty. The single enforcement point for the restriction
+ * (called from {@link sendEmail}), so every send path is covered whether
+ * the address was derived server-side or chosen in a UI.
+ */
+export function assertSenderAllowed(from: string, patterns: string[]): void {
+  if (!isSenderAllowed(from, patterns)) {
+    throw new Error(
+      `email: sender "${from}" is not permitted by the configured allow-list (${patterns.join(", ")})`,
+    );
+  }
+}
+
+/**
+ * Resolve the `From` address for a send from the resolved config and the
+ * current OBO user: explicit `from` wins, then `<local>@<domain>`, then
+ * (file/outbox mode only) the user's email verbatim. Throws when none of
+ * those yield an address.
+ */
+export function resolveSenderAddress(
+  config: ResolvedEmailConfig,
+  userEmail: string | undefined,
+): string {
+  if (config.from) return config.from;
+  if (config.domain) return deriveSenderAddress(userEmail, config.domain);
+  const email = userEmail?.trim();
+  if (!email) {
+    throw new Error(
+      "email: no sender address available - set `from` / EMAIL_FROM, `domain` / EMAIL_DOMAIN, or run on behalf of a user",
+    );
+  }
+  return email;
+}
+
+/**
+ * Expand the resolved config's allow-list into the concrete `From`
+ * addresses offered to the current user - the data a UI sender dropdown
+ * renders. Exact-address patterns pass through; domain wildcards
+ * (`*@domain.com` / bare `domain.com`) are concretized as
+ * `<user-local>@<domain>` and dropped when no OBO user local part is
+ * available. When no allow-list is configured, the single default sender
+ * ({@link resolveSenderAddress}) is returned when it can be resolved,
+ * else an empty list. The default resolved sender, when permitted, is
+ * ordered first.
+ */
+export function listSenderOptions(
+  config: ResolvedEmailConfig,
+  userEmail: string | undefined,
+): string[] {
+  const patterns = config.allowedSenders ?? [];
+  const local = userEmail?.split("@")[0]?.trim().toLowerCase();
+  const options: string[] = [];
+  const add = (address: string | undefined): void => {
+    if (address && !options.includes(address)) options.push(address);
+  };
+
+  // Surface the address a send would use by default first, when it can
+  // be resolved and the allow-list (if any) permits it.
+  try {
+    const fallback = resolveSenderAddress(config, userEmail);
+    if (isSenderAllowed(fallback, patterns)) add(fallback.toLowerCase());
+  } catch {
+    // No default resolvable (e.g. file mode with no user / domain / from).
+  }
+
+  for (const pattern of patterns) {
+    if (pattern === "*") continue; // "any" can't be enumerated as a choice
+    if (pattern.startsWith("*@") || !pattern.includes("@")) {
+      const domain = pattern.startsWith("*@") ? pattern.slice(2) : pattern;
+      if (local) add(`${local}@${domain}`);
+    } else {
+      add(pattern); // exact address
+    }
+  }
+  return options;
+}

package/src/tool.ts

@@ -0,0 +1,81 @@
+/**
+ * The `send_email` Mastra tool: approval-gated so a model can draft a
+ * message freely but nothing leaves the building until a human clicks
+ * Approve in the chat UI. On approval the sender is resolved (explicit
+ * `from` config, else derived from the on-behalf-of user's email) and
+ * the message is dispatched through the shared SMTP transport.
+ *
+ * The sender derivation runs inside the AppKit user scope, so
+ * `getExecutionContext()` returns the OBO user whose local-part seeds
+ * the address (see {@link deriveSenderAddress}).
+ */
+
+import { getExecutionContext } from "@databricks/appkit";
+import { email, type EmailMessage } from "@dbx-tools/shared-email";
+import { log, string } from "@dbx-tools/shared-core";
+import { createTool } from "@mastra/core/tools";
+import { resolveSenderAddress } from "./sender";
+import { getEmailRuntime, sendEmail } from "./transport";
+
+const logger = log.logger("email/tool/send-email");
+
+/** Options accepted by {@link emailTool}. */
+export interface EmailToolOptions {
+  /**
+   * Override the tool id. Defaults to `"send_email"`; the chat UI's
+   * approval gate keys off this id, so keep it unless you also teach
+   * the client about the new name.
+   */
+  id?: string;
+}
+
+/**
+ * Build the approval-gated `send_email` tool. Spread it into the agents
+ * that should be able to draft mail; it is intentionally not installed
+ * everywhere.
+ *
+ * @example
+ * ```ts
+ * import { emailTool } from "@dbx-tools/appkit-email";
+ * import { createAgent } from "@dbx-tools/appkit-mastra";
+ *
+ * const support = createAgent({
+ *   instructions: "...",
+ *   tools: () => ({ send_email: emailTool() }),
+ * });
+ * ```
+ */
+export function emailTool(opts: EmailToolOptions = {}) {
+  return createTool({
+    id: opts.id ?? "send_email",
+    description: string.toDescription(`
+      Send an email on the user's behalf. Pass one or more recipient
+      addresses (with optional cc / bcc and file attachments), a subject,
+      and a body; the user is prompted to approve the send before it goes
+      out (this tool is approval-gated). Use it only when the user
+      explicitly asks to send / forward / share something via email -
+      never autonomously. Keep subjects short and bodies self-contained:
+      the recipient has none of the chat context. Write the body in
+      GitHub-Flavored Markdown - headings, lists, and real Markdown
+      tables - not ASCII art (no "=====" dividers or space/pipe-drawn
+      tables); it is rendered to HTML before sending.
+    `),
+    inputSchema: email.emailMessageSchema,
+    outputSchema: email.emailResultSchema,
+    requireApproval: true,
+    execute: async (input) => {
+      const message = input as EmailMessage;
+      const { config } = getEmailRuntime();
+      const ctx = getExecutionContext();
+      const userEmail = "isUserContext" in ctx ? ctx.userEmail : undefined;
+      const from = resolveSenderAddress(config, userEmail);
+      const result = await sendEmail(message, from);
+      logger.info("sent", {
+        to: result.recipient,
+        from: result.from,
+        ...(result.messageId ? { messageId: result.messageId } : {}),
+      });
+      return result;
+    },
+  });
+}

package/src/transport.ts

@@ -0,0 +1,127 @@
+/**
+ * The email runtime: a lazily-built, process-wide dispatcher plus its
+ * resolved config, and {@link sendEmail} which sends one
+ * {@link EmailMessage} through it. In SMTP mode the runtime holds a
+ * memoized nodemailer transport (shared by the plugin's setup and the
+ * agent tool, so they reuse one connection pool); in file/outbox mode it
+ * holds no transport and {@link sendEmail} writes HTML to disk instead.
+ * The first caller (normally the plugin at setup) primes it with the
+ * plugin's config; later callers reuse it.
+ */
+
+import type { EmailAttachment, EmailMessage, EmailResult } from "@dbx-tools/shared-email";
+import nodemailer, { type SendMailOptions, type Transporter } from "nodemailer";
+import { resolveEmailConfig, type EmailPluginConfig, type ResolvedEmailConfig } from "./config";
+import { renderEmailHtml } from "./email-html";
+import { writeOutboxEmail } from "./outbox";
+import { assertSenderAllowed } from "./sender";
+
+/** The shared dispatcher and the config it was built from. */
+export interface EmailRuntime {
+  /** Present only in SMTP mode. */
+  transporter?: Transporter;
+  config: ResolvedEmailConfig;
+}
+
+let runtime: EmailRuntime | undefined;
+
+/**
+ * Return the shared runtime, building it on first use from the supplied
+ * config layered over environment defaults. Overrides are only read when
+ * the runtime is first created, so prime it from the plugin's config at
+ * setup; subsequent calls (e.g. the tool's `execute`) pass nothing and
+ * get the same instance.
+ */
+export function getEmailRuntime(overrides?: EmailPluginConfig): EmailRuntime {
+  if (!runtime) {
+    const config = resolveEmailConfig(overrides);
+    runtime = {
+      config,
+      ...(config.mode === "smtp"
+        ? {
+            transporter: nodemailer.createTransport({
+              host: config.host,
+              port: config.port,
+              secure: config.secure,
+              auth: config.auth,
+            }),
+          }
+        : {}),
+    };
+  }
+  return runtime;
+}
+
+/** Drop the memoized runtime so the next {@link getEmailRuntime} rebuilds it. */
+export function resetEmailRuntime(): void {
+  runtime?.transporter?.close();
+  runtime = undefined;
+}
+
+/** The comma-joined recipient string echoed back in {@link EmailResult}. */
+function recipientEcho(to: string[]): string {
+  return to.join(", ");
+}
+
+/**
+ * Map the wire-format {@link EmailAttachment}s onto nodemailer's
+ * attachment shape, dropping unset optional keys so nodemailer applies
+ * its own defaults (utf-8 encoding, filename-inferred content type). The
+ * wire fields are a deliberate subset of nodemailer's, so this is a
+ * straight structural pass-through.
+ */
+function toMailAttachments(
+  attachments: EmailAttachment[] | undefined,
+): SendMailOptions["attachments"] {
+  if (!attachments || attachments.length === 0) return undefined;
+  return attachments.map((att) => ({
+    filename: att.filename,
+    ...(att.content !== undefined ? { content: att.content } : {}),
+    ...(att.encoding !== undefined ? { encoding: att.encoding } : {}),
+    ...(att.path !== undefined ? { path: att.path } : {}),
+    ...(att.contentType !== undefined ? { contentType: att.contentType } : {}),
+  }));
+}
+
+/**
+ * Send (SMTP mode) or persist (file/outbox mode) one message from the
+ * resolved `from` address. `to` (and optional `cc` / `bcc`) each accept
+ * one or more addresses, and `attachments` are forwarded as files. The
+ * body is markdown: SMTP sends it as both a plain-text part (the raw
+ * source) and an HTML part (rendered), and the outbox embeds the
+ * rendered HTML in a document. In file mode the returned `messageId` is
+ * the path written. Throws when `to` carries no recipient, or when `from`
+ * is not permitted by the configured sender allow-list.
+ */
+export async function sendEmail(message: EmailMessage, from: string): Promise<EmailResult> {
+  if (message.to.length === 0) {
+    throw new Error("email: `to` must include at least one recipient");
+  }
+  const { config, transporter } = getEmailRuntime();
+  assertSenderAllowed(from, config.allowedSenders);
+  const recipient = recipientEcho(message.to);
+
+  if (config.mode === "file") {
+    const path = await writeOutboxEmail(message, from, config.outDir);
+    return { sent: true, recipient, from, messageId: path };
+  }
+
+  if (!transporter) throw new Error("email: SMTP transport unavailable");
+  const attachments = toMailAttachments(message.attachments);
+  const info = await transporter.sendMail({
+    from,
+    to: message.to,
+    subject: message.subject,
+    text: message.body,
+    html: renderEmailHtml({ subject: message.subject, body: message.body }),
+    ...(message.cc && message.cc.length > 0 ? { cc: message.cc } : {}),
+    ...(message.bcc && message.bcc.length > 0 ? { bcc: message.bcc } : {}),
+    ...(attachments ? { attachments } : {}),
+  });
+  return {
+    sent: true,
+    recipient,
+    from,
+    ...(info.messageId ? { messageId: info.messageId } : {}),
+  };
+}

package/tsconfig.json

@@ -0,0 +1,41 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib",
+    "alwaysStrict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "lib": [
+      "ES2022"
+    ],
+    "module": "ESNext",
+    "noEmitOnError": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "stripInternal": true,
+    "target": "ES2022",
+    "types": [
+      "node"
+    ],
+    "moduleResolution": "bundler",
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}