@sdxc/mail 2026.10.17 → 2026.10.21

package/README.md

@@ -44,56 +44,118 @@ if (isFailure(result)) console.warn(result.error.message);
 
 The plain-text part is derived from the HTML, so every message ships both.
 
-### Define an email
+### Declare emails in a registry
+
+An app declares every email it sends, and the schema of its props, in one map. Importing the
+map costs the schemas alone, so a sender never loads the module that renders an email:
 
 ```tsx
-import { defineEmail, Email } from "@sdxc/mail";
+// app/emails/index.ts
+import { email, emails } from "@sdxc/mail";
+import * as s from "remix/data-schema";
 
-interface TeamInvite {
-	team: string;
-	url: string;
-}
+export default emails({
+	teams: { invite: email({ props: s.object({ team: s.string(), url: s.string() }) }) },
+});
+
+// app/emails/teams/invite.tsx
+import { createEmail, Email } from "@sdxc/mail";
 
-export const TeamInviteEmail = defineEmail<TeamInvite>({
-	subject: (invite) => `Join ${invite.team}`,
+export default createEmail(emails.teams.invite, {
+	subject: ({ team, t }) => t("emails.teamInvite.subject", { team }),
 	body: (handle) => () => (
-		<Email.Layout preview={`Join ${handle.props.team}`} title="Invite">
-			<Email.Heading>You have been invited</Email.Heading>
-			<Email.Text>Join {handle.props.team} to start collaborating.</Email.Text>
-			<Email.Button href={handle.props.url}>Accept invite</Email.Button>
-			<Email.Footer>You received this because someone invited you to a team.</Email.Footer>
+		<Email.Layout lang={handle.props.locale} title={handle.props.team}>
+			<Email.Button href={handle.props.url}>
+				{handle.props.t("emails.teamInvite.action")}
+			</Email.Button>
 		</Email.Layout>
 	),
+	preview: () => ({ team: "Acme", url: "https://example.com/invite/1" }),
 });
 
-await mailer.send(new TeamInviteEmail(invite.email, invite));
+// app/initializers/mail.ts
+import { createMail, lazy } from "@sdxc/mail";
+
+export const mail = createMail({ translator: translate });
+mail.map(
+	emails.teams.invite,
+	lazy(() => import("~/app/emails/teams/invite")),
+);
+```
+
+A mailer configured with the registry as `mail` sends a declared email by its declaration, with
+the recipient, the reader's language and the props:
+
+```typescript
+await ctx.email.send(emails.teams.invite, { to, locale, props: { team, url } });
+ctx.email.later(emails.teams.invite, { to, locale, props: { team, url } });
+await ctx.email.queue(emails.teams.invite, { to, locale, props: { team, url } });
+```
+
+The props are parsed by the declared schema first, and copy is translated when the email
+renders: `subject`, `body` and the other members receive the props with `locale` and `t` beside
+them, from the registry's `translator` (`createTranslator()` from `@sdxc/i18n` fits). Augment
+`MailTypes` with `translate` so `t()` checks message keys. `preview()` is optional and only feeds
+`mail.preview()`, which `previews(mail, { locales })` from `@sdxc/mail/previews` serves at
+`/_emails` while developing.
+
+`queue()` hands the delivery, as plain JSON, to the mailer's `queue` option. One job delivers
+every queued email:
+
+```typescript
+// app/jobs/index.ts
+export default jobs({ email: job({ input: EMAIL_DELIVERY }) });
+
+// app/jobs/email.ts
+export default createJobHandler(jobs.email, async (ctx) => {
+	let sent = await ctx.email.deliver(ctx.input);
+	if (isFailure(sent) && sent.error instanceof EmailRefusedError) ctx.exit(sent.error.message);
+	if (isFailure(sent)) ctx.retry({ cause: sent.error });
+});
 ```
 
