@dbx-tools/email 0.6.46 → 0.6.49

package/src/config.ts

@@ -25,9 +25,9 @@
  */
 import { resolve } from "node:path";
 import { ConfigurationError, ValidationError, type BasePluginConfig } from "@databricks/appkit";
-import { object } from "@dbx-tools/shared-core";
+import { env, object } from "@dbx-tools/shared-core";
 import type { JSONSchema7 } from "json-schema";
-import type { EmailBrand } from "./brand.ts";
+import { defaultEmailBrand, type EmailBrand } from "./brand.ts";
 import { parseAllowedSenders } from "./sender.ts";
 
 /** SMTP submission port used when none is configured. */
@@ -108,10 +108,9 @@ export interface EmailPluginConfig extends BasePluginConfig {
    */
   senderPolicy?: SenderPolicy;
   /**
-   * Optional brand styling (accent, font, header logo) applied to the
-   * rendered HTML of every message. Omit for the neutral default layout.
-   * Pass {@link emailBrandFromContext} to derive it from a shared
-   * `BrandContext`.
+   * Optional brand styling applied to every rendered message. Omit to use the
+   * repository's dbx-tools brand. Pass {@link emailBrandFromContext} to derive
+   * a custom value from a shared `BrandContext`.
    */
   brand?: EmailBrand;
 }
@@ -131,8 +130,8 @@ interface ResolvedSender {
   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;
+  /** Brand styling applied to rendered HTML. */
+  brand: EmailBrand;
 }
 
 /** Resolved config for real SMTP delivery. */
