@sdxc/mail 2026.10.17 → 2026.10.20

package/dist/mailer.js

@@ -10,6 +10,7 @@
  */
 import { failure, isFailure, success, wrap } from "@sdxc/result";
 import { generateUUID } from "@sdxc/uuid/v4";
+import { isEmailDeclaration } from "./emails.js";
 import { MailError } from "./errors.js";
 import { isValidAddress, toAddressList } from "./lib/address.js";
 import { htmlToText } from "./lib/html-to-text.js";
@@ -89,6 +90,10 @@ function validate(message) {
     }
     return success(message);
 }
+/** The failure a declared email meets on a mailer opened without the app's mail instance. */
+function noRegistry() {
+    return new MailError("This mailer sends declared emails only when configured with the app's `createMail()` instance.");
+}
 /**
  * Sends mail through a transport, applying one app's sender identity to every
  * message. The instance is request-scoped when `later()` is used, because the
@@ -97,7 +102,7 @@ function validate(message) {
 export class Mailer {
     /** Configuration shared by every message this mailer sends. */
     #options;
-    /** Messages queued by `later()`, drained by `flush()`. */
+    /** Sends deferred by `later()`, drained by `flush()`. */
     #queue = [];
     /**
      * Creates a mailer.
@@ -111,17 +116,9 @@ export class Mailer {
     get pending() {
         return this.#queue.length;
     }
-    /**
-     * Normalizes and delivers a message, awaiting the outcome. Never throws: a
-     * render failure, an invalid message, a rejected delivery, and a transport
-     * that throws all arrive as a `MailError` failure for the caller to inspect.
-     *
-     * @param input - A plain message, or an email object that renders its own body.
-     * @param overrides - Fields that replace what the input provides for this send.
-     * @returns The provider's identifier on success, a `MailError` on failure.
-     * @example let result = await mailer.send(new TeamInviteEmail(invite.email, invite));
-     */
     async send(input, overrides) {
+        if (isEmailDeclaration(input))
+            return await this.#sendDeclared(input, overrides);
         let prepared = await this.#normalize(input, overrides);
         if (isFailure(prepared))
             return prepared;
@@ -134,17 +131,49 @@ export class Mailer {
         }
         return outcome.data;
     }
+    later(input, overrides) {
+        this.#queue.push(() => isEmailDeclaration(input)
+            ? this.#sendDeclared(input, overrides)
+            : this.send(input, overrides));
+    }
     /**
-     * Queues a message to be sent once the caller flushes, which is how a send whose
-     * failure must not affect the response gets a defined lifetime. Nothing is
-     * rendered or validated yet; that happens at flush time.
+     * Hands a declared email to the app's queue, so a job sends it with retries on its own
+     * schedule. The props are validated here, so a caller learns about bad props where it wrote
+     * them; they render, translated, when the job delivers them.
      *
-     * @param input - A plain message, or an email object that renders its own body.
-     * @param overrides - Fields that replace what the input provides for this send.
-     * @example ctx.email.later(new PasswordResetEmail(user));
+     * @param email - The declared email.
+     * @param delivery - The recipient, the locale and the props, all plain JSON.
+     * @returns Success once the queue accepted the delivery; an `EmailRefusedError` for props the
+     *   schema refuses, or a `MailError` when no queue is configured or it threw.
+     * @example await ctx.email.queue(emails.teams.invite, { to, locale, props: { team, url } });
      */
