@sdxc/mail 2026.10.13 → 2026.10.17

package/README.md

@@ -44,46 +44,36 @@ if (isFailure(result)) console.warn(result.error.message);
 
 The plain-text part is derived from the HTML, so every message ships both.
 
-### Author an email as a class
+### Define an email
 
 ```tsx
-import type { Handle } from "remix/component";
+import { defineEmail, Email } from "@sdxc/mail";
 
-import { Email } from "@sdxc/mail";
+interface TeamInvite {
+	team: string;
+	url: string;
+}
 
-function InviteBody(handle: Handle<{ team: string; url: string }>) {
-	return () => (
+export const TeamInviteEmail = defineEmail<TeamInvite>({
+	subject: (invite) => `Join ${invite.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>
-	);
-}
-
-export class TeamInviteEmail implements Email {
-	constructor(private invite: { team: string; email: string; url: string; subject: string }) {}
-
-	get to() {
-		return { email: this.invite.email };
-	}
-
-	get subject() {
-		return this.invite.subject;
-	}
-
-	body() {
-		return <InviteBody team={this.invite.team} url={this.invite.url} />;
-	}
-}
+	),
+});
 
-await mailer.send(new TeamInviteEmail(invite));
+await mailer.send(new TeamInviteEmail(invite.email, invite));
 ```
 
-`Email` is both the contract (type) and the layout kit (value), so one import covers
-`implements Email` and `<Email.Layout>`. The subject arrives as a string, already in the
-recipient's language.
+`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.
 
 ### Publish a mailer on the request context
 