-`defineEmail()` returns a class built with the recipient (a string, an `Address` or a list) and
-the props; `replyTo`, `headers`, `unsubscribe`, `list` and `calendar` are optional functions of
-the props. The subject arrives as a string, already in the recipient's language. Any object
-with `to`, `subject` and `body()` also satisfies the `Email` contract, for an email whose
-addressing needs more than its props.
+### An email outside the registry
+
+Mail that is no declared email, such as a message to the app's own inbox, can be any object
+with `to`, `subject` and `body()`; `replyTo`, `headers`, `unsubscribe`, `list` and `calendar`
+are optional members of the same `Email` contract.
+
+```tsx
+import { Email } from "@sdxc/mail";
+
+await mailer.send({
+	to: { email: "support@example.com" },
+	subject: `[Support] ${request.topic}`,
+	replyTo: { email: request.email },
+	body: () => (
+		<Email.Layout title="Support request">
+			<Email.Text>{request.message}</Email.Text>
+		</Email.Layout>
+	),
+});
+```
 
 ### Publish a mailer on the request context
 
 ```typescript
 import { CloudflareTransport } from "@sdxc/mail/cloudflare";
-import mail from "@sdxc/mail/middleware";
+import mailer from "@sdxc/mail/middleware";
 import { env } from "cloudflare:workers";
 import { createRouter } from "remix/router";
 
 let router = createRouter({
 	middleware: [
-		mail({
+		mailer({
 			transport: new CloudflareTransport(env.EMAIL),
 			from: { email: "no-reply@example.com", name: "Example" },
+			mail,
+			queue,
 		}),
 	],
 });
 
 router.post("/invites", async (context) => {
-	context.email.later(new TeamInviteEmail(invite.email, invite));
+	context.email.later(emails.teams.invite, { to: invite.email, props: invite });
 	return new Response(null, { status: 204 });
 });
 ```
@@ -104,17 +166,16 @@ is produced, and each outcome lands on the invocation's log.
 ### Test against the memory transport
 
 ```typescript
-import { Mailer } from "@sdxc/mail";
+import { isComposedEmail, Mailer } from "@sdxc/mail";
 import { MemoryTransport } from "@sdxc/mail/memory";
 
 let transport = new MemoryTransport();
-let mailer = new Mailer({ transport, from: { email: "no-reply@example.com" } });
+let mailer = new Mailer({ transport, from: { email: "no-reply@example.com" }, mail });
 
-await mailer.send(new TeamInviteEmail(invite.email, invite));
+await mailer.send(emails.teams.invite, { to: invite.email, props: invite });
 
-expect(transport.messages).toHaveLength(1);
-expect(transport.last?.email).toBeInstanceOf(TeamInviteEmail);
-expect(transport.last?.text).toContain(invite.url);
+let sent = transport.find((message) => isComposedEmail(message.email, emails.teams.invite));
+expect(sent?.text).toContain(invite.url);
 ```
 
 Recorded messages are the normalized ones a provider receives: defaults applied, address
@@ -146,6 +207,41 @@ calls it for you.
 
 How many messages wait for the next `flush()`.
 
+### `mailer.queue(email, delivery): Promise<Result<void, MailError>>`
+
+Validates a declared email's props and hands the delivery, with the email's name, to the
+`queue` option. Fails without a `mail` registry or a `queue`.
+
+### `mailer.deliver(queued: QueuedEmail): Promise<Result<SentMessage, MailError>>`
+
+Sends a delivery `queue()` produced. An `EmailRefusedError` (unmapped name, refused props) means
+no retry can send it.
+
+### `email({ props })` and `emails(tree)`
+
+Declare emails by the schema of their props; each declaration is named by its path
+(`teams.invite`), which a queued delivery carries.
+
+### `createEmail(email, options): EmailTemplate`
+
+Pairs a template with its declaration: `subject`, `body`, and optional `replyTo`, `headers`,
+`unsubscribe`, `list`, `calendar` and `preview`.
+
+### `createMail(options?: MailOptions): Mail`
+
+The registry: `map(email, template | lazy(load))`, `mapped`, `compose()`, `render(email, { locale, props })`,
+`preview(email, locale?)`, `hasPreview(email)` and `validate(email, props)`. It holds no transport, so a command run
+on Bun and the Worker share it.
+
+### `EMAIL_DELIVERY`
+
+The input schema of the job that delivers queued email.
+
+### `isComposedEmail(email, declaration?)`
+
+Whether a sent message's `email` was composed from a declaration, for picking it out of a
+memory transport in a test.
+
 ### `render(element: RemixElement): Promise<RenderedEmail>`
 
 Renders a body tree to `{ html, text }`, deriving `text` from the HTML. A whole document gets
