@sdxc/mail 2026.10.16 → 2026.10.20

package/dist/jobs.js

@@ -0,0 +1,43 @@
+/**
+ * `@sdxc/jobs` middleware that publishes a mailer to every job as `ctx.email`, so a job sends
+ * with the same templates and sender identity a route uses, and the job that delivers queued
+ * email reads the mailer the rest of its dispatcher shares.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { currentLog } from "@sdxc/logger";
+import { isFailure } from "@sdxc/result";
+import { CurrentMailer } from "./context.js";
+import { Mailer } from "./mailer.js";
+export { CurrentMailer } from "./context.js";
+/**
+ * Publishes a mailer as `ctx.email` for each run. Messages deferred with `later()` send once the
+ * handler returns and each outcome is recorded on the run's log; a failed deferred send is a
+ * warning there, since the job's own work already finished.
+ *
+ * @param options - Transport, sender, and the app's `createMail()` instance; see {@link MailJobOptions}.
+ * @returns A middleware that installs `ctx.email`.
+ * @example createJobDispatcher({ middleware: [mailer({ transport, from: MAIL_FROM, mail })] as const });
+ */
+export default function mail(options) {
+    return async (ctx, next) => {
+        let transport = typeof options.transport === "function" ? options.transport(ctx) : options.transport;
+        let mailer = new Mailer({ ...options, transport });
+        ctx.set(CurrentMailer, mailer, { property: "email" });
+        try {
+            await next();
+        }
+        finally {
+            let log = currentLog();
+            for (let result of await mailer.flush()) {
+                if (isFailure(result))
+                    log?.warn("mail.send_failed", { error: result.error.message });
+                else
+                    log
+                        ?.set({ mail: { sent: true } })
+                        .note("mail.sent", { message_id: result.data.messageId });
+            }
+        }
+    };
+}

package/dist/lazy.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Marks an email template as a module imported on first use, so a Worker starts without the
+ * body of every email it can send and the first send of one pays for its import once per
+ * isolate.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Brands a loader so `map()` can tell it from a template it holds directly. */
+declare const LAZY: unique symbol;
+/** A template that arrives as the default export of a module imported on demand. */
+export interface Lazy<Target> {
+    readonly [LAZY]: true;
+    /** Imports the module; `Mail` calls it once per isolate and shares the result. */
+    readonly load: () => Promise<{
+        default: Target;
+    }>;
+}
+/**
+ * Wraps a dynamic import so `map()` defers it to the first send of that email.
+ *
+ * @param load A function returning the module's `import()`; the module default-exports what `createEmail()` returns.
+ * @returns A binding `mail.map()` accepts wherever it takes a template.
+ * @example mail.map(emails.welcome, lazy(() => import("~/app/emails/welcome")));
+ */
+export declare function lazy<Target>(load: () => Promise<{
+    default: Target;
+}>): Lazy<Target>;
+/** Reports whether a `map()` argument was wrapped by {@link lazy}. */
+export declare function isLazy(value: unknown): value is Lazy<unknown>;
+export {};

package/dist/lazy.js

@@ -0,0 +1,24 @@
+/**
+ * Marks an email template as a module imported on first use, so a Worker starts without the
+ * body of every email it can send and the first send of one pays for its import once per
+ * isolate.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Brands a loader so `map()` can tell it from a template it holds directly. */
+const LAZY = Symbol.for("@sdxc/mail.lazy");
+/**
+ * Wraps a dynamic import so `map()` defers it to the first send of that email.
+ *
+ * @param load A function returning the module's `import()`; the module default-exports what `createEmail()` returns.
+ * @returns A binding `mail.map()` accepts wherever it takes a template.
+ * @example mail.map(emails.welcome, lazy(() => import("~/app/emails/welcome")));
+ */
+export function lazy(load) {
+    return { [LAZY]: true, load };
+}
+/** Reports whether a `map()` argument was wrapped by {@link lazy}. */
+export function isLazy(value) {
+    return typeof value === "object" && value !== null && LAZY in value;
+}

package/dist/mail.d.ts