-    later(input, overrides) {
-        this.#queue.push({ input, overrides });
+    async queue(email, delivery) {
+        let { mail, queue } = this.#options;
+        if (mail === undefined)
+            return failure(noRegistry());
+        if (queue === undefined) {
+            return failure(new MailError("This mailer has no `queue` to hand deliveries to."));
+        }
+        let props = await mail.validate(email, delivery.props);
+        if (isFailure(props))
+            return props;
+        let queued = await wrap(() => queue({ ...delivery, email: email.name }));
+        if (isFailure(queued)) {
+            return failure(new MailError(`Failed to queue the "${email.name}" email.`, { cause: queued.error }));
+        }
+        return success(undefined);
+    }
+    /**
+     * Sends a delivery `queue()` handed to the app's queue, which is the whole of the job that
+     * receives it. An `EmailRefusedError` means no retry can send it; any other failure can.
+     *
+     * @param queued - The delivery as the job received it.
+     * @returns The provider's identifier on success, a `MailError` on failure.
+     * @example let sent = await ctx.email.deliver(ctx.input);
+     */
+    async deliver(queued) {
+        let { email, ...delivery } = queued;
+        return await this.#sendDeclared(email, delivery);
     }
     /**
      * Sends everything `later()` queued and empties the queue. Results come back in
@@ -155,7 +184,27 @@ export class Mailer {
      */
     async flush() {
         let queued = this.#queue.splice(0, this.#queue.length);
-        return await Promise.all(queued.map((entry) => this.send(entry.input, entry.overrides)));
+        return await Promise.all(queued.map((deferred) => deferred()));
+    }
+    /**
+     * Composes a declared email through the app's mail instance and sends it, with the
+     * delivery's sender and copies applied over the mailer's.
+     */
+    async #sendDeclared(email, delivery) {
+        let mail = this.#options.mail;
+        if (mail === undefined)
+            return failure(noRegistry());
+        let composed = await mail.compose(email, delivery);
+        if (isFailure(composed))
+            return composed;
+        let overrides = {};
+        if (delivery.from !== undefined)
+            overrides.from = delivery.from;
+        if (delivery.cc !== undefined)
+            overrides.cc = delivery.cc;
+        if (delivery.bcc !== undefined)
+            overrides.bcc = delivery.bcc;
+        return await this.send(composed.data, overrides);
     }
     /**
      * Turns an email object into a plain message by reading its addressing and

package/dist/middleware.d.ts

@@ -9,6 +9,7 @@
  * @copyright Sergio Xalambrí 2026
  */
 import type { Middleware, RequestContext } from "remix/router";
+import type { Mail, QueuedEmail } from "./mail.js";
 import type { Address, Transport } from "./types.js";
 import { Mailer } from "./mailer.js";
 export { CurrentMailer } from "./context.js";
@@ -39,6 +40,10 @@ export interface MailMiddlewareOptions {
     replyTo?: Address | Address[];
     /** Headers added to every message the request sends. */
     headers?: Record<string, string>;
+    /** The app's `createMail()` instance, which lets `ctx.email` send its declared emails. */
+    mail?: Mail;
+    /** Hands a declared email's delivery to the app's queue for `ctx.email.queue()`. */
+    queue?: (delivery: QueuedEmail) => Promise<void>;
 }
 /**
  * Publishes a request-scoped mailer as `context.email`, under the {@link CurrentMailer} key the
@@ -48,6 +53,6 @@ export interface MailMiddlewareOptions {
  * @param options - Transport and sender configuration; see {@link MailMiddlewareOptions}.
  * @returns A middleware that populates `context.email`.
  * @example
- * router.use(mail({ transport: new CloudflareTransport(env.EMAIL), from: SENDER }));
+ * router.use(mailer({ transport: new CloudflareTransport(env.EMAIL), from: SENDER, mail }));
  */
 export default function mail(options: MailMiddlewareOptions): Middleware;

package/dist/middleware.js

@@ -21,7 +21,7 @@ export { CurrentMailer } from "./context.js";
  * @param options - Transport and sender configuration; see {@link MailMiddlewareOptions}.
  * @returns A middleware that populates `context.email`.
  * @example