@@ -159,11 +255,6 @@ headers fold at 78 characters, non-ASCII names and subjects become RFC 2047 enco
 part is quoted-printable or base64, whichever is smaller, line endings are CRLF, and `Bcc` is
 left to the envelope.
 
-### `defineEmail<Props>(definition: EmailDefinition<Props>): EmailClass<Props>`
-
-Builds an email class from `subject(props)` and a `body` component. Each call returns its own
-class, so `instanceof` tells two emails apart; an instance exposes the `props` it was built with.
-
 ### `isEmail(value: Message | Email): value is Email`
 
 `true` when the value has a callable `body`, the one member only an `Email` has.
@@ -280,10 +371,22 @@ binding.
 
 Publishes a request-scoped `Mailer` as `context.email` and flushes its queue after `next()`.
 `options` takes `transport` (a `Transport`, or `(context) => Transport` per request), `from`,
-`replyTo?` and `headers?`. Each deferred send logs `mail.sent` or a `mail.send_failed` warning
+`replyTo?`, `headers?`, and `mail?` (the `createMail()` registry) with `queue?` for declared emails. Each deferred send logs `mail.sent` or a `mail.send_failed` warning
 on the current log. It publishes under the `CurrentMailer` context key, exported here and from
 `./middleware/cli`, so `ctx.get(CurrentMailer)` reads the same mailer in a route or a command.
 
+### `@sdxc/mail/previews`
+
+#### `previews(mail: Mail, options?: PreviewsOptions): Middleware` (also the default export)
+
+Shows every mapped email as an inbox at `options.path` (default `/_emails`): each one's subject and
+opening lines in the locale picked from `options.locales`, and the one `?email=` names open beside
+the list as HTML or text (`?view=text`). The raw render of one email answers at
+`<path>/<name>?locale=&format=html|text`. The page is built from `@sdxc/ui`; pass the app's document
+stylesheets as `stylesheets` so it wears the app's theme:
+`stylesheets: () => assetResolver.getStylesheets("resources/layouts/document.tsx")`. Serve it only in
+development with `enabled: import.meta.env.DEV`, which passes every request on otherwise.
+
 ### `@sdxc/mail/middleware/cli`
 
 #### `mail(options: MailCommandOptions): CommandMiddleware` (default export)
@@ -312,6 +415,14 @@ let cli = createCLI({
 });
 ```
 
+### `@sdxc/mail/middleware/jobs`
+
+#### `mail(options: MailJobOptions): JobMiddleware` (default export)
+
+Publishes a `Mailer` as `ctx.email` on every [`@sdxc/jobs`](https://www.npmjs.com/package/@sdxc/jobs)
+run, with the router entry's options and `transport` a `Transport` or `(ctx) => Transport`. The
+queue flushes after the handler; a failed deferred send is a `mail.send_failed` warning.
+
 ### `@sdxc/mail/unsubscribe`
 
 #### `signUnsubscribeToken(secret: string, claims: { subject: string; list: string }, options?: UnsubscribeToken.SignOptions): Promise<Result<string, MailError>>`
@@ -340,18 +451,19 @@ send must not fail the request.
 import { isFailure } from "@sdxc/result";
 
 router.post("/password-reset", async (context) => {
-	let result = await context.email.send(new PasswordResetEmail(user));
+	let result = await context.email.send(emails.passwordReset, { to: user.email, props: { url } });
 	if (isFailure(result)) return new Response("Could not send the email", { status: 502 });
 	return new Response(null, { status: 204 });
 });
 
 router.post("/invites", async (context) => {
-	context.email.later(new TeamInviteEmail(invite.email, invite)); // sent after the response, failures logged
+	context.email.later(emails.teams.invite, { to: invite.email, props: invite }); // after the response, failures logged
 	return new Response(null, { status: 204 });
 });
 ```
 