@@ -0,0 +1,169 @@
+/**
+ * `createMail()`: the app's email registry. It maps every declared email onto its template and
+ * composes one from its props and the reader's locale, so a send, a queued delivery and a
+ * preview all render the same way, wherever the mailer that sends it runs.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { AnyEmailDeclaration, EmailPropsInput, EmailPropsOutput } from "./emails.js";
+import type { Lazy } from "./lazy.js";
+import type { RenderedEmail } from "./render.js";
+import type { EmailTemplate, EmailTranslate } from "./template.js";
+import type { Address, Email } from "./types.js";
+import { MailError } from "./errors.js";
+/**
+ * Who one declared email goes to, in which language, and the props it is built from. Every
+ * field is plain JSON, so the same delivery is sent now or handed to a queue.
+ *
+ * @template Props - The props as a caller writes them.
+ */
+export interface EmailDelivery<Props = unknown> {
+    /** Recipients; a bare string is the mailbox alone. */
+    to: string | Address | Address[];
+    /** The reader's language, handed to the translator; omitted means the translator's fallback. */
+    locale?: string;
+    props: Props;
+    /** Sender for this delivery in place of the mailer's. */
+    from?: Address;
+    cc?: Address | Address[];
+    bcc?: Address | Address[];
+    /** Reply-to for this delivery, in place of the template's and the mailer's. */
+    replyTo?: Address | Address[];
+    /** Headers merged over the template's and the mailer's. */
+    headers?: Record<string, string>;
+}
+/** The delivery a caller writes for one declared email, typed from its schema. */
+export type DeliveryFor<Declaration> = EmailDelivery<EmailPropsInput<Declaration>>;
+/** A delivery addressed to a declared email by name, as it travels through a queue. */
+export interface QueuedEmail extends EmailDelivery {
+    /** The declared email's name (`teams.invite`). */
+    email: string;
+}
+/** The props and the language a render needs, which a preview supplies without a recipient. */
+export type RenderInput<Props = unknown> = Pick<EmailDelivery<Props>, "locale" | "props">;
+/** A rendered email: its subject beside both body parts, as a preview or a test reads it. */
+export interface RenderedDeclaredEmail extends RenderedEmail {
+    subject: string;
+}
+/**
+ * An email composed from a declaration, carrying the parsed props and the locale it rendered
+ * in, so a test finds a sent message by the email it came from and asserts on what the caller
+ * passed.
+ *
+ * @template Props - The props as the email's schema parsed them.
+ */
+export interface ComposedEmail<Props = unknown> extends Email {
+    readonly declaration: AnyEmailDeclaration;
+    readonly props: Props;
+    readonly locale: string;
+}
+/** Binds the reader's language to a translator; `createTranslator()` from `@sdxc/i18n` returns one. */
+export type EmailTranslator = (locale?: string) => {
+    locale: string;
+    t: EmailTranslate;
+};
+/** Configuration for the app's email registry. */
+export interface MailOptions {
+    /**
+     * Binds each delivery's locale to the translator its template receives. Without one, a
+     * template's `t()` returns the key it was given and `locale` is the delivery's or `en`.
+     */
+    translator?: EmailTranslator;
+}
+/**
+ * The input of the job that delivers queued email: `job({ input: EMAIL_DELIVERY })`. The props
+ * pass through untouched here, since the declared email's own schema parses them on delivery.
+ */
+export declare const EMAIL_DELIVERY: StandardSchemaV1<QueuedEmail, QueuedEmail>;
+/**
+ * The app's email registry: every declared email mapped onto its template. It holds no
+ * transport, so the same instance serves the Worker's mailers and a command run on Bun; a
+ * mailer configured with it as `mail` sends, defers and queues declared emails.
+ */
+export declare class Mail {
+    #private;
+    /**
+     * Creates the instance; {@link createMail} is the usual way to call it.
+     *
+     * @param options - The translator; see {@link MailOptions}.
+     */
+    constructor(options?: MailOptions);
+    /** Every mapped email, in the order it was mapped, for a preview list or a check to walk. */
+    get mapped(): AnyEmailDeclaration[];
+    /**
+     * Maps a declared email onto its template, held directly or loaded through `lazy()` on the
+     * email's first send.
+     *
+     * @param email - The declared email.
+     * @param template - What `createEmail()` returned for it, or the module that default-exports it.
+     * @throws When the email is already mapped, or the template was written for another email.
+     * @example mail.map(emails.welcome, lazy(() => import("~/app/emails/welcome")));
+     */
+    map<Schema extends StandardSchemaV1>(email: AnyEmailDeclaration & {
+        props: Schema;
+    }, template: EmailTemplate<Schema> | Lazy<EmailTemplate<Schema>>): void;
+    /**
+     * Builds the email a delivery describes: the props parsed by the declared schema, the
+     * locale bound to the translator, and every template member read from both.
+     *
+     * @param email - The declared email, or its name as a queued delivery carries it.
+     * @param delivery - The recipient, the locale and the props.
+     * @returns The email, or an `EmailRefusedError` for an unmapped name or props the schema refuses.
+     */
+    compose<Declaration extends AnyEmailDeclaration>(email: Declaration | string, delivery: EmailDelivery): Promise<Result<ComposedEmail<EmailPropsOutput<Declaration>>, MailError>>;
+    /**
+     * Renders a declared email without sending it, for a preview or a test asserting on copy.
+     *
+     * @param email - The declared email.
+     * @param input - The props and the locale to render with.
+     * @returns The subject and both body parts.
+     * @example let { subject, text } = unwrap(await mail.render(emails.welcome, { locale: "es", props }));
+     */
+    render<Declaration extends AnyEmailDeclaration>(email: Declaration, input: RenderInput<EmailPropsInput<Declaration>>): Promise<Result<RenderedDeclaredEmail, MailError>>;
+    /**
+     * Renders a declared email with its template's `preview()` props.
+     *
+     * @param email - The declared email, or its name as a preview URL carries it.
+     * @param locale - The language to render in; omitted means the translator's fallback.
+     * @returns The rendered email, or a `MailError` when the template has no `preview()`.
+     */
+    preview(email: AnyEmailDeclaration | string, locale?: string): Promise<Result<RenderedDeclaredEmail, MailError>>;
+    /**
+     * Reports whether the template mapped for an email has a `preview()`, loading it without
+     * rendering, so a preview list marks the emails it cannot show.
+     *
+     * @param email - The declared email, or its name.
+     * @returns `false` for an unmapped email or a template that failed to load, too.
+     */
+    hasPreview(email: AnyEmailDeclaration | string): Promise<boolean>;
+    /**
+     * Parses props with the declared schema without rendering anything, which is how a mailer
+     * refuses a queued delivery where its caller wrote it.
+     *
+     * @param email - The declared email.
+     * @param props - The props as the caller wrote them.
+     * @returns The parsed props, or an `EmailRefusedError` naming every issue.
+     */
+    validate<Declaration extends AnyEmailDeclaration>(email: Declaration, props: unknown): Promise<Result<EmailPropsOutput<Declaration>, MailError>>;
+}
+/**
+ * Creates the app's email registry.
+ *
+ * @param options - The translator; see {@link MailOptions}.
+ * @returns The instance an initializer maps every declared email onto.
+ * @example export const mail = createMail({ translator: translate });
+ */
+export declare function createMail(options?: MailOptions): Mail;
+/**
+ * Reports whether an email was composed from a declaration, and from which one when given,
+ * which is how a test picks a sent message out of a memory transport.
+ *
+ * @param email - The `email` a normalized message carries.
+ * @param declaration - The declared email it must come from.
+ * @returns `true` for an email `Mail.compose()` built, from `declaration` when one is given.
+ * @example transport.find((message) => isComposedEmail(message.email, emails.welcome));
+ */
+export declare function isComposedEmail<Declaration extends AnyEmailDeclaration>(email: Email | undefined, declaration?: Declaration): email is ComposedEmail<EmailPropsOutput<Declaration>>;