@@ -103,7 +93,7 @@ let router = createRouter({
 });
 
 router.post("/invites", async (context) => {
-	context.email.later(new TeamInviteEmail(invite));
+	context.email.later(new TeamInviteEmail(invite.email, invite));
 	return new Response(null, { status: 204 });
 });
 ```
@@ -120,7 +110,7 @@ import { MemoryTransport } from "@sdxc/mail/memory";
 let transport = new MemoryTransport();
 let mailer = new Mailer({ transport, from: { email: "no-reply@example.com" } });
 
-await mailer.send(new TeamInviteEmail(invite));
+await mailer.send(new TeamInviteEmail(invite.email, invite));
 
 expect(transport.messages).toHaveLength(1);
 expect(transport.last?.email).toBeInstanceOf(TeamInviteEmail);
@@ -169,6 +159,11 @@ 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.
@@ -259,6 +254,15 @@ Records every delivery instead of sending it. `options.mime: true` also records
 message. Members: `messages`, `last`, `deliveries` (`RecordedDelivery[]`, each
 `{ message, mime? }`), `lastMime`, `find(predicate)` and `clear()`.
 
+### `@sdxc/mail/print`
+
+#### `new PrintTransport(options: PrintTransportOptions)`
+
+Writes each message to `options.write` instead of sending it, and reports it sent: the envelope,
+subject, date, `Message-ID` and extra headers, then the plain-text body. `options.mime: true`
+writes the raw MIME message instead. It writes only through the function it is given, so it runs
+anywhere: `ctx.stderr` in a command, `(text) => process.stderr.write(text)` in a script.
+
 ### `@sdxc/mail/cloudflare`
 
 #### `new CloudflareTransport(binding: SendEmailBinding)`
@@ -277,7 +281,36 @@ 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
-on the current log.
+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/middleware/cli`
+
+#### `mail(options: MailCommandOptions): CommandMiddleware` (default export)
+
+Publishes a `Mailer` as `ctx.email` on an [`@sdxc/cli`](https://www.npmjs.com/package/@sdxc/cli)
+command, so an admin command resends a message with the templates a route uses. `options` takes
+the router entry's fields, with `transport` a `Transport` or `(ctx) => Transport` per run. The
+queue flushes after the handler and each send is logged as in the router entry; a failed deferred
+send also fails the run with its error. On a laptop, pass a `PrintTransport` writing to the
+command's stderr, so a local run shows each message and never emails a real user.
+
+```typescript
+import { createCLI } from "@sdxc/cli";
+import mail from "@sdxc/mail/middleware/cli";
+import { PrintTransport } from "@sdxc/mail/print";
+
+let cli = createCLI({
+	name: "app",
+	commands,
+	middleware: [
+		mail({
+			transport: (ctx) => new PrintTransport({ write: (text) => ctx.stderr(text) }),
+			from: { email: "no-reply@example.com" },
+		}),
+	],
+});
+```
 
 ### `@sdxc/mail/unsubscribe`
 
@@ -313,7 +346,7 @@ router.post("/password-reset", async (context) => {
 });
 
 router.post("/invites", async (context) => {
-	context.email.later(new TeamInviteEmail(invite)); // sent after the response, failures logged
+	context.email.later(new TeamInviteEmail(invite.email, invite)); // sent after the response, failures logged
 	return new Response(null, { status: 204 });
 });
 ```
@@ -326,48 +359,26 @@ Gmail and Yahoo require one-click unsubscribe on subscribed and marketing mail.
 its target and list, and the mailer writes the headers:
 
 ```tsx
-import type { MailingList, Unsubscribe } from "@sdxc/mail";
-
-import { Email } from "@sdxc/mail";
+import { defineEmail, Email } from "@sdxc/mail";
 import { signUnsubscribeToken } from "@sdxc/mail/unsubscribe";
 import { unwrap } from "@sdxc/result";
 
-class DailyDigestEmail implements Email {
-	constructor(
-		private member: { id: string; email: string },
-		private token: string,
-	) {}
-
-	get to() {
-		return { email: this.member.email };
-	}
-
-	get subject() {
-		return "Your daily digest";
-	}
-
-	get unsubscribe(): Unsubscribe {
-		return {
-			url: `https://example.com/unsubscribe/${this.token}`,
-			mailto: "unsubscribe@example.com",
-		};
-	}
-
-	get list(): MailingList {
-		return { id: "daily-digest.example.com", name: "Daily digest" };
-	}
-
-	body() {
-		return (
-			<Email.Layout title="Daily digest">
-				<Email.Text>Here is what happened today.</Email.Text>
-			</Email.Layout>
-		);
-	}
-}
+const DailyDigestEmail = defineEmail<{ token: string }>({
+	subject: () => "Your daily digest",
+	unsubscribe: (props) => ({
+		url: `https://example.com/unsubscribe/${props.token}`,
+		mailto: "unsubscribe@example.com",
+	}),
+	list: () => ({ id: "daily-digest.example.com", name: "Daily digest" }),
+	body: () => () => (
+		<Email.Layout title="Daily digest">
+			<Email.Text>Here is what happened today.</Email.Text>
+		</Email.Layout>
+	),
+});
 
 let token = unwrap(await signUnsubscribeToken(secret, { subject: member.id, list: "digest" }));
-await mailer.send(new DailyDigestEmail(member, token));
+await mailer.send(new DailyDigestEmail(member.email, { token }));
 ```
 
 ```text

package/dist/cli.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `@sdxc/cli` middleware that publishes the app's mailer to a command as `ctx.email`, so an admin
+ * command resends an invitation or a receipt with the same templates a route uses, through
+ * whichever transport the app passes for where the command runs.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { AnyCommandContext, CommandMiddleware } from "@sdxc/cli";
+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 command-line mail middleware. */
+export interface MailCommandOptions extends Omit<MailerOptions, "transport"> {
+    /**
+     * Transport used for delivery, or a factory that resolves one per run from the command's
+     * context, such as one that reads `ctx.flags.remote` to pick the production transport.
+     */
+    transport: Transport | ((ctx: AnyCommandContext) => Transport);
+}
+/**
+ * Publishes a mailer as `ctx.email` for the run. Messages queued with `later()` send once the
+ * handler returns, each outcome is recorded on the run's log, and a failed deferred send fails
+ * the run, so whoever ran the command sees that a message never left.
+ *
+ * @param options - Transport and sender configuration; see {@link MailCommandOptions}.
+ * @returns A middleware that installs `ctx.email`.
+ * @example createCLI({ name: "app", commands, middleware: [mail({ transport: new MemoryTransport(), from: SENDER })] });
+ */
+export default function mail(options: MailCommandOptions): CommandMiddleware<{
+    key: typeof CurrentMailer;
+    value: Mailer;
+    property: "email";
+}>;

package/dist/cli.js

@@ -0,0 +1,62 @@
+/**
+ * `@sdxc/cli` middleware that publishes the app's mailer to a command as `ctx.email`, so an admin
+ * command resends an invitation or a receipt with the same templates a route uses, through
+ * whichever transport the app passes for where the command runs.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { currentLog } from "@sdxc/logger";
+import { failure, 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 the run. Messages queued with `later()` send once the
+ * handler returns, each outcome is recorded on the run's log, and a failed deferred send fails
+ * the run, so whoever ran the command sees that a message never left.
+ *
+ * @param options - Transport and sender configuration; see {@link MailCommandOptions}.
+ * @returns A middleware that installs `ctx.email`.
+ * @example createCLI({ name: "app", commands, middleware: [mail({ transport: new MemoryTransport(), from: SENDER })] });
+ */
+export default function mail(options) {
+    return async (ctx, next) => {
+        let transport = typeof options.transport === "function" ? options.transport(ctx) : options.transport;
+        let mailer = new Mailer({
+            transport,
+            from: options.from,
+            replyTo: options.replyTo,
+            headers: options.headers,
+        });
+        ctx.set(CurrentMailer, mailer, { property: "email" });
+        let failed;
+        try {
+            await next();
+        }
+        finally {
+            failed = await flush(mailer);
+        }
+        if (failed !== undefined)
+            return failure(failed);
+    };
+}
+/**
+ * Sends the mailer's deferred queue, recording each outcome on the run's log.
+ *
+ * @returns The first send's error, or `undefined` when every message left.
+ */
+async function flush(mailer) {
+    let log = currentLog();
+    let failed;
+    for (let result of await mailer.flush()) {
+        if (isFailure(result)) {
+            log?.warn("mail.send_failed", { error: result.error.message });
+            failed ??= result.error;
+        }
+        else {
+            log?.set({ mail: { sent: true } }).note("mail.sent", { message_id: result.data.messageId });
+        }
+    }
+    return failed;
+}

package/dist/context.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The context key the router and command-line middleware publish the mailer under, so code that
+ * reads it by key sends through the same mailer whichever host it runs in.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Mailer } from "./mailer.js";
+/** The mailer the current invocation sends through, installed as `ctx.email`. */
+export declare const CurrentMailer: {
+    defaultValue?: Mailer;
+};