-Outside the middleware, call `mailer.flush()` yourself, for example at the end of a job.
+Use `queue()` when the email must survive a failed send: a job delivers it and retries. Outside
+the middleware, call `mailer.flush()` yourself.
 
 ## Pattern: One-Click Unsubscribe For Bulk Mail
 
@@ -359,14 +471,16 @@ Gmail and Yahoo require one-click unsubscribe on subscribed and marketing mail.
 its target and list, and the mailer writes the headers:
 
 ```tsx
-import { defineEmail, Email } from "@sdxc/mail";
-import { signUnsubscribeToken } from "@sdxc/mail/unsubscribe";
-import { unwrap } from "@sdxc/result";
+// app/emails/index.ts
+export default emails({ digest: email({ props: s.object({ token: s.string() }) }) });
+
+// app/emails/digest.tsx
+import { createEmail, Email } from "@sdxc/mail";
 
-const DailyDigestEmail = defineEmail<{ token: string }>({
+export default createEmail(emails.digest, {
 	subject: () => "Your daily digest",
-	unsubscribe: (props) => ({
-		url: `https://example.com/unsubscribe/${props.token}`,
+	unsubscribe: ({ token }) => ({
+		url: `https://example.com/unsubscribe/${token}`,
 		mailto: "unsubscribe@example.com",
 	}),
 	list: () => ({ id: "daily-digest.example.com", name: "Daily digest" }),
@@ -377,8 +491,12 @@ const DailyDigestEmail = defineEmail<{ token: string }>({
 	),
 });
 
+// the sender
+import { signUnsubscribeToken } from "@sdxc/mail/unsubscribe";
+import { unwrap } from "@sdxc/result";
+
 let token = unwrap(await signUnsubscribeToken(secret, { subject: member.id, list: "digest" }));
-await mailer.send(new DailyDigestEmail(member.email, { token }));
+await ctx.email.send(emails.digest, { to: member.email, props: { token } });
 ```
 
 ```text

package/dist/cli.js

@@ -28,6 +28,8 @@ export default function mail(options) {
             from: options.from,
             replyTo: options.replyTo,
             headers: options.headers,
+            mail: options.mail,
+            queue: options.queue,
         });
         ctx.set(CurrentMailer, mailer, { property: "email" });
         let failed;