package/dist/mail.js

@@ -0,0 +1,265 @@
+/**
+ * `createMail()`: the app's email registry. It maps every declared email onto its template and
+ * composes one from its props and the reader's locale, so a send, a queued delivery and a
+ * preview all render the same way, wherever the mailer that sends it runs.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, isFailure, success, wrap } from "@sdxc/result";
+import { createElement } from "remix/component";
+import * as s from "remix/data-schema";
+import { isEmailDeclaration } from "./emails.js";
+import { EmailRefusedError, MailError } from "./errors.js";
+import { isLazy } from "./lazy.js";
+import { render } from "./render.js";
+/** A mailbox as it travels through a queue. */
+const ADDRESS = s.object({ email: s.string(), name: s.optional(s.string()) });
+/** One or several mailboxes, or a bare address string, as {@link EmailDelivery} accepts them. */
+const ADDRESSES = s.union([s.string(), ADDRESS, s.array(ADDRESS)]);
+/**
+ * The input of the job that delivers queued email: `job({ input: EMAIL_DELIVERY })`. The props
+ * pass through untouched here, since the declared email's own schema parses them on delivery.
+ */
+export const EMAIL_DELIVERY = s.object({
+    email: s.string(),
+    to: ADDRESSES,
+    locale: s.optional(s.string()),
+    props: s.any(),
+    from: s.optional(ADDRESS),
+    cc: s.optional(ADDRESSES),
+    bcc: s.optional(ADDRESSES),
+    replyTo: s.optional(ADDRESSES),
+    headers: s.optional(s.record(s.string(), s.string())),
+});
+/** What `t` does for an app that configured no translator: hands back the key. */
+function untranslated(key) {
+    return key;
+}
+/**
+ * The app's email registry: every declared email mapped onto its template. It holds no
+ * transport, so the same instance serves the Worker's mailers and a command run on Bun; a
+ * mailer configured with it as `mail` sends, defers and queues declared emails.
+ */
+export class Mail {
+    /** The translator every composed email receives. */
+    #options;
+    /** Declared emails by name, each with the loader that resolves its template once. */
+    #mapped = new Map();
+    /**
+     * Creates the instance; {@link createMail} is the usual way to call it.
+     *
+     * @param options - The translator; see {@link MailOptions}.
+     */
+    constructor(options = {}) {
+        this.#options = options;
+    }
+    /** Every mapped email, in the order it was mapped, for a preview list or a check to walk. */
+    get mapped() {
+        return [...this.#mapped.values()].map((entry) => entry.declaration);
+    }
+    /**
+     * Maps a declared email onto its template, held directly or loaded through `lazy()` on the
+     * email's first send.
+     *
+     * @param email - The declared email.
+     * @param template - What `createEmail()` returned for it, or the module that default-exports it.
+     * @throws When the email is already mapped, or the template was written for another email.
+     * @example mail.map(emails.welcome, lazy(() => import("~/app/emails/welcome")));
+     */
+    map(email, template) {
+        if (this.#mapped.has(email.name))
+            throw new Error(`Email "${email.name}" is already mapped`);
+        this.#mapped.set(email.name, { declaration: email, template: resolver(email, template) });
+    }
+    /**
+     * Builds the email a delivery describes: the props parsed by the declared schema, the
+     * locale bound to the translator, and every template member read from both.
+     *
+     * @param email - The declared email, or its name as a queued delivery carries it.
+     * @param delivery - The recipient, the locale and the props.
+     * @returns The email, or an `EmailRefusedError` for an unmapped name or props the schema refuses.
+     */
+    async compose(email, delivery) {
+        let loaded = await this.#load(email);
+        if (isFailure(loaded))
+            return loaded;
+        let { declaration, template } = loaded.data;
+        let props = await parse(declaration, delivery.props);
+        if (isFailure(props))
+            return props;
+        let language = this.#translate(delivery.locale);
+        let input = { ...props.data, ...language };
+        let composed = wrap(() => build(declaration, template, delivery, props.data, input));
+        if (isFailure(composed)) {
+            return failure(new MailError(`Failed to compose the "${declaration.name}" email.`, {
+                cause: composed.error,
+            }));
+        }
+        return success(composed.data);
+    }
+    /**
+     * Renders a declared email without sending it, for a preview or a test asserting on copy.
+     *
+     * @param email - The declared email.
+     * @param input - The props and the locale to render with.
+     * @returns The subject and both body parts.
+     * @example let { subject, text } = unwrap(await mail.render(emails.welcome, { locale: "es", props }));
+     */
+    async render(email, input) {
+        let composed = await this.compose(email, { ...input, to: [] });
+        if (isFailure(composed))
+            return composed;
+        let rendered = await wrap(() => render(composed.data.body()));
+        if (isFailure(rendered)) {
+            return failure(new MailError("Failed to render the email body.", { cause: rendered.error }));
+        }
+        return success({ subject: composed.data.subject, ...rendered.data });
+    }
+    /**
+     * Renders a declared email with its template's `preview()` props.
+     *
+     * @param email - The declared email, or its name as a preview URL carries it.
+     * @param locale - The language to render in; omitted means the translator's fallback.
+     * @returns The rendered email, or a `MailError` when the template has no `preview()`.
+     */
+    async preview(email, locale) {
+        let loaded = await this.#load(email);
+        if (isFailure(loaded))
+            return loaded;
+        let { declaration, template } = loaded.data;
+        if (template.preview === undefined) {
+            return failure(new MailError(`The "${declaration.name}" email has no preview.`));
+        }
+        let props = wrap(() => template.preview?.());
+        if (isFailure(props)) {
+            return failure(new MailError(`The "${declaration.name}" preview threw.`, { cause: props.error }));
+        }
+        return await this.render(declaration, { locale, props: props.data });
+    }
+    /**
+     * Reports whether the template mapped for an email has a `preview()`, loading it without
+     * rendering, so a preview list marks the emails it cannot show.
+     *
+     * @param email - The declared email, or its name.
+     * @returns `false` for an unmapped email or a template that failed to load, too.
+     */
+    async hasPreview(email) {
+        let loaded = await this.#load(email);
+        return !isFailure(loaded) && loaded.data.template.preview !== undefined;
+    }
+    /**
+     * Parses props with the declared schema without rendering anything, which is how a mailer
+     * refuses a queued delivery where its caller wrote it.
+     *
+     * @param email - The declared email.
+     * @param props - The props as the caller wrote them.
+     * @returns The parsed props, or an `EmailRefusedError` naming every issue.
+     */
+    async validate(email, props) {
+        return (await parse(email, props));
+    }
+    /** Resolves a declaration or a name to the mapped declaration and its loaded template. */
+    async #load(email) {
+        let name = isEmailDeclaration(email) ? email.name : email;
+        let entry = this.#mapped.get(name);
+        if (entry === undefined) {
+            return failure(new EmailRefusedError(`No template is mapped for the "${name}" email.`));
+        }
+        let template = await wrap(() => entry.template());
+        if (isFailure(template)) {
+            return failure(new MailError(`Failed to load the "${name}" email's template.`, {
+                cause: template.error,
+            }));
+        }
+        return success({ declaration: entry.declaration, template: template.data });
+    }
+    /** The reader's language and translator, or the key-returning stand-in without a translator. */
+    #translate(locale) {
+        let translator = this.#options.translator;
+        if (translator !== undefined)
+            return translator(locale);
+        return { locale: locale ?? "en", t: untranslated };
+    }
+}
+/**
+ * Creates the app's email registry.
+ *
+ * @param options - The translator; see {@link MailOptions}.
+ * @returns The instance an initializer maps every declared email onto.
+ * @example export const mail = createMail({ translator: translate });
+ */
+export function createMail(options = {}) {
+    return new Mail(options);
+}
+/**
+ * A function resolving a binding to its template, importing a lazy one at most once per
+ * isolate. A failed import is dropped, so the next send retries it.
+ */
+function resolver(email, template) {
+    if (!isLazy(template)) {
+        check(email, template);
+        return () => Promise.resolve(template);
+    }
+    let loading;
+    return () => {
+        loading ??= template.load().then((module) => check(email, module.default), (error) => {
+            loading = undefined;
+            throw error;
+        });
+        return loading;
+    };
+}
+/**
+ * Confirms a template renders the email it is mapped onto, so a module mapped under the wrong
+ * name fails on its first load instead of sending the wrong copy.
+ */
+function check(email, template) {
+    if (template.email.name !== email.name) {
+        throw new Error(`The template mapped for "${email.name}" was written for "${template.email.name}"`);
+    }
+    return template;
+}
+/** Parses props with the declared schema, refusing them with every issue's message. */
+async function parse(email, props) {
+    let result = await email.props["~standard"].validate(props);
+    if (result.issues === undefined)
+        return success(result.value);
+    let issues = result.issues.map((issue) => {
+        let path = issue.path?.map((key) => (typeof key === "object" ? key.key : key)).join(".");
+        return path ? `${path}: ${issue.message}` : issue.message;
+    });
+    return failure(new EmailRefusedError(`Invalid props for the "${email.name}" email: ${issues.join("; ")}`));
+}
+/** The email one template reads from `input`, with the delivery's reply-to and headers on top. */
+function build(declaration, template, delivery, props, input) {
+    let headers = template.headers?.(input);
+    return {
+        declaration,
+        props,
+        locale: input.locale,
+        to: typeof delivery.to === "string" ? { email: delivery.to } : delivery.to,
+        subject: template.subject(input),
+        replyTo: delivery.replyTo ?? template.replyTo?.(input),
+        headers: delivery.headers ? { ...headers, ...delivery.headers } : headers,
+        unsubscribe: template.unsubscribe?.(input),
+        list: template.list?.(input),
+        calendar: template.calendar?.(input),
+        body: () => createElement(template.body, input),
+    };
+}
+/**
+ * Reports whether an email was composed from a declaration, and from which one when given,
+ * which is how a test picks a sent message out of a memory transport.
+ *
+ * @param email - The `email` a normalized message carries.
+ * @param declaration - The declared email it must come from.
+ * @returns `true` for an email `Mail.compose()` built, from `declaration` when one is given.
+ * @example transport.find((message) => isComposedEmail(message.email, emails.welcome));
+ */
+export function isComposedEmail(email, declaration) {
+    if (email === undefined || !("declaration" in email))
+        return false;
+    let composed = email;
+    return declaration === undefined || composed.declaration.name === declaration.name;
+}