package/dist/context.js

@@ -0,0 +1,10 @@
+/**
+ * The context key the router and command-line middleware publish the mailer under, so code that
+ * reads it by key sends through the same mailer whichever host it runs in.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createContextKey } from "remix/router";
+/** The mailer the current invocation sends through, installed as `ctx.email`. */
+export const CurrentMailer = createContextKey();

package/dist/define.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `defineEmail()`: an email declared as its props, a subject and a body component, from
+ * which the package builds the class the mailer sends. Every email built this way is its own
+ * class, so a test still finds a sent message with `instanceof`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Handle, RemixNode } from "remix/component";
+import type { Address, CalendarPart, Email, MailingList, Unsubscribe } from "./types.js";
+/**
+ * What an email says and looks like, written once per kind of email. Every member reads the
+ * props one instance was built with, so the subject and the body never disagree.
+ *
+ * @template Props - The data one email is built from, already translated for its reader.
+ */
+export interface EmailDefinition<Props extends object> {
+    /** Subject line, already in the reader's language. */
+    subject(props: Props): string;
+    /** Body component, rendered by the mailer into the HTML and plain-text parts. */
+    body: (handle: Handle<Props>) => () => RemixNode;
+    /** Per-email reply-to; the mailer's configuration supplies the default. */
+    replyTo?(props: Props): Address | Address[] | undefined;
+    /** Per-email headers, merged over the mailer's configured headers. */
+    headers?(props: Props): Record<string, string> | undefined;
+    /** One-click unsubscribe for optional mail, built per reader since its URL names them. */
+    unsubscribe?(props: Props): Unsubscribe | undefined;
+    /** List the email belongs to, written as `List-Id`. */
+    list?(props: Props): MailingList | undefined;
+    /** A calendar object, such as an invitation, sent alongside the rendered body. */
+    calendar?(props: Props): CalendarPart | undefined;
+}
+/**
+ * One email built by a {@link defineEmail} class, ready for `send()` or `later()`.
+ *
+ * @template Props - The data the email was built from.
+ */
+export interface DefinedEmail<Props extends object> extends Email {
+    /** Recipients, normalized to addresses from whatever form the constructor received. */
+    readonly to: Address | Address[];
+    /** The data the email was built from, so a test can assert on what a caller passed. */
+    readonly props: Props;
+}
+/**
+ * The class `defineEmail()` returns. A bare string recipient is the mailbox alone, the
+ * common case of mailing the address a record holds.
+ *
+ * @template Props - The data one email is built from.
+ */
+export interface EmailClass<Props extends object> {
+    new (to: string | Address | Address[], props: Props): DefinedEmail<Props>;
+}
+/**
+ * Builds an email class from its subject and body, so an email is its props and its markup.
+ *
+ * @param definition - The subject, the body component and any per-email delivery options.
+ * @returns A class constructed with the recipient and the props, sendable by any mailer.
+ * @example export const WelcomeEmail = defineEmail<WelcomeEmail.Props>({ subject: (props) => props.heading, body: WelcomeBody });
+ * @example await mailer.send(new WelcomeEmail("ada@example.com", { heading: "Welcome" }));
+ */
+export declare function defineEmail<Props extends object>(definition: EmailDefinition<Props>): EmailClass<Props>;