package/dist/emails.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The email registry's declarations: `emails({ … })` names every email an app sends and the
+ * schema of the props each one is built from. Importing the declarations costs the schemas
+ * alone, so a controller or a job sends an email without loading the module that renders it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+/** Tells a declared email from a group of them, both being plain objects. */
+declare const LEAF: unique symbol;
+/** Tells a named declaration, as `emails()` returns it, from anything else a mailer receives. */
+declare const DECLARATION: unique symbol;
+/**
+ * One email as `email()` declares it, before `emails()` gives it the name its path spells.
+ *
+ * @template Schema - The schema of the props the email is built from.
+ */
+export interface EmailLeaf<Schema extends StandardSchemaV1> {
+    readonly [LEAF]: true;
+    readonly props: Schema;
+}
+type AnyEmailLeaf = EmailLeaf<any>;
+/** The tree `emails()` takes: emails and groups of emails, nested to any depth. */
+export interface EmailTree {
+    [key: string]: AnyEmailLeaf | EmailTree;
+}
+/**
+ * A declared email: its name, which a queued delivery carries, and the schema its props are
+ * validated against before it renders or enters a queue.
+ *
+ * @template Schema - The schema of the props the email is built from.
+ */
+export interface EmailDeclaration<Schema extends StandardSchemaV1 = StandardSchemaV1> {
+    readonly [DECLARATION]: true;
+    /** The email's path in the tree, joined with dots (`teams.invite`); stable while a delivery waits in a queue. */
+    readonly name: string;
+    readonly props: Schema;
+}
+/** A declaration whatever its props, for the places that hold any of them. */
+export type AnyEmailDeclaration = EmailDeclaration<any>;
+/**
+ * The map `emails()` returns, with every leaf replaced by its named declaration.
+ *
+ * @template Tree - The tree the map was built from.
+ */
+export type EmailMap<Tree> = {
+    [Key in keyof Tree]: Tree[Key] extends EmailLeaf<infer Schema> ? EmailDeclaration<Schema> : EmailMap<Tree[Key]>;
+};
+/** The props a caller passes to send one email, before its schema parses them. */
+export type EmailPropsInput<Declaration> = Declaration extends EmailDeclaration<infer Schema> ? StandardSchemaV1.InferInput<Schema> : never;
+/** The props an email's template receives, as its schema parsed them. */
+export type EmailPropsOutput<Declaration> = Declaration extends EmailDeclaration<infer Schema> ? StandardSchemaV1.InferOutput<Schema> : never;
+/**
+ * Declares one email by the schema of its props. Any Standard Schema works; the props must be
+ * plain JSON when the email is queued, since a queued delivery travels as JSON.
+ *
+ * @param options - The schema the props are validated against.
+ * @returns A leaf for {@link emails} to name.
+ * @example email({ props: s.object({ team: s.string(), url: s.string() }) })
+ */
+export declare function email<Schema extends StandardSchemaV1>(options: {
+    props: Schema;
+}): EmailLeaf<Schema>;
+/**
+ * Names every email in `tree` by its path, so `emails({ teams: { invite } })` declares
+ * `teams.invite`.
+ *
+ * @param tree - The emails and groups of emails the app sends.
+ * @returns The same tree with each leaf turned into its named declaration.
+ * @example export default emails({ welcome: email({ props: s.object({ name: s.string() }) }) });
+ */
+export declare function emails<const Tree extends EmailTree>(tree: Tree): EmailMap<Tree>;
+/**
+ * Reports whether a value is a declared email rather than a message or an email object, which
+ * is how one `send()` takes either.
+ *
+ * @param value - Whatever a mailer received.
+ * @returns `true` for a declaration `emails()` returned.
+ */
+export declare function isEmailDeclaration(value: unknown): value is AnyEmailDeclaration;
+export {};

package/dist/emails.js

@@ -0,0 +1,61 @@
+/**
+ * The email registry's declarations: `emails({ … })` names every email an app sends and the
+ * schema of the props each one is built from. Importing the declarations costs the schemas
+ * alone, so a controller or a job sends an email without loading the module that renders it.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Tells a declared email from a group of them, both being plain objects. */
+const LEAF = Symbol.for("@sdxc/mail.email");
+/** Tells a named declaration, as `emails()` returns it, from anything else a mailer receives. */
+const DECLARATION = Symbol.for("@sdxc/mail.declaration");
+/**
+ * Declares one email by the schema of its props. Any Standard Schema works; the props must be
+ * plain JSON when the email is queued, since a queued delivery travels as JSON.
+ *
+ * @param options - The schema the props are validated against.
+ * @returns A leaf for {@link emails} to name.
+ * @example email({ props: s.object({ team: s.string(), url: s.string() }) })
+ */
+export function email(options) {
+    return { [LEAF]: true, props: options.props };
+}
+/**
+ * Names every email in `tree` by its path, so `emails({ teams: { invite } })` declares
+ * `teams.invite`.
+ *
+ * @param tree - The emails and groups of emails the app sends.
+ * @returns The same tree with each leaf turned into its named declaration.
+ * @example export default emails({ welcome: email({ props: s.object({ name: s.string() }) }) });
+ */
+export function emails(tree) {
+    return build(tree, "");
+}
+/** Walks one level of the tree, prefixing every name with the path that reached it. */
+function build(tree, prefix) {
+    let map = {};
+    for (let [key, value] of Object.entries(tree)) {
+        let name = prefix === "" ? key : `${prefix}.${key}`;
+        map[key] = isLeaf(value) ? declare(name, value) : build(value, name);
+    }
+    return map;
+}
+/** Reports whether a tree entry is an email rather than a group of them. */
+function isLeaf(value) {
+    return LEAF in value;
+}
+/** The declaration of one leaf under the name its path spells. */
+function declare(name, leaf) {
+    return { [DECLARATION]: true, name, props: leaf.props };
+}
+/**
+ * Reports whether a value is a declared email rather than a message or an email object, which
+ * is how one `send()` takes either.
+ *
+ * @param value - Whatever a mailer received.
+ * @returns `true` for a declaration `emails()` returned.
+ */
+export function isEmailDeclaration(value) {
+    return typeof value === "object" && value !== null && DECLARATION in value;
+}

