@sdxc/mail 2026.10.16 → 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.
@@ -351,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 });
 });
 ```
@@ -364,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/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/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,6 +1,6 @@
 {
 	"name": "@sdxc/mail",
-	"version": "2026.10.16",
+	"version": "2026.10.17",
 	"description": "Transport-agnostic transactional email with pluggable transports and remix/component rendering",
 	"license": "MIT",
 	"type": "module",
@@ -31,7 +31,7 @@
 			"optional": true
 		}
 	},
-	"gitHead": "1e547d8431568f5ed9bdb079ca3046c936240fde",
+	"gitHead": "4f4bce453e9afe69f53194368af9e9739d73a876",
 	"publishConfig": {
 		"access": "public"
 	},