package/dist/define.js

@@ -0,0 +1,48 @@
+/**
+ * `defineEmail()`: an email declared as its props, a subject and a body component, from
+ * which the package builds the class the mailer sends. Every email built this way is its own
+ * class, so a test still finds a sent message with `instanceof`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createElement } from "remix/component";
+/**
+ * Builds an email class from its subject and body, so an email is its props and its markup.
+ *
+ * @param definition - The subject, the body component and any per-email delivery options.
+ * @returns A class constructed with the recipient and the props, sendable by any mailer.
+ * @example export const WelcomeEmail = defineEmail<WelcomeEmail.Props>({ subject: (props) => props.heading, body: WelcomeBody });
+ * @example await mailer.send(new WelcomeEmail("ada@example.com", { heading: "Welcome" }));
+ */
+export function defineEmail(definition) {
+    return class {
+        to;
+        props;
+        constructor(to, props) {
+            this.to = typeof to === "string" ? { email: to } : to;
+            this.props = props;
+        }
+        get subject() {
+            return definition.subject(this.props);
+        }
+        get replyTo() {
+            return definition.replyTo?.(this.props);
+        }
+        get headers() {
+            return definition.headers?.(this.props);
+        }
+        get unsubscribe() {
+            return definition.unsubscribe?.(this.props);
+        }
+        get list() {
+            return definition.list?.(this.props);
+        }
+        get calendar() {
+            return definition.calendar?.(this.props);
+        }
+        body() {
+            return createElement(definition.body, this.props);
+        }
+    };
+}

package/dist/index.d.ts

@@ -10,6 +10,7 @@
 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 { MailerOptions, SendOptions } from "./mailer.js";
 export type { RenderedEmail } from "./render.js";
 /**
@@ -20,6 +21,7 @@ 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 { formatAddress, toAddressList } from "./lib/address.js";
 export { htmlToText } from "./lib/html-to-text.js";
@@ -27,8 +29,8 @@ export { isEmail, Mailer } from "./mailer.js";
 export { buildMimeMessage } from "./mime.js";
 export { render } from "./render.js";
 /**
- * An email authored as a class: who it goes to, what it says, and what it
- * looks like, handed straight to `send()` or `later()`. Declared as an alias
+ * An email: who it goes to, what it says, and what it looks like, handed
+ * straight to `send()` or `later()`. Declared as an alias
  * so it can share the `Email` identifier with the layout kit below.
  */
 export type Email = EmailContract;