- * router.use(mail({ transport: new CloudflareTransport(env.EMAIL), from: SENDER }));
+ * router.use(mailer({ transport: new CloudflareTransport(env.EMAIL), from: SENDER, mail }));
  */
 export default function mail(options) {
     return async (context, next) => {
@@ -31,6 +31,8 @@ export default function mail(options) {
             from: options.from,
             replyTo: options.replyTo,
             headers: options.headers,
+            mail: options.mail,
+            queue: options.queue,
         });
         context.set(CurrentMailer, mailer, { property: "email" });
         try {

package/dist/previews.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A fetch-router middleware that shows every email the registry maps, in every language the
+ * app speaks, rendered from each template's `preview()` props. It is a development tool: an
+ * app mounts it only while developing, since it renders any email for anyone who asks.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Middleware } from "remix/router";
+import type { Mail } from "./mail.js";
+/** Where the previews are served and in which languages. */
+export interface PreviewsOptions {
+    /**
+     * The languages each email is listed in, such as the app's supported languages. Without
+     * any, each email is listed once, in the translator's fallback.
+     */
+    locales?: readonly string[];
+    /**
+     * The path the list answers at; one email renders at `<path>/<name>`.
+     * @default "/_emails"
+     */
+    path?: string;
+    /**
+     * The stylesheets the page links, which carry `@sdxc/ui`'s reset, theme and the app's palette,
+     * such as the ones the app's document links; without any, the components render unthemed.
+     * @example stylesheets: () => assetResolver.getStylesheets("resources/layouts/document.tsx")
+     */
+    stylesheets?: () => readonly string[] | Promise<readonly string[]>;
+    /**
+     * Whether to answer at all; `false` passes every request on, which keeps the middleware in
+     * a typed chain while serving previews only in development, as `import.meta.env.DEV`.
+     * @default true
+     */
+    enabled?: boolean;
+}
+/**
+ * Answers `GET` on `options.path` with an inbox of every mapped email, the one `?email=` names
+ * open beside the list in the `?locale=` asked for, and on `<path>/<name>?locale=<locale>&format=html|text` with that email rendered from its
+ * `preview()`: the HTML document, or the subject and the plain-text part. An unmapped email or
+ * one without `preview()` answers 404; every other path and method goes to `next()`.
+ *
+ * @param mail - The app's email registry.
+ * @param options - The languages to list and the path to answer at.
+ * @example previews(mail, { locales: SUPPORTED_LANGUAGES, enabled: import.meta.env.DEV })
+ */
+export declare function previews(mail: Mail, options?: PreviewsOptions): Middleware;
+export default previews;

package/dist/previews.js

@@ -0,0 +1,229 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "remix/component/jsx-runtime";
+import { isFailure } from "@sdxc/result";
+import { bg, border, borderEdge, colorScheme, fg } from "@sdxc/u/color";
+import { block, flexWrap, grid, gridTemplate, grow, hstack, vstack } from "@sdxc/u/layout";
+import { divide, overflowY } from "@sdxc/u/overflow";
+import { media } from "@sdxc/u/responsive";
+import { bs, is, m, maxBs, minBs, minIs, p } from "@sdxc/u/size";
+import { aria, hover } from "@sdxc/u/state";
+import { font, fontSize, lineClamp, textDecoration, truncate, weight, whiteSpace, } from "@sdxc/u/typography";
+import { Avatar, Badge, Empty, Heading, Item, Link, LinkButton, Text } from "@sdxc/ui";
+import { renderToString } from "remix/component/server";
+import { EmailRefusedError } from "./errors.js";
+/**
+ * `path` with every trailing slash removed, by walking back from the end, so the time it takes
+ * grows with the path's length whatever the path holds.
+ */
+function withoutTrailingSlashes(path) {
+    let end = path.length;
+    while (end > 0 && path[end - 1] === "/")
+        end -= 1;
+    return path.slice(0, end);
+}
+/** The headers of a page that a preview never caches, since the template may change on the next save. */
+const NO_STORE = { "Cache-Control": "no-store" };
+/**
+ * Answers `GET` on `options.path` with an inbox of every mapped email, the one `?email=` names
+ * open beside the list in the `?locale=` asked for, and on `<path>/<name>?locale=<locale>&format=html|text` with that email rendered from its
+ * `preview()`: the HTML document, or the subject and the plain-text part. An unmapped email or
+ * one without `preview()` answers 404; every other path and method goes to `next()`.
+ *
+ * @param mail - The app's email registry.
+ * @param options - The languages to list and the path to answer at.
+ * @example previews(mail, { locales: SUPPORTED_LANGUAGES, enabled: import.meta.env.DEV })
+ */
+export function previews(mail, options = {}) {
+    let base = withoutTrailingSlashes(options.path ?? "/_emails");
+    let locales = options.locales ?? [];
+    let enabled = options.enabled ?? true;
+    let stylesheets = options.stylesheets ?? (() => []);
+    return async (ctx, next) => {
+        if (!enabled)
+            return next();
+        if (ctx.method !== "GET" && ctx.method !== "HEAD")
+            return next();
+        let path = ctx.url.pathname;
+        if (path === base)
+            return await inbox(mail, base, locales, ctx.url.searchParams, stylesheets);
+        if (!path.startsWith(`${base}/`))
+            return next();
+        let name = decodeURIComponent(path.slice(base.length + 1));
+        let locale = ctx.url.searchParams.get("locale") ?? undefined;
+        let format = ctx.url.searchParams.get("format") === "text" ? "text" : "html";
+        return await show(mail, name, locale, format);
+    };
+}
+/**
+ * The inbox page: every mapped email rendered in the chosen locale for its subject and snippet,
+ * and the selected one, by default the first previewable, opened in the reading pane.
+ */
+async function inbox(mail, base, locales, query, stylesheets) {
+    let asked = query.get("locale") ?? undefined;
+    let locale = asked !== undefined && locales.includes(asked) ? asked : locales[0];
+    let view = query.get("view") === "text" ? "text" : "html";
+    let requested = query.get("email") ?? undefined;
+    let entries = [];
+    let texts = new Map();
+    for (let email of mail.mapped) {
+        if (!(await mail.hasPreview(email))) {
+            entries.push({ name: email.name, previewable: false });
+            continue;
+        }
+        let rendered = await mail.preview(email.name, locale);
+        if (isFailure(rendered)) {
+            entries.push({
+                name: email.name,
+                previewable: true,
+                failed: true,
+                subject: rendered.error.message,
+            });
+            continue;
+        }
+        texts.set(email.name, rendered.data.text);
+        entries.push({
+            name: email.name,
+            previewable: true,
+            subject: rendered.data.subject,
+            snippet: snippet(rendered.data.text, rendered.data.subject),
+        });
+    }
+    let selected = requested === undefined
+        ? entries.find((entry) => entry.previewable)
+        : entries.find((entry) => entry.name === requested);
+    let html = await renderToString(_jsx(PreviewInbox, { base: base, locales: locales, locale: locale, entries: entries, selected: selected, requested: requested, view: view, text: selected === undefined ? undefined : texts.get(selected.name), stylesheets: await stylesheets() }));
+    return new Response(`<!doctype html>${html}`, {
+        headers: { "Content-Type": "text/html; charset=utf-8", ...NO_STORE },
+    });
+}
+/** The text part collapsed to one line, with a leading repeat of the subject dropped, cut at 140 characters. */
+function snippet(text, subject) {
+    let line = text.replace(/\s+/g, " ").trim();
+    if (line.startsWith(subject))
+        line = line.slice(subject.length).trim();
+    return line.length > 140 ? `${line.slice(0, 139).trimEnd()}…` : line;
+}
+/** One email rendered from its preview props, or the reason it cannot be. */
+async function show(mail, name, locale, format) {
+    if (!mail.mapped.some((email) => email.name === name)) {
+        return plain(`No template is mapped for the "${name}" email.`, 404);
+    }
+    if (!(await mail.hasPreview(name))) {
+        return plain(`The "${name}" email has no preview(); add one to its template.`, 404);
+    }
+    let rendered = await mail.preview(name, locale);
+    if (isFailure(rendered)) {
+        let cause = rendered.error.cause instanceof Error ? `\n\n${rendered.error.cause.stack}` : "";
+        let status = rendered.error instanceof EmailRefusedError ? 422 : 500;
+        return plain(`${rendered.error.message}${cause}`, status);
+    }
+    if (format === "text")
+        return plain(`Subject: ${rendered.data.subject}\n\n${rendered.data.text}`);
+    return new Response(rendered.data.html, {
+        headers: { "Content-Type": "text/html; charset=utf-8", ...NO_STORE },
+    });
+}
+/** A plain-text answer, uncached. */
+function plain(text, status = 200) {
+    return new Response(text, {
+        status,
+        headers: { "Content-Type": "text/plain; charset=utf-8", ...NO_STORE },
+    });
+}
+/** The URL of one email's preview in one locale and format. */
+function previewHref(base, name, locale, format) {
+    let query = new URLSearchParams();
+    if (locale !== undefined)
+        query.set("locale", locale);
+    if (format === "text")
+        query.set("format", "text");
+    let search = query.size === 0 ? "" : `?${query}`;
+    return `${base}/${encodeURIComponent(name)}${search}`;
+}
+/** The URL of the inbox with one email open, in one locale and view. */
+function inboxHref(base, name, locale, view) {
+    let query = new URLSearchParams({ email: name });
+    if (locale !== undefined)
+        query.set("locale", locale);
+    if (view === "text")
+        query.set("view", "text");
+    return `${base}?${query}`;
+}
+/**
+ * The inbox document, built from `@sdxc/ui` over the app's own stylesheets: a toolbar with the
+ * locale switch, every mapped email listed as a mail client lists messages, and a reading pane
+ * with the open email's HTML in a frame or its text part. It stacks into one column on a phone.
+ */
+function PreviewInbox(handle) {
+    return () => {
+        let { base, locales, locale, entries, selected, requested, view, text, stylesheets } = handle.props;
+        let readable = selected?.previewable === true && selected.failed !== true;
+        return (_jsxs("html", { lang: "en", class: "system", mix: colorScheme("light dark"), children: [_jsxs("head", { children: [_jsx("meta", { charset: "utf-8" }), _jsx("meta", { name: "viewport", content: "width=device-width, initial-scale=1" }), _jsx("title", { children: readable && selected?.subject !== undefined
+                                ? `${selected.subject} · Email previews`
+                                : "Email previews" }), stylesheets.map((href) => (_jsx("link", { rel: "stylesheet", href: href })))] }), _jsxs("body", { mix: [
+                        grid(),
+                        gridTemplate({ rows: "auto minmax(0, 1fr)" }),
+                        bs("100dvh"),
+                        m(0),
+                        font("sans"),
+                        bg("neutral.bg-tint"),
+                        fg("neutral"),
+                        media("(max-width: 48rem)", bs("auto")),
+                    ], children: [_jsxs("header", { mix: [
+                                hstack({ gap: 4, align: "center" }),
+                                flexWrap(),
+                                p(3, 4),
+                                bg("neutral.bg"),
+                                borderEdge("block-end", { width: 1, style: "solid", color: "neutral" }),
+                            ], children: [_jsxs(Heading, { level: 1, mix: [hstack({ gap: 2, align: "center" }), fontSize("lg"), grow()], children: ["Email previews", _jsx(Badge, { color: "neutral", children: entries.length })] }), locales.length > 1 ? (_jsx("nav", { "aria-label": "Language", mix: [hstack({ gap: 1, align: "center" }), flexWrap()], children: locales.map((code) => (_jsx(LinkButton, { href: selected === undefined
+                                            ? `${base}?locale=${encodeURIComponent(code)}`
+                                            : inboxHref(base, selected.name, code, view), "aria-current": code === locale ? "true" : undefined, color: code === locale ? "brand" : "neutral", variant: code === locale ? "solid" : "ghost", size: "sm", children: code.toUpperCase() }))) })) : null] }), _jsxs("div", { mix: [
+                                grid(),
+                                gridTemplate({ columns: "minmax(18rem, 24rem) minmax(0, 1fr)" }),
+                                minBs(0),
+                                media("(max-width: 48rem)", gridTemplate({ columns: "minmax(0, 1fr)" })),
+                            ], children: [_jsx("nav", { "aria-label": "Emails", mix: [
+                                        overflowY("auto"),
+                                        bg("neutral.bg"),
+                                        borderEdge("inline-end", { width: 1, style: "solid", color: "neutral" }),
+                                        divide(),
+                                        media("(max-width: 48rem)", [maxBs("45dvh"), border("none")]),
+                                    ], children: entries.length === 0 ? (_jsx(Empty, { children: _jsx(Empty.Title, { children: "No email is mapped on the registry yet." }) })) : (entries.map((entry) => (_jsx("a", { href: inboxHref(base, entry.name, locale, view), "aria-current": entry.name === selected?.name ? "true" : undefined, mix: [
+                                            block(),
+                                            p(3, 4),
+                                            borderEdge("inline-start", {
+                                                width: 3,
+                                                style: "solid",
+                                                color: "transparent",
+                                            }),
+                                            fg("neutral"),
+                                            textDecoration("none"),
+                                            hover(bg("neutral.bg-tint-hover")),
+                                            aria("current", "true", [
+                                                bg("brand.bg-tint"),
+                                                borderEdge("inline-start", { width: 3, style: "solid", color: "brand" }),
+                                            ]),
+                                        ], children: _jsxs(Item, { children: [_jsx(Item.Media, { children: _jsx(Avatar, { children: _jsx(Avatar.Fallback, { children: (entry.name.split(".").pop() ?? entry.name).charAt(0).toUpperCase() }) }) }), _jsxs(Item.Content, { children: [_jsx(Text, { mix: [fontSize("xs"), fg("neutral.muted"), font("mono")], children: entry.name }), _jsx(Item.Title, { mix: [truncate(), weight("semibold")], children: entry.previewable ? (_jsx("span", { mix: entry.failed === true ? fg("danger") : [], children: entry.subject })) : (_jsx(Badge, { color: "warning", children: "No preview" })) }), _jsx(Item.Description, { mix: lineClamp(2), children: entry.previewable
+                                                                ? entry.snippet
+                                                                : "Add preview() to its template to see it here." })] })] }) })))) }), _jsx("main", { mix: [vstack({ gap: 0 }), minBs(0), minIs(0)], children: !readable || selected === undefined ? (_jsx(Empty, { mix: m("auto"), color: selected?.failed === true ? "danger" : "neutral", children: _jsx(Empty.Title, { children: selected === undefined && requested !== undefined
+                                                ? `No template is mapped for the "${requested}" email.`
+                                                : selected === undefined
+                                                    ? "Select an email to read it."
+                                                    : selected.failed === true
+                                                        ? selected.subject
+                                                        : `The "${selected.name}" email has no preview(); add one to its template.` }) })) : (_jsxs(_Fragment, { children: [_jsxs("div", { mix: [
+                                                    vstack({ gap: 2 }),
+                                                    p(4, 5),
+                                                    bg("neutral.bg"),
+                                                    borderEdge("block-end", { width: 1, style: "solid", color: "neutral" }),
+                                                ], children: [_jsx(Heading, { level: 2, mix: fontSize("xl"), children: selected.subject }), _jsxs("div", { mix: [hstack({ gap: 3, align: "center" }), flexWrap()], children: [_jsx(Text, { mix: [grow(), fontSize("xs"), fg("neutral.muted"), font("mono")], children: locale === undefined ? selected.name : `${selected.name} · ${locale}` }), _jsx("nav", { "aria-label": "Format", mix: hstack({ gap: 1, align: "center" }), children: ["html", "text"].map((format) => (_jsx(LinkButton, { href: inboxHref(base, selected.name, locale, format), "aria-current": format === view ? "true" : undefined, color: format === view ? "brand" : "neutral", variant: format === view ? "solid" : "outline", size: "sm", children: format === "html" ? "HTML" : "Text" }))) }), _jsx(Link, { href: previewHref(base, selected.name, locale, view), target: "_blank", children: "Open raw" })] })] }), view === "html" ? (_jsx("iframe", { title: selected.subject, src: previewHref(base, selected.name, locale, "html"), mix: [grow(), is("full"), minBs("70dvh"), border("none"), bg("white")] })) : (_jsx("pre", { mix: [
+                                                    grow(),
+                                                    m(0),
+                                                    p(5),
+                                                    overflowY("auto"),
+                                                    whiteSpace("pre-wrap"),
+                                                    font("mono"),
+                                                    fontSize("sm"),
+                                                ], children: text }))] })) })] })] })] }));
+    };
+}
+export default previews;

package/dist/template.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `createEmail()`: what one declared email says and looks like, written in its own module and
+ * mapped onto the registry. Every member reads the parsed props together with the reader's
+ * locale and its translator, so copy is translated when the email renders.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { Handle, RemixNode } from "remix/component";
+import type { EmailDeclaration } from "./emails.js";
+import type { Address, CalendarPart, MailingList, Unsubscribe } from "./types.js";
+/**
+ * Augmented by an app to type the translator its templates receive, so `t()` checks message
+ * keys against the app's bundles.
+ *
+ * @example declare module "@sdxc/mail" { interface MailTypes { translate: Translate } }
+ */
+export interface MailTypes {
+}
+/** The translator a template calls: the app's, or one keyed by any string until it declares its own. */
+export type EmailTranslate = MailTypes extends {
+    translate: infer Translate;
+} ? Translate : (key: string, values?: Record<string, unknown>) => string;
+/** The language an email renders in, and the translator bound to it. */
+export interface EmailLocale {
+    /** The language the translator resolved, which the layout's `lang` should carry. */
+    locale: string;
+    t: EmailTranslate;
+}
+/**
+ * What every member of a template receives: the parsed props with `locale` and `t` beside
+ * them, so a body reads `handle.props.team` and `handle.props.t` from one object.
+ *
+ * @template Props - The props as the email's schema parses them.
+ */
+export type EmailInput<Props> = Props & EmailLocale;
+/**
+ * What one declared email says and looks like.
+ *
+ * @template Props - The props as the email's schema parses them.
+ * @template Input - The props as a caller writes them, which `preview()` returns.
+ */
+export interface EmailTemplateOptions<Props, Input = Props> {
+    /** Subject line, translated for the reader. */
+    subject(input: EmailInput<Props>): string;
+    /** Body component, rendered by the mailer into the HTML and plain-text parts. */
+    body: (handle: Handle<EmailInput<Props>>) => () => RemixNode;
+    /** Per-email reply-to; the mailer's configuration supplies the default. */
+    replyTo?(input: EmailInput<Props>): Address | Address[] | undefined;
+    /** Per-email headers, merged over the mailer's configured headers. */
+    headers?(input: EmailInput<Props>): Record<string, string> | undefined;
+    /** One-click unsubscribe for optional mail, built per reader since its URL names them. */
+    unsubscribe?(input: EmailInput<Props>): Unsubscribe | undefined;
+    /** List the email belongs to, written as `List-Id`. */
+    list?(input: EmailInput<Props>): MailingList | undefined;
+    /** A calendar object, such as an invitation, sent alongside the rendered body. */
+    calendar?(input: EmailInput<Props>): CalendarPart | undefined;
+    /**
+     * Sample props that show the email in a preview. Only previews read it, so an email
+     * without one still sends; its props pass through the schema like any caller's.
+     */
+    preview?(): Input;
+}
+/**
+ * A template paired with the email it was written for, which `map()` checks.
+ *
+ * @template Schema - The schema of the email's props.
+ */
+export interface EmailTemplate<Schema extends StandardSchemaV1 = StandardSchemaV1> extends EmailTemplateOptions<StandardSchemaV1.InferOutput<Schema>, StandardSchemaV1.InferInput<Schema>> {
+    readonly email: EmailDeclaration<Schema>;
+}
+/** A template whatever its props, for the places that hold any of them. */
+export type AnyEmailTemplate = EmailTemplate<any>;
+/**
+ * Pairs a template with its declared email; passing the declaration is what types the props
+ * every member reads.
+ *
+ * @param email - The email this template renders, from the app's `emails()` map.
+ * @param options - The subject, the body component and any per-email delivery options.
+ * @returns The template, which the module default-exports for `mail.map()` to load.
+ * @example export default createEmail(emails.welcome, { subject: ({ name, t }) => t("emails.welcome.subject", { name }), body: WelcomeBody });
+ */
+export declare function createEmail<Schema extends StandardSchemaV1>(email: EmailDeclaration<Schema>, options: EmailTemplateOptions<StandardSchemaV1.InferOutput<Schema>, StandardSchemaV1.InferInput<Schema>>): EmailTemplate<Schema>;

package/dist/template.js

@@ -0,0 +1,20 @@
+/**
+ * `createEmail()`: what one declared email says and looks like, written in its own module and
+ * mapped onto the registry. Every member reads the parsed props together with the reader's
+ * locale and its translator, so copy is translated when the email renders.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Pairs a template with its declared email; passing the declaration is what types the props
+ * every member reads.
+ *
+ * @param email - The email this template renders, from the app's `emails()` map.
+ * @param options - The subject, the body component and any per-email delivery options.
+ * @returns The template, which the module default-exports for `mail.map()` to load.
+ * @example export default createEmail(emails.welcome, { subject: ({ name, t }) => t("emails.welcome.subject", { name }), body: WelcomeBody });
+ */
+export function createEmail(email, options) {
+    return { ...options, email };
+}

package/dist/types.d.ts

@@ -155,9 +155,9 @@ export interface Transport {
     send(message: NormalizedMessage): Promise<Result<SentMessage, MailError>>;
 }
 /**
- * An email: who it goes to, what it says, and what it looks like, usually built by
- * `defineEmail()`. Sender identity lives on the mailer, and a subject arrives already
- * translated from the caller's locale handling.
+ * An email: who it goes to, what it says, and what it looks like, usually composed by the
+ * registry from a declared email. Sender identity lives on the mailer, and a subject arrives
+ * already translated for its reader.
  */
 export interface Email {
     /** Recipient this email is addressed to, derived from the data it was constructed with. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sdxc/mail",
-	"version": "2026.10.17",
+	"version": "2026.10.20",
 	"description": "Transport-agnostic transactional email with pluggable transports and remix/component rendering",
 	"license": "MIT",
 	"type": "module",
@@ -12,26 +12,35 @@
 		"./print": "./dist/print.js",
 		"./middleware": "./dist/middleware.js",
 		"./middleware/cli": "./dist/cli.js",
+		"./middleware/jobs": "./dist/jobs.js",
+		"./previews": "./dist/previews.js",
 		"./unsubscribe": "./dist/unsubscribe.js"
 	},
 	"dependencies": {
 		"@sdxc/crypto": "2026.10.13",
 		"@sdxc/highlight": "2026.10.16",
-		"@sdxc/logger": "2026.10.16",
+		"@sdxc/logger": "2026.10.20",
 		"@sdxc/markdown": "2026.10.16",
 		"@sdxc/result": "2026.10.13",
-		"@sdxc/uuid": "2026.10.13"
+		"@sdxc/u": "2026.10.20",
+		"@sdxc/ui": "2026.10.20",
+		"@sdxc/uuid": "2026.10.13",
+		"@standard-schema/spec": "^1.1.0"
 	},
 	"peerDependencies": {
-		"@sdxc/cli": "2026.10.16",
+		"@sdxc/cli": "2026.10.20",
+		"@sdxc/jobs": "2026.10.20",
 		"remix": "3.0.0"
 	},
 	"peerDependenciesMeta": {
 		"@sdxc/cli": {
 			"optional": true
+		},
+		"@sdxc/jobs": {
+			"optional": true
 		}
 	},
-	"gitHead": "4f4bce453e9afe69f53194368af9e9739d73a876",
+	"gitHead": "bd4473246f405c43055d2fc5e08c62ba35197258",
 	"publishConfig": {
 		"access": "public"
 	},