package/dist/mailer.d.ts

@@ -9,6 +9,8 @@
  * @copyright Sergio Xalambrí 2026
  */
 import type { Result } from "@sdxc/result";
+import type { AnyEmailDeclaration } from "./emails.js";
+import type { DeliveryFor, Mail, QueuedEmail } from "./mail.js";
 import type { Address, Email, Message, SentMessage, Transport } from "./types.js";
 import { MailError } from "./errors.js";
 /**
@@ -25,6 +27,16 @@ export interface MailerOptions {
     replyTo?: Address | Address[];
     /** Headers added to every message, with per-message headers winning. */
     headers?: Record<string, string>;
+    /**
+     * The app's `createMail()` instance, which resolves a declared email to its template; what
+     * lets `send()`, `later()` and `queue()` take a declaration.
+     */
+    mail?: Mail;
+    /**
+     * Hands a declared email's delivery to the app's queue, which is what `queue()` calls; the
+     * job that receives it sends it with `ctx.email.deliver(ctx.input)`.
+     */
+    queue?: (delivery: QueuedEmail) => Promise<void>;
 }
 /**
  * Reports whether a value is an `Email` rather than a plain `Message`.
@@ -55,22 +67,47 @@ export declare class Mailer {
      * 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.
+     * @param input - A declared email, a plain message, or an email object that renders its own body.
+     * @param overrides - For a declared email, the delivery: recipient, locale and props; otherwise
+     *   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));
+     * @example let result = await ctx.email.send(emails.teams.invite, { to, locale, props: { team, url } });
      */
+    send<Declaration extends AnyEmailDeclaration>(input: Declaration, delivery: DeliveryFor<Declaration>): Promise<Result<SentMessage, MailError>>;
     send(input: Message | Email, overrides?: SendOptions): Promise<Result<SentMessage, MailError>>;
     /**
      * 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.
      *
-     * @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 input - A declared email, a plain message, or an email object that renders its own body.
+     * @param overrides - For a declared email, the delivery; otherwise fields that replace what
+     *   the input provides for this send.
+     * @example ctx.email.later(emails.passwordReset, { to: user.email, locale, props: { url } });
      */
+    later<Declaration extends AnyEmailDeclaration>(input: Declaration, delivery: DeliveryFor<Declaration>): void;
     later(input: Message | Email, overrides?: SendOptions): void;
+    /**
+     * 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 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 } });
+     */
+    queue<Declaration extends AnyEmailDeclaration>(email: Declaration, delivery: DeliveryFor<Declaration>): Promise<Result<void, MailError>>;
+    /**
+     * 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);
+     */
+    deliver(queued: QueuedEmail): Promise<Result<SentMessage, MailError>>;
     /**
      * Sends everything `later()` queued and empties the queue. Results come back in
      * queue order for the caller to log; like `send()`, it never throws, so a failed