package/dist/errors.d.ts

@@ -1,6 +1,7 @@
 /**
  * The errors the mail package reports inside a `Result`: `MailError` for every
- * send failure — invalid message, failed render, rejected delivery — and
+ * send failure — invalid message, failed render, rejected delivery — its subclass
+ * `EmailRefusedError` for a declared email no retry can send, and
  * `InvalidUnsubscribeTokenError` for a token the unsubscribe endpoint refuses.
  *
  * @author [Sergio Xalambrí](https://sergiodxa.com)
@@ -20,6 +21,13 @@ export declare class MailError extends Error {
      */
     constructor(message: string, options?: ErrorOptions);
 }
+/**
+ * A declared email that cannot be sent however often it is retried: its name is not mapped,
+ * or its props fail its schema. A queued delivery's job gives up on it instead of retrying.
+ */
+export declare class EmailRefusedError extends MailError {
+    name: string;
+}
 /**
  * A token the unsubscribe endpoint cannot act on: malformed, tampered with, signed
  * with another secret or purpose, or expired. The cases share one type so the

package/dist/errors.js

@@ -1,6 +1,7 @@
 /**
  * The errors the mail package reports inside a `Result`: `MailError` for every
- * send failure — invalid message, failed render, rejected delivery — and
+ * send failure — invalid message, failed render, rejected delivery — its subclass
+ * `EmailRefusedError` for a declared email no retry can send, and
  * `InvalidUnsubscribeTokenError` for a token the unsubscribe endpoint refuses.
  *
  * @author [Sergio Xalambrí](https://sergiodxa.com)
@@ -22,6 +23,13 @@ export class MailError extends Error {
         super(message, options);
     }
 }
+/**
+ * A declared email that cannot be sent however often it is retried: its name is not mapped,
+ * or its props fail its schema. A queued delivery's job gives up on it instead of retrying.
+ */
+export class EmailRefusedError extends MailError {
+    name = "EmailRefusedError";
+}
 /**
  * A token the unsubscribe endpoint cannot act on: malformed, tampered with, signed
  * with another secret or purpose, or expired. The cases share one type so the

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 /**
- * Transport-agnostic transactional mail: the message contract, the mailer that
- * normalizes and delivers it, the rendering layer that turns a `remix/component` tree into
- * both body parts, and the unbranded layout kit for authoring one. Transports live
- * behind their own subpaths so importing one never pulls another's dependency.
+ * Transport-agnostic transactional mail: the message contract, the email registry that maps
+ * declared emails onto their templates, the mailer that normalizes and delivers them, the
+ * rendering layer for a `remix/component` tree, and the layout kit for authoring one.
+ * Transports live behind their own subpaths so importing one never pulls another's dependency.
  *
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
@@ -10,7 +10,10 @@
 import type { Email as EmailContract } from "./types.js";
 import * as EmailComponents from "./components.js";
 export type { Address, CalendarPart, MailingList, Message, NormalizedMessage, SentMessage, Transport, Unsubscribe, } from "./types.js";
-export type { DefinedEmail, EmailClass, EmailDefinition } from "./define.js";
+export type { AnyEmailDeclaration, EmailDeclaration, EmailLeaf, EmailMap, EmailPropsInput, EmailPropsOutput, EmailTree, } from "./emails.js";
+export type { Lazy } from "./lazy.js";
+export type { ComposedEmail, DeliveryFor, EmailDelivery, EmailTranslator, MailOptions, QueuedEmail, RenderInput, RenderedDeclaredEmail, } from "./mail.js";
+export type { AnyEmailTemplate, EmailInput, EmailLocale, EmailTemplate, EmailTemplateOptions, EmailTranslate, MailTypes, } from "./template.js";
 export type { MailerOptions, SendOptions } from "./mailer.js";
 export type { RenderedEmail } from "./render.js";
 /**
@@ -21,8 +24,11 @@ export type { RenderedEmail } from "./render.js";
 export type EmailTableRow = EmailComponents.Table.Row;
 /** A web font for `Email.Layout` to declare, named here for the same reason as above. */
 export type EmailFont = EmailComponents.Font;