@@ -207,7 +206,7 @@ export const EMAIL_CONFIG_SCHEMA: JSONSchema7 = {
     brand: {
       type: "object",
       description:
-        "Brand styling inlined into every rendered message. Omit for the neutral default layout.",
+        "Brand styling applied to every React Email message. Omit to use the dbx-tools brand.",
       properties: {
         accent: {
           type: "string",
@@ -230,6 +229,13 @@ export const EMAIL_CONFIG_SCHEMA: JSONSchema7 = {
           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.",
         },
+        background: { type: "string", description: "Inbox canvas color." },
+        surface: { type: "string", description: "Message-card color." },
+        foreground: { type: "string", description: "Primary text color." },
+        muted: { type: "string", description: "Secondary text color." },
+        border: { type: "string", description: "Border and divider color." },
+        tagline: { type: "string", description: "Footer product line." },
+        website: { type: "string", description: "Optional footer website URL." },
       },
       required: ["accent", "fontFamily"],
     },
@@ -238,13 +244,12 @@ export const EMAIL_CONFIG_SCHEMA: JSONSchema7 = {
 
 /** 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 === IMPLICIT_TLS_SMTP_PORT;
+  return env.boolean(flag, "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();
+  const raw = policy ?? env.text("EMAIL_SENDER_POLICY")?.toLowerCase();
   if (raw === "unrestricted") return "unrestricted";
   if (raw === undefined || raw === "" || raw === "allowlist") return "allowlist";
   throw ValidationError.invalidValue("senderPolicy", raw, '"allowlist" or "unrestricted"');
@@ -266,7 +271,7 @@ function impliedSenderPatterns(domain: string | undefined, from: string | undefi
 
 /** Whether `EMAIL_OUTBOX_MODE` explicitly opts into the file/outbox fallback. */
 function isOutboxModeEnabled(): boolean {
-  return object.toBoolean(process.env.EMAIL_OUTBOX_MODE) ?? false;
+  return env.boolean(undefined, "EMAIL_OUTBOX_MODE") ?? false;
 }
 
 const SMTP_REQUIRED_FIELDS = ["SMTP_HOST", "SMTP_USER", "SMTP_PASSWORD"] as const;
@@ -301,25 +306,25 @@ function missingSmtpFields(
  */
 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 host = env.string(smtp.host, "SMTP_HOST") ?? undefined;
+  const user = env.string(smtp.user, "SMTP_USER") ?? undefined;
+  const pass = env.string(smtp.password, "SMTP_PASSWORD") ?? undefined;
+  const domain = env.string(config.domain, "EMAIL_DOMAIN") ?? undefined;
+  const from = env.string(config.from, "EMAIL_FROM") ?? undefined;
   const senderPolicy = resolveSenderPolicy(config.senderPolicy);
   const configuredSenders = parseAllowedSenders(
-    config.allowedSenders ?? process.env.EMAIL_ALLOWED_SENDERS,
+    config.allowedSenders ?? env.text("EMAIL_ALLOWED_SENDERS") ?? undefined,
   );
   const allowedSenders =
     configuredSenders.length > 0 || senderPolicy === "unrestricted"
       ? configuredSenders
       : impliedSenderPatterns(domain, from);
   const sender: ResolvedSender = {
-    ...(domain ? { domain } : {}),
-    ...(from ? { from } : {}),
+    ...object.optional("domain", domain),
+    ...object.optional("from", from),
     allowedSenders,
     senderPolicy,
-    ...(config.brand ? { brand: config.brand } : {}),
+    brand: config.brand ?? defaultEmailBrand,
   };
 
   const hasAllSmtp = Boolean(host && user && pass);
@@ -336,8 +341,7 @@ export function resolveEmailConfig(config: EmailPluginConfig = {}): ResolvedEmai
         "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) : DEFAULT_SMTP_PORT;
+    const port = env.positiveInt(smtp.port, "SMTP_PORT", DEFAULT_SMTP_PORT);
     return {
       mode: "smtp",
       host: host!,
@@ -356,7 +360,7 @@ export function resolveEmailConfig(config: EmailPluginConfig = {}): ResolvedEmai
   }
 
   const outDir = resolve(
-    config.outDir ?? process.env.EMAIL_OUTBOX_DIR ?? resolve(process.cwd(), "tmp"),
+    env.string(config.outDir, "EMAIL_OUTBOX_DIR") ?? resolve(process.cwd(), "tmp"),
   );
   return { mode: "file", outDir, ...sender };
 }

package/src/defaults.ts

@@ -50,7 +50,7 @@ export const MAX_ATTACHMENTS_TOTAL_BYTES = 20_971_520;
 /** Largest number of attachments accepted on one message. */
 export const MAX_ATTACHMENT_COUNT = 20;
 
-/** Largest markdown body accepted, in characters. */
+/** Largest email body accepted, in characters. */
 export const MAX_BODY_CHARS = 200_000;
 
 /** Execution settings for a send (SMTP dispatch or an outbox write). */

package/src/email-html.ts

@@ -1,174 +1,33 @@
-/**
- * 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.
- *
- * Brand styling (accent color, font, header logo) is optional: pass an
- * {@link EmailBrand} to color the layout, or omit it for the neutral
- * default. Branding is inlined here because the browser UI's `[data-brand]`
- * CSS bridge can't reach an inbox (see `./brand`).
- *
- * @module
- */
-
+/** Node rendering adapters for the shared React Email document. @module */
 import { string } from "@dbx-tools/shared-core";
-import juice from "juice";
-import type { EmailBrand } from "./brand.ts";
-import { markdownToHtml } from "./markdown.ts";
-
-/**
- * Rendered height of the header logo. Fixed rather than intrinsic because
- * mail clients ignore CSS sizing on an image without an `height` attribute.
- */
-const LOGO_HEIGHT_PX = 28;
+import { EmailDocument, type EmailDocumentProps } from "@dbx-tools/shared-email-template";
+import { render } from "@react-email/render";
+import { createElement } from "react";
 
-/** Neutral fallback styling when no brand is supplied. */
-const DEFAULT_BRAND: Required<Pick<EmailBrand, "accent" | "onAccent" | "fontFamily">> = {
-  accent: "#0b6bcb",
-  onAccent: "#ffffff",
-  fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif",
-};
-
-/** Escape HTML-significant characters (re-exported from `@dbx-tools/shared-core`). */
+/** Escape HTML-significant characters (re-exported from shared-core). */
 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. Parameterized by the resolved accent
- * so body links match the brand.
- */
-function contentCss(accent: string): string {
-  return `
-    .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;
-  /**
-   * Optional brand styling for the layout (accent, font, header logo).
-   * Omit for the neutral default palette.
-   */
-  brand?: EmailBrand;
-}
-
-/** 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>`;
-}
+/** Options accepted by the shared React Email document. */
+export type EmailHtmlOptions = EmailDocumentProps;
 
-/** 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 a complete responsive React Email document. */
+export async function renderEmailHtml(options: EmailHtmlOptions): Promise<string> {
+  return render(createElement(EmailDocument, options), { pretty: true });
 }
 
-/**
- * Render the header-band content: the brand logo (when the brand supplies a
- * renderable image) above the title, or just the title. The logo is capped
- * at {@link LOGO_HEIGHT_PX} and tinted implicitly by its own artwork; the
- * title always shows so the band is never empty.
- */
-function headerBand(title: string, brand: EmailBrand, onAccent: string): string {
-  const logo = brand.logoUrl
-    ? `<img src="${escapeHtml(brand.logoUrl)}" alt="${escapeHtml(brand.name ?? title)}" height="${LOGO_HEIGHT_PX}" style="height: ${LOGO_HEIGHT_PX}px; width: auto; display: block; margin-bottom: 8px;" />`
-    : "";
-  return `${logo}<span style="color: ${onAccent}; font-size: 18px; font-weight: 700; line-height: 1.3;">${escapeHtml(title)}</span>`;
+/** Render the same React Email document as its plain-text alternative. */
+export async function renderEmailText(options: EmailHtmlOptions): Promise<string> {
+  return render(createElement(EmailDocument, options), { plainText: true });
 }
 
-/**
- * Render `body` (markdown) into a complete, style-inlined email document
- * using the responsive layout. When `opts.brand` is set its accent, font,
- * and logo style the layout; otherwise a neutral default palette is used.
- */
-export function renderEmailHtml(opts: EmailHtmlOptions): string {
-  const title = opts.subject?.trim() || "Message";
-  const accent = opts.brand?.accent ?? DEFAULT_BRAND.accent;
-  const onAccent = opts.brand?.onAccent ?? DEFAULT_BRAND.onAccent;
-  const fontFamily = opts.brand?.fontFamily ?? DEFAULT_BRAND.fontFamily;
-  const brand: EmailBrand = opts.brand ?? { accent, onAccent, fontFamily };
-  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>${contentCss(accent)}
-    </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: ${fontFamily};">
-            <tr>
-              <td class="gutter" style="padding: 20px 32px; background-color: ${accent};">
-                ${headerBand(title, brand, onAccent)}
-              </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);
+/** Render both MIME alternatives from one shared React Email component tree. */
+export async function renderEmail(
+  options: EmailHtmlOptions,
+): Promise<{ html: string; text: string }> {
+  const element = createElement(EmailDocument, options);
+  const [html, text] = await Promise.all([
+    render(element, { pretty: true }),
+    render(element, { plainText: true }),
+  ]);
+  return { html, text };
 }

package/src/markdown.ts

@@ -1,94 +1,14 @@
-/**
- * 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.
- *
- * @module
- */
-
-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,
+/** Compatibility helpers backed by the shared React Email body. @module */
+import { EmailBody, normalizeEmailMarkdown } from "@dbx-tools/shared-email-template";
+import { render } from "@react-email/render";
+import { createElement } from "react";
+
+/** Normalize indentation in authored content. */
+export const normalizeMarkdown = normalizeEmailMarkdown;
+
+/** Render a standalone message body through React Email. */
+export async function markdownToHtml(body: string): Promise<string> {
+  return render(createElement(EmailBody, { body: normalizeEmailMarkdown(body) }), {
+    pretty: true,
   });
 }

package/src/outbox.ts

@@ -59,7 +59,7 @@ export async function writeOutboxEmail(
   const folder = resolve(dir, from);
   await mkdir(folder, { recursive: true });
   const path = join(folder, `${Date.now()}-${subjectSlug(message.subject)}.html`);
-  const html = renderEmailHtml({
+  const html = await renderEmailHtml({
     subject: message.subject,
     headers: headerRows(message, from),
     body: message.body,

package/src/plugin.ts

@@ -45,7 +45,7 @@ import {
   type ToolProvider,
   type ToolRegistry,
 } from "@databricks/appkit/beta";
-import { log } from "@dbx-tools/shared-core";
+import { log, string, token } from "@dbx-tools/shared-core";
 import {
   email as emailWire,
   type EmailMessage,
@@ -203,6 +203,20 @@ export class EmailPlugin extends Plugin<EmailPluginConfig> implements ToolProvid
    * 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.
+   *
+   * OBO is used only WHEN the request can support it. `asUser(req)` throws
+   * `AuthenticationError` outside `NODE_ENV=development` if the request carries
+   * no forwarded OBO token, and AppKit does not catch a rejection raised inside
+   * a handler - so unconditionally wrapping this route takes the process down
+   * for a caller that authenticated some other way (a `@dbx-tools/cli-tunnel`
+   * OTP session, a health probe, a local `curl`). The user context is only ever
+   * an ENRICHMENT here: without it, wildcard senders simply expand against no
+   * local part. Degrading to the service context therefore answers correctly
+   * instead of failing, and a front-door request is unchanged.
+   *
+   * This is the same rule `@dbx-tools/appkit`'s `identity` module applies in
+   * `"auto"` mode; the header check is inlined rather than taking a dependency
+   * on that package for one predicate.
    */
   override injectRoutes(router: IAppRouter): void {
     this.route(router, {
@@ -210,7 +224,9 @@ export class EmailPlugin extends Plugin<EmailPluginConfig> implements ToolProvid
       method: "get",
       path: SENDERS_ROUTE,
       handler: async (req, res) => {
-        const result = await this.asUser(req).executeListSenders();
+        const oboToken = string.trimToNull(req.header(token.ACCESS_TOKEN_HEADER));
+        const scoped = oboToken === null ? this : this.asUser(req);
+        const result = await scoped.executeListSenders();
         if (!result.ok) {
           res.status(result.status).json({ error: result.message });
           return;

package/src/tool.ts

@@ -29,7 +29,7 @@ const logger = log.logger("email/tool/send-email");
 /**
  * The model-facing description of the send capability, shared by the Mastra
  * {@link emailTool} and the AppKit `email.send` tool so both agents get the
- * same guidance about approval, scope, and body formatting.
+ * same guidance about approval and scope.
  */
 export const SEND_EMAIL_DESCRIPTION = string.toDescription(`
   Send an email on the user's behalf. Pass one or more recipient
@@ -37,11 +37,9 @@ export const SEND_EMAIL_DESCRIPTION = string.toDescription(`
   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.
+  never autonomously. Compose whatever subject and body best fulfill
+  the user's request; the configured React Email template handles the
+  responsive layout, rich presentation, and brand styling.
 `);
 
 /** Options accepted by {@link emailTool}. */

package/src/transport.ts

@@ -23,13 +23,12 @@
  */
 
 import {
-  AppKitError,
   ConfigurationError,
   ExecutionError,
   ValidationError,
   type ExecutionResult,
 } from "@databricks/appkit";
-import { async, error, log } from "@dbx-tools/shared-core";
+import { execution, log } from "@dbx-tools/shared-core";
 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.ts";
@@ -41,7 +40,7 @@ import {
   MAX_BODY_CHARS,
   type EmailExecutionSettings,
 } from "./defaults.ts";
-import { renderEmailHtml } from "./email-html.ts";
+import { renderEmail } from "./email-html.ts";
 import { writeOutboxEmail } from "./outbox.ts";
 import { assertSenderAllowed } from "./sender.ts";
 
@@ -70,17 +69,7 @@ export interface EmailRuntime {
  * directly, mapping a throw onto the same {@link ExecutionResult} shape so
  * call sites branch on `ok` either way.
  */
-const directExecute: EmailExecutor = async (fn) => {
-  try {
-    return { ok: true, data: await fn() };
-  } catch (err) {
-    return {
-      ok: false,
-      status: err instanceof AppKitError ? err.statusCode : 500,
-      message: error.errorMessage(err),
-    };
-  }
-};
+const directExecute = execution.directExecutor<EmailExecutionSettings>();
 
 let runtime: EmailRuntime | undefined;
 
@@ -157,20 +146,23 @@ export async function executeWrite<T>(
   signal?: AbortSignal,
 ): Promise<T> {
   const { execute } = getEmailRuntime();
-  const result = await execute(
-    (executeSignal) => fn(async.combineAbortSignals(executeSignal, signal)),
-    settings,
-  );
-  if (result.ok) return result.data;
-  // A caller that cancelled is not a failure worth reporting as one.
-  if (signal?.aborted) throw ExecutionError.canceled();
-  logger.warn("execution-failed", {
+  return execution.run({
     operation,
-    status: result.status,
-    error: result.message,
-  });
-  throw new ExecutionError(`email: ${operation} failed`, {
-    context: { operation, status: result.status },
+    settings,
+    execute,
+    fn,
+    signal,
+    canceled: ExecutionError.canceled,
+    failed: (failure) => {
+      logger.warn("execution-failed", {
+        operation: failure.operation,
+        status: failure.status,
+        error: failure.message,
+      });
+      return new ExecutionError(`email: ${failure.operation} failed`, {
+        context: { operation: failure.operation, status: failure.status },
+      });
+    },
   });
 }
 
@@ -340,17 +332,18 @@ async function dispatch(
     );
   }
   const attachments = toMailAttachments(message.attachments);
+  const rendered = await renderEmail({
+    subject: message.subject,
+    body: message.body,
+    brand: config.brand,
+  });
   const info = await abortable(
     transporter.sendMail({
       from,
       to: message.to,
       subject: message.subject,
-      text: message.body,
-      html: renderEmailHtml({
-        subject: message.subject,
-        body: message.body,
-        ...(config.brand ? { brand: config.brand } : {}),
-      }),
+      text: rendered.text,
+      html: rendered.html,
       ...(message.cc && message.cc.length > 0 ? { cc: message.cc } : {}),
       ...(message.bcc && message.bcc.length > 0 ? { bcc: message.bcc } : {}),
       ...(attachments ? { attachments } : {}),
@@ -369,8 +362,8 @@ async function dispatch(
  * 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
+ * body is rendered by React Email into matching plain-text and HTML MIME
+ * alternatives, 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, when the body
  * or attachments exceed the plugin's caps, or when `from` is not permitted