package/dist/index.js

@@ -8,6 +8,7 @@
  * @copyright Sergio Xalambrí 2026
  */
 import * as EmailComponents from "./components.js";
+export { defineEmail } from "./define.js";
 export { MailError } from "./errors.js";
 export { formatAddress, toAddressList } from "./lib/address.js";
 export { htmlToText } from "./lib/html-to-text.js";

package/dist/mailer.d.ts

@@ -58,7 +58,7 @@ export declare class Mailer {
      * @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));
+     * @example let result = await mailer.send(new TeamInviteEmail(invite.email, invite));
      */
     send(input: Message | Email, overrides?: SendOptions): Promise<Result<SentMessage, MailError>>;
     /**

package/dist/mailer.js

@@ -119,7 +119,7 @@ export class Mailer {
      * @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));
+     * @example let result = await mailer.send(new TeamInviteEmail(invite.email, invite));
      */
     async send(input, overrides) {
         let prepared = await this.#normalize(input, overrides);

package/dist/memory.d.ts

@@ -34,7 +34,7 @@ export interface RecordedDelivery {
  *
  * @example
  * let transport = new MemoryTransport();
- * await new Mailer({ transport, from: SENDER }).send(new TeamInviteEmail(invite));
+ * await new Mailer({ transport, from: SENDER }).send(new TeamInviteEmail(invite.email, invite));
  * expect(transport.find((message) => message.email instanceof TeamInviteEmail)).toBeDefined();
  *
  * @example

package/dist/memory.js

@@ -17,7 +17,7 @@ import { buildMimeMessage } from "./mime.js";
  *
  * @example
  * let transport = new MemoryTransport();
- * await new Mailer({ transport, from: SENDER }).send(new TeamInviteEmail(invite));
+ * await new Mailer({ transport, from: SENDER }).send(new TeamInviteEmail(invite.email, invite));
  * expect(transport.find((message) => message.email instanceof TeamInviteEmail)).toBeDefined();
  *
  * @example

package/dist/middleware.d.ts

@@ -11,6 +11,7 @@
 import type { Middleware, RequestContext } from "remix/router";
 import type { Address, Transport } from "./types.js";
 import { Mailer } from "./mailer.js";
+export { CurrentMailer } from "./context.js";
 /**
  * Declared here, in an imported module rather than an ambient .d.ts, so the
  * augmentation is applied in consuming projects that import the middleware.
@@ -40,10 +41,9 @@ export interface MailMiddlewareOptions {
     headers?: Record<string, string>;
 }
 /**
- * Creates a middleware that publishes a request-scoped mailer as `context.email`,
- * resolving a container-based transport once per request. The `later()` queue
- * flushes in a `finally` after `next()`; the response is already decided by then,
- * so a failed deferred send is a warning on the invocation's log rather than an error.
+ * Publishes a request-scoped mailer as `context.email`, under the {@link CurrentMailer} key the
+ * command-line entry shares. The `later()` queue flushes after `next()`, when the response is
+ * already decided, so a failed deferred send is a warning on the invocation's log.
  *
  * @param options - Transport and sender configuration; see {@link MailMiddlewareOptions}.
  * @returns A middleware that populates `context.email`.

package/dist/middleware.js

@@ -10,12 +10,13 @@
  */
 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";
 /**
- * Creates a middleware that publishes a request-scoped mailer as `context.email`,
- * resolving a container-based transport once per request. The `later()` queue
- * flushes in a `finally` after `next()`; the response is already decided by then,
- * so a failed deferred send is a warning on the invocation's log rather than an error.
+ * Publishes a request-scoped mailer as `context.email`, under the {@link CurrentMailer} key the
+ * command-line entry shares. The `later()` queue flushes after `next()`, when the response is
+ * already decided, so a failed deferred send is a warning on the invocation's log.
  *
  * @param options - Transport and sender configuration; see {@link MailMiddlewareOptions}.
  * @returns A middleware that populates `context.email`.
@@ -31,7 +32,7 @@ export default function mail(options) {
             replyTo: options.replyTo,
             headers: options.headers,
         });
-        context.email = mailer;
+        context.set(CurrentMailer, mailer, { property: "email" });
         try {
             return await next();
         }

package/dist/print.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Transport that prints each message instead of delivering it, for development and command
+ * lines run against local data: the message shows where the developer is looking and never
+ * reaches a real inbox. It writes through a function it is given, so it runs on any runtime.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { MailError } from "./errors.js";
+import type { NormalizedMessage, SentMessage, Transport } from "./types.js";
+/** Where a print transport writes, and in which form. */
+export interface PrintTransportOptions {
+    /**
+     * Receives each printed message as one string ending in a newline, such as `ctx.stderr`
+     * in a command or `(text) => process.stderr.write(text)` in a script.
+     */
+    write: (text: string) => void;
+    /**
+     * Print the raw MIME message, headers and every part, instead of the readable summary.
+     * @default false
+     */
+    mime?: boolean;
+}
+/**
+ * Transport that writes each message to `options.write` and reports it sent. The summary lists
+ * the envelope, the subject, the date, the `Message-ID` and any extra headers, then the
+ * plain-text body (the HTML one when a message has no text).
+ *
+ * @example new Mailer({ transport: new PrintTransport({ write: (text) => ctx.stderr(text) }), from: SENDER });
+ * @example new PrintTransport({ write: (text) => process.stderr.write(text), mime: true });
+ */
+export declare class PrintTransport implements Transport {
+    #private;
+    /**
+     * Creates the transport.
+     *
+     * @param options - Where to write and in which form; see {@link PrintTransportOptions}.
+     */
+    constructor(options: PrintTransportOptions);
+    /**
+     * Prints the message and reports success.
+     *
+     * @param message - The normalized message to print.
+     * @returns Success carrying the message's own `Message-ID`, since no provider assigned one.
+     */
+    send(message: NormalizedMessage): Promise<Result<SentMessage, MailError>>;
+}

package/dist/print.js

@@ -0,0 +1,72 @@
+/**
+ * Transport that prints each message instead of delivering it, for development and command
+ * lines run against local data: the message shows where the developer is looking and never
+ * reaches a real inbox. It writes through a function it is given, so it runs on any runtime.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { success } from "@sdxc/result";
+import { buildMimeMessage } from "./mime.js";
+/**
+ * Transport that writes each message to `options.write` and reports it sent. The summary lists
+ * the envelope, the subject, the date, the `Message-ID` and any extra headers, then the
+ * plain-text body (the HTML one when a message has no text).
+ *
+ * @example new Mailer({ transport: new PrintTransport({ write: (text) => ctx.stderr(text) }), from: SENDER });
+ * @example new PrintTransport({ write: (text) => process.stderr.write(text), mime: true });
+ */
+export class PrintTransport {
+    /** The function each printed message goes to. */
+    #write;
+    /** Whether messages print as raw MIME. */
+    #mime;
+    /**
+     * Creates the transport.
+     *
+     * @param options - Where to write and in which form; see {@link PrintTransportOptions}.
+     */
+    constructor(options) {
+        this.#write = options.write;
+        this.#mime = options.mime ?? false;
+    }
+    /**
+     * Prints the message and reports success.
+     *
+     * @param message - The normalized message to print.
+     * @returns Success carrying the message's own `Message-ID`, since no provider assigned one.
+     */
+    async send(message) {
+        this.#write(this.#mime ? ensureNewline(buildMimeMessage(message)) : summarize(message));
+        return success({ messageId: message.messageId });
+    }
+}
+/** The readable form of a message: one header per line, a blank line, then the body. */
+function summarize(message) {
+    let lines = [`From: ${formatAddresses([message.from])}`, `To: ${formatAddresses(message.to)}`];
+    if (message.cc.length > 0)
+        lines.push(`Cc: ${formatAddresses(message.cc)}`);
+    if (message.bcc.length > 0)
+        lines.push(`Bcc: ${formatAddresses(message.bcc)}`);
+    if (message.replyTo.length > 0)
+        lines.push(`Reply-To: ${formatAddresses(message.replyTo)}`);
+    lines.push(`Subject: ${message.subject}`);
+    lines.push(`Date: ${message.date.toUTCString()}`);
+    lines.push(`Message-ID: ${message.messageId}`);
+    for (let [name, value] of Object.entries(message.headers))
+        lines.push(`${name}: ${value}`);
+    let body = message.text ?? message.html ?? "";
+    return `${lines.join("\n")}\n\n${ensureNewline(body)}`;
+}
+/** Mailboxes as a mail client shows them: `Name <email>`, or the bare address without a name. */
+function formatAddresses(addresses) {
+    return addresses
+        .map((address) => address.name === undefined || address.name === ""
+        ? address.email
+        : `${address.name} <${address.email}>`)
+        .join(", ");
+}
+/** `text` ending in exactly one newline, so consecutive messages never run together. */
+function ensureNewline(text) {
+    return text.endsWith("\n") ? text : `${text}\n`;
+}

package/dist/types.d.ts

@@ -155,8 +155,8 @@ export interface Transport {
     send(message: NormalizedMessage): Promise<Result<SentMessage, MailError>>;
 }
 /**
- * An email authored as a class: who it goes to, what it says, and what it looks
- * like. Sender identity lives on the mailer, and a subject arrives already
+ * 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.
  */
 export interface Email {

package/package.json

@@ -1,27 +1,37 @@
 {
 	"name": "@sdxc/mail",
-	"version": "2026.10.13",
+	"version": "2026.10.17",
 	"description": "Transport-agnostic transactional email with pluggable transports and remix/component rendering",
 	"license": "MIT",
 	"type": "module",
 	"exports": {
 		".": "./dist/index.js",
+		"./cloudflare": "./dist/cloudflare.js",
 		"./markdown": "./dist/markdown.js",
 		"./memory": "./dist/memory.js",
+		"./print": "./dist/print.js",
 		"./middleware": "./dist/middleware.js",
-		"./cloudflare": "./dist/cloudflare.js",
+		"./middleware/cli": "./dist/cli.js",
 		"./unsubscribe": "./dist/unsubscribe.js"
 	},
 	"dependencies": {
 		"@sdxc/crypto": "2026.10.13",
-		"@sdxc/highlight": "2026.10.13",
-		"@sdxc/logger": "2026.10.13",
-		"@sdxc/markdown": "2026.10.13",
+		"@sdxc/highlight": "2026.10.16",
+		"@sdxc/logger": "2026.10.16",
+		"@sdxc/markdown": "2026.10.16",
 		"@sdxc/result": "2026.10.13",
-		"@sdxc/uuid": "2026.10.13",
+		"@sdxc/uuid": "2026.10.13"
+	},
+	"peerDependencies": {
+		"@sdxc/cli": "2026.10.16",
 		"remix": "3.0.0"
 	},
-	"gitHead": "5ff758a57e35480a8db7abd24f1d9527b81bfb51",
+	"peerDependenciesMeta": {
+		"@sdxc/cli": {
+			"optional": true
+		}
+	},
+	"gitHead": "4f4bce453e9afe69f53194368af9e9739d73a876",
 	"publishConfig": {
 		"access": "public"
 	},
@@ -30,7 +40,7 @@
 		"url": "git+https://github.com/sergiodxa/monorepo.git",
 		"directory": "packages/mail"
 	},
-	"homepage": "https://sdxc.sergiodxa.com/api/mail",
+	"homepage": "https://sdxc.dev/api/mail",
 	"author": {
 		"name": "Sergio Xalambrí",
 		"url": "https://sergiodxa.com"