-export { defineEmail } from "./define.js";
-export { MailError } from "./errors.js";
+export { email, emails, isEmailDeclaration } from "./emails.js";
+export { EmailRefusedError, MailError } from "./errors.js";
+export { lazy } from "./lazy.js";
+export { createMail, EMAIL_DELIVERY, isComposedEmail, Mail } from "./mail.js";
+export { createEmail } from "./template.js";
 export { formatAddress, toAddressList } from "./lib/address.js";
 export { htmlToText } from "./lib/html-to-text.js";
 export { isEmail, Mailer } from "./mailer.js";

package/dist/index.js

@@ -1,15 +1,18 @@
 /**
- * Transport-agnostic transactional mail: the message contract, the mailer that
- * normalizes and delivers it, the rendering layer that turns a `remix/component` tree into
- * both body parts, and the unbranded layout kit for authoring one. Transports live
- * behind their own subpaths so importing one never pulls another's dependency.
+ * Transport-agnostic transactional mail: the message contract, the email registry that maps
+ * declared emails onto their templates, the mailer that normalizes and delivers them, the
+ * rendering layer for a `remix/component` tree, and the layout kit for authoring one.
+ * Transports live behind their own subpaths so importing one never pulls another's dependency.
  *
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
  */
 import * as EmailComponents from "./components.js";
-export { defineEmail } from "./define.js";
-export { MailError } from "./errors.js";
+export { email, emails, isEmailDeclaration } from "./emails.js";
+export { EmailRefusedError, MailError } from "./errors.js";
+export { lazy } from "./lazy.js";
+export { createMail, EMAIL_DELIVERY, isComposedEmail, Mail } from "./mail.js";
+export { createEmail } from "./template.js";
 export { formatAddress, toAddressList } from "./lib/address.js";
 export { htmlToText } from "./lib/html-to-text.js";
 export { isEmail, Mailer } from "./mailer.js";

package/dist/jobs.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `@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 type { AnyJobContext, JobMiddleware } from "@sdxc/jobs";
+import type { MailerOptions } from "./mailer.js";
+import type { Transport } from "./types.js";
+import { CurrentMailer } from "./context.js";
+import { Mailer } from "./mailer.js";
+export { CurrentMailer } from "./context.js";
+/** Options that configure the job mail middleware. */
+export interface MailJobOptions extends Omit<MailerOptions, "transport"> {
+    /** Transport used for delivery, or a factory that resolves one per run from the job's context. */
+    transport: Transport | ((ctx: AnyJobContext) => Transport);
+}
+/**
+ * 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: MailJobOptions): JobMiddleware<{
+    key: typeof CurrentMailer;
+    value: Mailer;
+    property: "email";
+}>;

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 });
+            }
+        }
+    };
+}