@sdxc/mail 2026.9.15 → 2026.9.28

package/README.md

@@ -25,7 +25,8 @@ alongside this package.
 
 Entry points: `@sdxc/mail` for the mailer, renderer, MIME builder and layout kit;
 `@sdxc/mail/markdown` for markdown bodies; `@sdxc/mail/memory` and `@sdxc/mail/cloudflare`
-for transports; `@sdxc/mail/middleware` for the router middleware. A transport ships from
+for transports; `@sdxc/mail/middleware` for the router middleware; `@sdxc/mail/unsubscribe`
+for the endpoint behind a one-click unsubscribe link. A transport ships from
 its own subpath, so importing one never pulls another's platform dependency into a bundle.
 
 ## Usage
@@ -214,8 +215,8 @@ alone. `render()` applies this for you.
 
 ### `MailError`
 
-The single error type the package reports. The original provider or render error is kept
-as `cause`, so one log line can name the root problem.
+The error every send failure reports. The original provider or render error is kept as
+`cause`, so one log line can name the root problem.
 
 ### `Email` (layout kit)
 
@@ -279,6 +280,35 @@ interface Message {
 	/** Explicit values; omitted means "now" and a generated id. Set both to keep tests deterministic. */
 	date?: Date;
 	messageId?: string;
+	/** Optional mail only; see "Bulk Mail". */
+	unsubscribe?: Unsubscribe;
+	list?: MailingList;
+	/** A calendar object sent beside the bodies; see "Calendar Invitations". */
+	calendar?: CalendarPart;
+}
+
+interface CalendarPart {
+	/** iTIP method written as `method=`, e.g. `REQUEST`; must match the content's `METHOD`. */
+	method: string;
+	/** The serialized iCalendar object. */
+	content: string;
+	/** Also attach the calendar as a file with this name, e.g. `invite.ics`. */
+	filename?: string;
+}
+
+interface Unsubscribe {
+	/** Must be `https:`; receives the RFC 8058 POST with no session. */
+	url: string | URL;
+	/** A bare address (sent with `?subject=unsubscribe`) or a full `mailto:` URI. */
+	mailto?: string;
+	/** `false` omits `List-Unsubscribe-Post`. Defaults to `true`. */
+	oneClick?: boolean;
+}
+
+interface MailingList {
+	/** RFC 2919 list-id, e.g. `digest.example.com`. */
+	id: string;
+	name?: string;
 }
 
 interface Email {
@@ -287,6 +317,9 @@ interface Email {
 	body(): RemixElement;
 	readonly replyTo?: Address | Address[];
 	readonly headers?: Record<string, string>;
+	readonly unsubscribe?: Unsubscribe;
+	readonly list?: MailingList;
+	readonly calendar?: CalendarPart;
 }
 
 interface Transport {
@@ -301,7 +334,8 @@ interface SentMessage {
 
 `NormalizedMessage` is what a transport receives: every field of `Message` with defaults
 applied, address fields as lists, `date` and `messageId` always present, a derived `text`
-part, and `email` carrying the source `Email` when the message came from one — which
+part, `headers` including the generated `List-*` ones, `unsubscribe` and `list` as the
+option or `null`, `calendar` when one was set, and `email` carrying the source `Email` when the message came from one — which
 transports ignore and tests use to identify a send by type. `RenderedEmail` is
 `{ html, text }`, `SendOptions` is `Partial<Message>`, `MailerOptions` is the
 constructor's options object, `EmailTableRow` is one `{ label, value }` row of an
@@ -356,7 +390,10 @@ class. Success carries the identifier the platform assigned; a refusal arrives a
 
 The binding writes its own `Date` and `Message-ID`, so the values a normalized message
 carries stay local, and it takes one `replyTo` mailbox rather than a list, so the first is
-the one that ships. `SendEmailBinding`, `SendEmailMessage` and `SendEmailResult` are
+the one that ships. Its payload has no field for an alternative part, so a `calendar`
+travels as one attachment typed `text/calendar; method=…; charset=UTF-8`, named by
+`filename` or `invite.ics`. `SendEmailBinding`, `SendEmailMessage`, `SendEmailAttachment`
+and `SendEmailResult` are
 exported as the seam those platform assumptions live behind, declared locally so this
 package typechecks outside a Workers project. See the
 [Cloudflare email routing docs](https://developers.cloudflare.com/email-routing/email-workers/send-email-workers/)
@@ -377,13 +414,130 @@ out. With no log current the outcomes are dropped. The module augments `RequestC
 so `context.email` is typed wherever the middleware is imported. Despite the name, it is
 the object that _sends_ mail, not the current user's address.
 
+### `@sdxc/mail/unsubscribe`
+
+#### `signUnsubscribeToken(secret, claims, options?): Promise<Result<string, MailError>>`
+
+Signs `{ subject, list }` into one URL path segment: the hex HMAC-SHA-256 followed by the
+base64url payload. `subject` must be an opaque id — an email address is refused, since the
+token lands in URLs and logs — and `list` a name without colons. `options.expiresAt` makes
+the link stop working; omitted, it never expires, because a provider may POST long after
+delivery. `options.purpose` (default `"unsubscribe:v1:"`) prefixes the MAC input, so a
+secret shared with something else cannot mint these tokens.
+
+#### `verifyUnsubscribeToken(secret, token, options?): Promise<Result<UnsubscribeToken.Claims, InvalidUnsubscribeTokenError>>`
+
+Checks the MAC in constant time and returns `{ subject, list, issuedAt }`. Malformed,
+tampered, foreign-key, foreign-purpose and expired tokens all fail with the same
+`InvalidUnsubscribeTokenError`, so the endpoint answers every case alike. `issuedAt` is
+`null` for a token whose payload names only `list:subject`, the shape an app signing with
+the same scheme by hand produces; pass that app's `purpose` to verify its links.
+
+#### `isOneClickUnsubscribe(form: FormData): boolean`
+
+Whether a parsed body is RFC 8058's `List-Unsubscribe=One-Click`, URL-encoded or
+multipart. It tells the provider's POST, which reads no response, from a person pressing
+the confirmation page's button.
+
+## Bulk Mail
+
+Gmail and Yahoo require one-click unsubscribe on subscribed and marketing mail: a
+`List-Unsubscribe` header with an HTTPS URL, `List-Unsubscribe-Post:
+List-Unsubscribe=One-Click`, both covered by DKIM, and the unsubscribe honored within two
+days. With those present the provider shows its own "Unsubscribe" button, and a recipient
+who presses it stops receiving mail instead of reporting spam. Transactional mail
+(verification, resets, sign-in alerts) is exempt and leaves the options unset.
+
+An optional email declares its target and list; the mailer writes the headers:
+
+```typescript
+import type { Email, MailingList, Unsubscribe } from "@sdxc/mail";
+
+class DailyDigestEmail implements Email {
+	// to, subject, body() ...
+
+	get unsubscribe(): Unsubscribe {
+		return { url: this.digest.unsubscribeUrl, mailto: "unsubscribe@example.com" };
+	}
+
+	get list(): MailingList {
+		return { id: "daily-digest.example.com", name: "Daily digest" };
+	}
+}
+```
+
+```text
+List-Unsubscribe: <https://example.com/unsubscribe/…>, <mailto:unsubscribe@example.com?subject=unsubscribe>
+List-Unsubscribe-Post: List-Unsubscribe=One-Click
+List-Id: Daily digest <daily-digest.example.com>
+```
+
+The send fails with a `MailError` when the URL is not `https:`, `mailto` names no address,
+`list.id` is not a list-id, or the mailer, message or email headers already contain
+`List-Unsubscribe`, `List-Unsubscribe-Post` or `List-Id` (any case) alongside the matching
+option — a half-migrated email fails loudly instead of sending two targets. A hand-written
+header keeps working while its option is unset.
+
+The URL receives a POST from the provider's servers with no cookies, so it carries a
+signed token and sits outside any auth guard. `GET` renders a confirmation and changes
+nothing, because link scanners follow every URL; `POST` acts:
+
+```typescript
+import { isOneClickUnsubscribe, verifyUnsubscribeToken } from "@sdxc/mail/unsubscribe";
+import { isSuccess } from "@sdxc/result";
+
+let claims = await verifyUnsubscribeToken(env.UNSUBSCRIBE_SECRET, token);
+if (isSuccess(claims)) await unsubscribe(claims.data.subject, claims.data.list);
+if (isOneClickUnsubscribe(formData)) return new Response(null, { status: 200 });
+return renderDonePage();
+```
+
+Rotating the secret breaks every link already delivered. DKIM coverage of the two headers
+is decided by the transport's platform (Cloudflare's `send_email` binding signs for the
+verified domain); check a delivered message's `h=` tag lists `list-unsubscribe` and
+`list-unsubscribe-post`.
+
+## Calendar Invitations
+
+An iTIP invitation (RFC 5546) is a calendar object sent as a `text/calendar` part whose
+`method=` parameter repeats the object's `METHOD`; Gmail, Outlook and Apple Mail read it
+and show the event with accept and decline buttons. A message or an email carries one as
+`calendar`, with the content written by any iCalendar library:
+
+```typescript
+await mailer.send({
+	to: { email: "ada@example.com" },
+	subject: "Scheduled maintenance on Saturday",
+	html: "<p>The database is read-only from 02:00 to 04:00 UTC.</p>",
+	calendar: { method: "REQUEST", content: ics, filename: "invite.ics" },
+});
+```
+
+`buildMimeMessage` places the calendar last in `multipart/alternative`, the most
+preferred part, and with `filename` also attaches it as `application/ics` inside
+`multipart/mixed`, for clients that only offer attachments:
+
+```text
+multipart/mixed
+├── multipart/alternative
+│   ├── text/plain; charset=utf-8
+│   ├── text/html; charset=utf-8
+│   └── text/calendar; method=REQUEST; charset=UTF-8
+└── application/ics; name="invite.ics"  (attachment)
+```
+
+The send fails with a `MailError` when `method` is not a token or `filename` is not
+printable ASCII free of quotes, backslashes and slashes, since both are written into
+headers. A calendar still needs a body beside it, for clients that show no invitation.
+
 ## MIME Guarantees
 
 What `buildMimeMessage` produces, for a transport that speaks raw messages:
 
-- **Structure** — both body parts produce `multipart/alternative` with the plain-text part
-  first, which RFC 2046 reads as least to most preferred; a single part produces a
-  single-part message with no boundary.
+- **Structure** — several parts produce `multipart/alternative` ordered plain text, HTML,
+  calendar, which RFC 2046 reads as least to most preferred; a single part produces a
+  single-part message with no boundary, and a calendar attachment wraps the body in
+  `multipart/mixed`.
 - **Headers** — `From`, `To`, `Cc`, `Reply-To`, `Subject`, `Date`, `Message-ID`,
   `MIME-Version`, then custom headers, then the `Content-*` headers. `Bcc` is absent,
   since those recipients are addressed by the envelope, and a custom header repeating a

package/dist/cloudflare.d.ts

@@ -35,6 +35,16 @@ export interface SendEmailMessage {
     html?: string;
     /** Extra headers to set on the assembled message. */
     headers?: Record<string, string>;
+    /** Files the platform attaches after the bodies. */
+    attachments?: SendEmailAttachment[];
+}
+/** A file the binding attaches to the message it composes. */
+export interface SendEmailAttachment {
+    disposition: "attachment";
+    filename: string;
+    /** Media type of the file, parameters included. */
+    type: string;
+    content: string;
 }
 /** What the binding reports back for an accepted message. */
 export interface SendEmailResult {

package/dist/cloudflare.js

@@ -17,6 +17,26 @@ function optionalAddresses(addresses) {
         return undefined;
     return addresses.map(formatAddress);
 }
+/** Name a calendar attachment takes when the caller named none. */
+const CALENDAR_FILENAME = "invite.ics";
+/**
+ * Carries a calendar part as the one attachment the binding composes, since its
+ * payload has no alternative-part field; the `method=` parameter on the file's type
+ * is what calendar clients read to offer accept and decline.
+ */
+function calendarAttachments(message) {
+    if (!message.calendar)
+        return undefined;
+    let { method, content, filename } = message.calendar;
+    return [
+        {
+            disposition: "attachment",
+            filename: filename ?? CALENDAR_FILENAME,
+            type: `text/calendar; method=${method}; charset=UTF-8`,
+            content,
+        },
+    ];
+}
 /**
  * Maps a normalized message onto the binding's send payload. Only the first
  * reply-to mailbox survives, since the platform's field holds one address, so
@@ -34,6 +54,7 @@ function toPayload(message) {
         text: message.text,
         html: message.html,
         headers: message.headers,
+        attachments: calendarAttachments(message),
     };
 }
 /**

package/dist/errors.d.ts

@@ -1,7 +1,7 @@
 /**
- * The single error type the mail package reports. Every failure a caller can
- * branch on — invalid message, failed render, rejected delivery — arrives as a
- * `MailError` inside a `Result`, so no send path throws.
+ * The errors the mail package reports inside a `Result`: `MailError` for every
+ * send failure — invalid message, failed render, rejected delivery — and
+ * `InvalidUnsubscribeTokenError` for a token the unsubscribe endpoint refuses.
  *
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
@@ -20,3 +20,17 @@ export declare class MailError extends Error {
      */
     constructor(message: string, options?: ErrorOptions);
 }
+/**
+ * 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
+ * endpoint answers all of them the same way and leaks nothing about which failed.
+ */
+export declare class InvalidUnsubscribeTokenError extends Error {
+    name: string;
+    /**
+     * Creates the error.
+     *
+     * @param options - Standard error options; `cause` keeps a crypto failure for logs.
+     */
+    constructor(options?: ErrorOptions);
+}

package/dist/errors.js

@@ -1,7 +1,7 @@
 /**
- * The single error type the mail package reports. Every failure a caller can
- * branch on — invalid message, failed render, rejected delivery — arrives as a
- * `MailError` inside a `Result`, so no send path throws.
+ * The errors the mail package reports inside a `Result`: `MailError` for every
+ * send failure — invalid message, failed render, rejected delivery — and
+ * `InvalidUnsubscribeTokenError` for a token the unsubscribe endpoint refuses.
  *
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
@@ -22,3 +22,19 @@ export class MailError extends Error {
         super(message, options);
     }
 }
+/**
+ * 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
+ * endpoint answers all of them the same way and leaks nothing about which failed.
+ */
+export class InvalidUnsubscribeTokenError extends Error {
+    name = "InvalidUnsubscribeTokenError";
+    /**
+     * Creates the error.
+     *
+     * @param options - Standard error options; `cause` keeps a crypto failure for logs.
+     */
+    constructor(options) {
+        super("The unsubscribe token is invalid or has expired.", options);
+    }
+}

package/dist/index.d.ts

@@ -9,7 +9,7 @@
  */
 import type { Email as EmailContract } from "./types.js";
 import * as EmailComponents from "./components.js";
-export type { Address, Message, NormalizedMessage, SentMessage, Transport } from "./types.js";
+export type { Address, CalendarPart, MailingList, Message, NormalizedMessage, SentMessage, Transport, Unsubscribe, } from "./types.js";
 export type { MailerOptions, SendOptions } from "./mailer.js";
 export type { RenderedEmail } from "./render.js";
 /**

package/dist/lib/list-headers.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Builds the `List-Unsubscribe`, `List-Unsubscribe-Post` and `List-Id` headers from a
+ * message's structured options, so every sender gets the syntax RFC 2369, RFC 8058 and
+ * RFC 2919 require and a non-compliant target fails the send instead of the button.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { MailingList, Unsubscribe } from "../types.js";
+import { MailError } from "../errors.js";
+/**
+ * Generates the list headers a message's options ask for. A caller-written header that
+ * a set option would also generate fails the send, so a half-migrated email reports the
+ * mistake instead of shipping two different unsubscribe targets.
+ *
+ * @param headers - Every header already merged for the message: mailer, message and email.
+ * @param options - The message's `unsubscribe` and `list` options.
+ * @returns The headers to add, or a `MailError` naming the invalid option or the conflict.
+ */
+export declare function buildListHeaders(headers: Record<string, string>, options: {
+    unsubscribe: Unsubscribe | null;
+    list: MailingList | null;
+}): Result<Record<string, string>, MailError>;

package/dist/lib/list-headers.js

@@ -0,0 +1,110 @@
+/**
+ * Builds the `List-Unsubscribe`, `List-Unsubscribe-Post` and `List-Id` headers from a
+ * message's structured options, so every sender gets the syntax RFC 2369, RFC 8058 and
+ * RFC 2919 require and a non-compliant target fails the send instead of the button.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { failure, isFailure, success } from "@sdxc/result";
+import { MailError } from "../errors.js";
+import { formatAddress, isValidAddress } from "./address.js";
+/** RFC 8058's fixed `List-Unsubscribe-Post` value, the only one providers act on. */
+const ONE_CLICK = "List-Unsubscribe=One-Click";
+/** RFC 2919 list-id: dot-atom text with at least two labels. */
+const LIST_ID = /^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)+$/;
+/** Control characters, which would split a header line or smuggle another header in. */
+const CONTROL_CHARACTERS = /\p{Cc}/u;
+/**
+ * Finds a caller-written header with the given name, compared case-insensitively as
+ * mail header names are, so a hand-written `list-id` conflicts with the generated one.
+ */
+function findHeader(headers, names) {
+    return Object.keys(headers).find((key) => names.includes(key.toLowerCase()));
+}
+/**
+ * Resolves the unsubscribe target into its `List-Unsubscribe` value. The HTTPS URL
+ * comes first because RFC 8058 one-click requires it; a bare `mailto` address gets a
+ * subject so a client that composes the mail sends something a list server recognizes.
+ */
+function unsubscribeValue(unsubscribe) {
+    let url = URL.parse(unsubscribe.url);
+    if (url?.protocol !== "https:") {
+        return failure(new MailError(`The unsubscribe URL "${unsubscribe.url}" must be https:.`));
+    }
+    let uris = [url.href];
+    if (unsubscribe.mailto !== undefined) {
+        let mailto = mailtoUri(unsubscribe.mailto);
+        if (mailto === null) {
+            return failure(new MailError(`"${unsubscribe.mailto}" is not an unsubscribe address.`));
+        }
+        uris.push(mailto);
+    }
+    return success(uris.map((uri) => `<${uri}>`).join(", "));
+}
+/**
+ * Turns the `mailto` option into a URI, or `null` when it names no routable address.
+ * A full URI keeps whatever query its author chose, normalized only by URL parsing so
+ * it cannot break out of its angle brackets.
+ */
+function mailtoUri(mailto) {
+    if (!/^mailto:/i.test(mailto)) {
+        if (!isValidAddress({ email: mailto }))
+            return null;
+        return `mailto:${mailto}?subject=unsubscribe`;
+    }
+    let url = URL.parse(mailto);
+    if (!url || !isValidAddress({ email: decodeURIComponent(url.pathname) }))
+        return null;
+    return url.href;
+}
+/**
+ * Formats `List-Id`, whose id always sits in angle brackets, quoting a description the
+ * same way a mailbox's display name is quoted.
+ */
+function listIdValue(list) {
+    if (!LIST_ID.test(list.id)) {
+        return failure(new MailError(`"${list.id}" is not a valid list id.`));
+    }
+    if (list.name !== undefined && CONTROL_CHARACTERS.test(list.name)) {
+        return failure(new MailError("A list name cannot contain control characters."));
+    }
+    if (!list.name?.trim())
+        return success(`<${list.id}>`);
+    return success(formatAddress({ email: list.id, name: list.name }));
+}
+/**
+ * Generates the list headers a message's options ask for. A caller-written header that
+ * a set option would also generate fails the send, so a half-migrated email reports the
+ * mistake instead of shipping two different unsubscribe targets.
+ *
+ * @param headers - Every header already merged for the message: mailer, message and email.
+ * @param options - The message's `unsubscribe` and `list` options.
+ * @returns The headers to add, or a `MailError` naming the invalid option or the conflict.
+ */
+export function buildListHeaders(headers, options) {
+    let generated = {};
+    if (options.unsubscribe) {
+        let conflict = findHeader(headers, ["list-unsubscribe", "list-unsubscribe-post"]);
+        if (conflict) {
+            return failure(new MailError(`The "${conflict}" header conflicts with the unsubscribe option.`));
+        }
+        let value = unsubscribeValue(options.unsubscribe);
+        if (isFailure(value))
+            return value;
+        generated["List-Unsubscribe"] = value.data;
+        if (options.unsubscribe.oneClick !== false)
+            generated["List-Unsubscribe-Post"] = ONE_CLICK;
+    }
+    if (options.list) {
+        let conflict = findHeader(headers, ["list-id"]);
+        if (conflict) {
+            return failure(new MailError(`The "${conflict}" header conflicts with the list option.`));
+        }
+        let value = listIdValue(options.list);
+        if (isFailure(value))
+            return value;
+        generated["List-Id"] = value.data;
+    }
+    return success(generated);
+}

package/dist/mailer.js

@@ -12,7 +12,15 @@ import { failure, isFailure, success, wrap } from "@sdxc/result";
 import { MailError } from "./errors.js";
 import { isValidAddress, toAddressList } from "./lib/address.js";
 import { htmlToText } from "./lib/html-to-text.js";
+import { buildListHeaders } from "./lib/list-headers.js";
 import { render } from "./render.js";
+/** An iTIP method is an iana-token or x-name, which is all a `method=` parameter may hold. */
+const METHOD = /^[A-Za-z0-9-]+$/;
+/**
+ * Printable ASCII without quotes, backslashes or path separators, so the name travels in
+ * a quoted `filename` parameter unchanged and no client reads a directory into it.
+ */
+const FILENAME = /^[\x20-\x21\x23-\x2E\x30-\x5B\x5D-\x7E]+$/;
 /**
  * Reports whether a value is an `Email` rather than a plain `Message`.
  * Discrimination is structural: a callable `body` is the one member only an email
@@ -50,9 +58,9 @@ function generateMessageId(from) {
     return `<${crypto.randomUUID()}@${domain}>`;
 }
 /**
- * Rejects messages no transport could deliver, so the failure names the mistake
- * instead of surfacing as a provider error later: a missing sender or recipient,
- * an address that cannot be routed, or a message with no body at all.
+ * Rejects messages no transport could deliver, so the failure names the mistake instead of
+ * a provider error: a missing sender or recipient, an unroutable address, no body at all,
+ * or a calendar method or filename that would break the header it is written into.
  */
 function validate(message) {
     if (!message.from.email)
@@ -69,6 +77,15 @@ function validate(message) {
     if (!message.html && !message.text) {
         return failure(new MailError("A message needs an HTML or a plain-text body."));
     }
+    if (message.calendar) {
+        let { method, filename } = message.calendar;
+        if (!METHOD.test(method)) {
+            return failure(new MailError(`"${method}" is not a calendar method.`));
+        }
+        if (filename !== undefined && !FILENAME.test(filename)) {
+            return failure(new MailError(`"${filename}" is not a calendar attachment filename.`));
+        }
+    }
     return success(message);
 }
 /**
@@ -155,14 +172,18 @@ export class Mailer {
             subject: input.subject,
             replyTo: input.replyTo,
             headers: input.headers,
+            unsubscribe: input.unsubscribe,
+            list: input.list,
+            calendar: input.calendar,
             html: rendered.data.html,
             text: rendered.data.text,
         });
     }
     /**
      * Produces the shape transports read: configured defaults filled in, address
-     * lists coerced, a plain-text part derived, and the source email recorded for
-     * type-based lookup. Validation runs last, so a failure describes the final message.
+     * lists coerced, a plain-text part derived, the `List-*` headers generated from
+     * their options, and the source email recorded for type-based lookup. Validation
+     * runs last, so a failure describes the final message.
      */
     async #normalize(input, overrides) {
         let converted = await this.#toMessage(input);
@@ -170,6 +191,12 @@ export class Mailer {
             return converted;
         let message = { ...converted.data, ...overrides };
         let from = message.from ?? this.#options.from;
+        let headers = { ...this.#options.headers, ...message.headers };
+        let unsubscribe = message.unsubscribe ?? null;
+        let list = message.list ?? null;
+        let listHeaders = buildListHeaders(headers, { unsubscribe, list });
+        if (isFailure(listHeaders))
+            return listHeaders;
         return validate({
             from,
             to: toAddressList(message.to),
@@ -179,9 +206,12 @@ export class Mailer {
             subject: message.subject,
             html: message.html,
             text: derivePlainText(converted.data, overrides),
-            headers: { ...this.#options.headers, ...message.headers },
+            headers: { ...headers, ...listHeaders.data },
             date: message.date ?? new Date(),
             messageId: message.messageId ?? generateMessageId(from),
+            unsubscribe,
+            list,
+            calendar: message.calendar,
             email: isEmail(input) ? input : undefined,
         });
     }

package/dist/mime.d.ts

@@ -1,7 +1,7 @@
 /**
  * Assembles a normalized message into the raw RFC 5322 message a transport whose
  * provider takes MIME has to hand over: folded headers, encoded words for
- * non-ASCII text, a `multipart/alternative` body when both parts exist, and CRLF
+ * non-ASCII text, a `multipart/alternative` body when several parts exist, and CRLF
  * line endings throughout. It lives at the package root so any raw-MIME transport
  * can reuse it and so its tests need no runtime-specific import.
  *
@@ -10,9 +10,9 @@
  */
 import type { NormalizedMessage } from "./types.js";
 /**
- * Assembles a normalized message into a raw RFC 5322 message, ordering plain text
- * before HTML per RFC 2046 when both parts exist; with neither part, it yields an
- * empty text part, since validation guarantees that case never reaches a transport.
+ * Assembles a normalized message into a raw RFC 5322 message: one part is written
+ * alone, several go in `multipart/alternative`, and a calendar attachment wraps that in
+ * `multipart/mixed`. With no part at all it writes an empty text part.
  *
  * @param message - The normalized message a transport received.
  * @returns The complete message, ready to hand to a provider that takes raw MIME.

package/dist/mime.js

@@ -1,7 +1,7 @@
 /**
  * Assembles a normalized message into the raw RFC 5322 message a transport whose
  * provider takes MIME has to hand over: folded headers, encoded words for
- * non-ASCII text, a `multipart/alternative` body when both parts exist, and CRLF
+ * non-ASCII text, a `multipart/alternative` body when several parts exist, and CRLF
  * line endings throughout. It lives at the package root so any raw-MIME transport
  * can reuse it and so its tests need no runtime-specific import.
  *
@@ -331,44 +331,80 @@ function buildHeaders(message) {
     }
     return headers;
 }
-/** Writes the `Content-*` headers that describe one part's type and encoding. */
-function buildContentHeaders(part) {
-    return [
-        foldHeader("Content-Type", `${part.contentType}; charset=utf-8`),
+/** Writes the `Content-*` headers that describe one part's type, encoding and disposition. */
+function toEntity(part) {
+    let headers = [
+        foldHeader("Content-Type", part.contentType),
         foldHeader("Content-Transfer-Encoding", part.encoding),
     ];
+    if (part.disposition)
+        headers.push(foldHeader("Content-Disposition", part.disposition));
+    return { headers, body: part.body };
 }
 /**
- * Assembles a normalized message into a raw RFC 5322 message, ordering plain text
- * before HTML per RFC 2046 when both parts exist; with neither part, it yields an
- * empty text part, since validation guarantees that case never reaches a transport.
+ * Nests entities in one multipart entity. Each delimiter line is its own line, and the
+ * boundary is checked against the nested bodies, inner boundaries included.
+ */
+function toMultipart(subtype, entities) {
+    let boundary = selectBoundary(entities);
+    let lines = [];
+    for (let entity of entities)
+        lines.push(`--${boundary}`, ...entity.headers, "", entity.body);
+    lines.push(`--${boundary}--`);
+    return {
+        headers: [foldHeader("Content-Type", `multipart/${subtype}; boundary="${boundary}"`)],
+        body: lines.join(CRLF),
+    };
+}
+/**
+ * The alternative parts, in increasing order of preference as RFC 2046 orders them:
+ * plain text, HTML, then the calendar, which clients that understand iTIP render as
+ * an invitation and every other client skips.
+ */
+function alternativeParts(message) {
+    let parts = [];
+    if (message.text)
+        parts.push(encodePart("text/plain; charset=utf-8", message.text));
+    if (message.html)
+        parts.push(encodePart("text/html; charset=utf-8", message.html));
+    if (message.calendar) {
+        let type = `text/calendar; method=${message.calendar.method}; charset=UTF-8`;
+        parts.push(encodePart(type, message.calendar.content));
+    }
+    return parts;
+}
+/**
+ * The calendar as a downloadable file. It is typed `application/ics` so a client that
+ * already acts on the `text/calendar` alternative does not process the invitation twice.
+ */
+function calendarAttachment(message) {
+    let filename = message.calendar?.filename;
+    if (!message.calendar || filename === undefined)
+        return undefined;
+    return {
+        contentType: `application/ics; name="${filename}"`,
+        encoding: "base64",
+        disposition: `attachment; filename="${filename}"`,
+        body: toBase64Body(message.calendar.content),
+    };
+}
+/**
+ * Assembles a normalized message into a raw RFC 5322 message: one part is written
+ * alone, several go in `multipart/alternative`, and a calendar attachment wraps that in
+ * `multipart/mixed`. With no part at all it writes an empty text part.
  *
  * @param message - The normalized message a transport received.
  * @returns The complete message, ready to hand to a provider that takes raw MIME.
  * @example let raw = buildMimeMessage(message); // "From: ...\r\n\r\n..."
  */
 export function buildMimeMessage(message) {
-    let text = message.text ? encodePart("text/plain", message.text) : undefined;
-    let html = message.html ? encodePart("text/html", message.html) : undefined;
-    let headers = buildHeaders(message);
-    if (text && html) {
-        let boundary = selectBoundary([text, html]);
-        return [
-            ...headers,
-            foldHeader("Content-Type", `multipart/alternative; boundary="${boundary}"`),
-            "",
-            `--${boundary}`,
-            ...buildContentHeaders(text),
-            "",
-            text.body,
-            `--${boundary}`,
-            ...buildContentHeaders(html),
-            "",
-            html.body,
-            `--${boundary}--`,
-            "",
-        ].join(CRLF);
-    }
-    let part = text ?? html ?? encodePart("text/plain", "");
-    return [...headers, ...buildContentHeaders(part), "", part.body, ""].join(CRLF);
+    let parts = alternativeParts(message);
+    if (parts.length === 0)
+        parts.push(encodePart("text/plain; charset=utf-8", ""));
+    let [only] = parts;
+    let body = parts.length === 1 && only ? toEntity(only) : toMultipart("alternative", parts.map(toEntity));
+    let attachment = calendarAttachment(message);
+    if (attachment)
+        body = toMultipart("mixed", [body, toEntity(attachment)]);
+    return [...buildHeaders(message), ...body.headers, "", body.body, ""].join(CRLF);
 }

package/dist/types.d.ts

@@ -16,6 +16,48 @@ export interface Address {
     /** Display name shown by mail clients in place of the bare address. */
     name?: string;
 }
+/**
+ * An RFC 8058 one-click unsubscribe target, from which the mailer writes
+ * `List-Unsubscribe` and `List-Unsubscribe-Post`. Mailbox providers show their own
+ * unsubscribe button only for an HTTPS target they can POST to without a session.
+ */
+export interface Unsubscribe {
+    /**
+     * The one-click endpoint, which must be `https:`. It receives the provider's POST
+     * with no cookies, so the URL alone has to identify the recipient and the list.
+     */
+    url: string | URL;
+    /** An address, or a full `mailto:` URI, listed after the URL for clients that only mail. */
+    mailto?: string;
+    /**
+     * Writes `List-Unsubscribe-Post`; set `false` only for a URL that cannot accept the POST.
+     * @default true
+     */
+    oneClick?: boolean;
+}
+/** The mailing list a message belongs to, written as RFC 2919 `List-Id` for filters and feedback loops. */
+export interface MailingList {
+    /** Dot-separated labels in a domain the sender controls, e.g. `digest.uptime.example.com`. */
+    id: string;
+    /** Description shown before the id: `List-Id: Daily digest <digest.uptime.example.com>`. */
+    name?: string;
+}
+/**
+ * A calendar object carried beside the bodies, which is how an iTIP invitation reaches a
+ * calendar client: raw MIME places it last in `multipart/alternative` as
+ * `text/calendar; method=…`, so clients that understand it show accept and decline.
+ */
+export interface CalendarPart {
+    /** The iTIP method, e.g. `REQUEST`, `CANCEL` or `REPLY`; it must match the content's `METHOD`. */
+    method: string;
+    /** The serialized iCalendar object, CRLF lines as a calendar writer produces them. */
+    content: string;
+    /**
+     * Attaches the same calendar as a file with this name, e.g. `invite.ics`, for clients that
+     * only offer attachments; transports with no alternative part use it as the file's name.
+     */
+    filename?: string;
+}
 /**
  * A message as callers write it. Everything the mailer can supply a default for
  * is optional, so a caller only states what is specific to this message.
@@ -43,6 +85,12 @@ export interface Message {
     date?: Date;
     /** Explicit `Message-ID` value; omitted means generated. Set it to keep tests deterministic. */
     messageId?: string;
+    /** One-click unsubscribe for optional mail; transactional mail leaves it unset. */
+    unsubscribe?: Unsubscribe;
+    /** List the message belongs to, written as `List-Id`. */
+    list?: MailingList;
+    /** A calendar object, such as an invitation, sent alongside the bodies. */
+    calendar?: CalendarPart;
 }
 /**
  * A message after normalization: defaults applied, every address list coerced to
@@ -66,12 +114,21 @@ export interface NormalizedMessage {
     html?: string;
     /** Plain-text body; derived from `html` unless the caller supplied one. */
     text?: string;
-    /** Headers to add, with per-message values winning over configured ones. */
+    /**
+     * Headers to add, with per-message values winning over configured ones, plus the
+     * `List-*` headers generated from `unsubscribe` and `list`.
+     */
     headers: Record<string, string>;
     /** Value for the `Date` header, defaulted to the moment of normalization. */
     date: Date;
     /** Value for the `Message-ID` header, generated when the caller omitted it. */
     messageId: string;
+    /** The unsubscribe target the `List-Unsubscribe` headers were written from, when set. */
+    unsubscribe: Unsubscribe | null;
+    /** The list the `List-Id` header was written from, when set. */
+    list: MailingList | null;
+    /** The calendar object to send alongside the bodies, when set. */
+    calendar?: CalendarPart;
     /**
      * The email object this message was produced from, when it came from one.
      * It exists so tests can identify a sent message by its type.
@@ -113,4 +170,10 @@ export interface Email {
     readonly replyTo?: Address | Address[];
     /** Per-email headers, merged over the mailer's configured headers. */
     readonly headers?: Record<string, string>;
+    /** One-click unsubscribe for optional mail; transactional emails leave it unset. */
+    readonly unsubscribe?: Unsubscribe;
+    /** List the email belongs to, written as `List-Id`. */
+    readonly list?: MailingList;
+    /** A calendar object, such as an invitation, sent alongside the rendered body. */
+    readonly calendar?: CalendarPart;
 }

package/dist/unsubscribe.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The receiving side of one-click unsubscribe: HMAC-signed tokens that let an
+ * unsubscribe URL name the recipient and list with no session and no stored row, and
+ * a recognizer for the RFC 8058 POST a mailbox provider sends to that URL.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import { InvalidUnsubscribeTokenError, MailError } from "./errors.js";
+export { InvalidUnsubscribeTokenError } from "./errors.js";
+/** Types for the unsubscribe token helpers. */
+export declare namespace UnsubscribeToken {
+    /** What a verified token authorizes. */
+    interface Claims {
+        /** Who is unsubscribing: an opaque id, never an email address, since the token lands in URLs and logs. */
+        subject: string;
+        /** What they are unsubscribing from, matching the app's own list or email-kind name. */
+        list: string;
+        /** When the token was signed; `null` for a token whose payload names only the list and subject. */
+        issuedAt: Date | null;
+    }
+    /** Options both signing and verifying accept; they must agree for a token to verify. */
+    interface Options {
+        /**
+         * Domain-separation prefix for the MAC, so a secret shared with sessions or webhooks
+         * cannot be used to mint an unsubscribe token.
+         * @default "unsubscribe:v1:"
+         */
+        purpose?: string;
+    }
+    /** Options for signing a token. */
+    interface SignOptions extends Options {
+        /** When the link stops working; omitted means never, since providers may POST long after delivery. */
+        expiresAt?: Date;
+    }
+}
+/**
+ * Signs an unsubscribe token: the hex HMAC-SHA-256 followed by the base64url payload, so
+ * the whole token is one URL path segment that needs no escaping. The subject must be
+ * an opaque id; an email address is refused because the token travels in URLs and logs.
+ *
+ * @param secret - The app's unsubscribe secret; rotating it invalidates every delivered link.
+ * @param claims - The recipient's opaque id and the list they leave.
+ * @param options - An expiry, and the purpose prefix the verifier must also use.
+ * @returns The token, or a `MailError` for unusable claims or a failed signature.
+ * @example let token = await signUnsubscribeToken(env.UNSUBSCRIBE_SECRET, { subject: member.id, list: "digest" });
+ */
+export declare function signUnsubscribeToken(secret: string, claims: {
+    subject: string;
+    list: string;
+}, options?: UnsubscribeToken.SignOptions): Promise<Result<string, MailError>>;
+/**
+ * Verifies a token from an unsubscribe URL in constant time and returns what it
+ * authorizes. Every way a token can be unusable arrives as the same error, so the
+ * endpoint answers them alike.
+ *
+ * @param secret - The secret the token was signed with.
+ * @param token - The path segment from the unsubscribe URL.
+ * @param options - The purpose prefix the token was signed with.
+ * @returns The claims, or an `InvalidUnsubscribeTokenError`.
+ */
+export declare function verifyUnsubscribeToken(secret: string, token: string, options?: UnsubscribeToken.Options): Promise<Result<UnsubscribeToken.Claims, InvalidUnsubscribeTokenError>>;
+/**
+ * Reports whether a parsed form body is RFC 8058's `List-Unsubscribe=One-Click`, which
+ * is how an endpoint tells the mailbox provider's POST, which reads no response body,
+ * from a person pressing the confirmation page's button.
+ *
+ * @param form - The request's parsed form data, URL-encoded or multipart.
+ * @returns `true` only for the exact field and value RFC 8058 defines.
+ */
+export declare function isOneClickUnsubscribe(form: FormData): boolean;

package/dist/unsubscribe.js

@@ -0,0 +1,133 @@
+/**
+ * The receiving side of one-click unsubscribe: HMAC-signed tokens that let an
+ * unsubscribe URL name the recipient and list with no session and no stored row, and
+ * a recognizer for the RFC 8058 POST a mailbox provider sends to that URL.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { Base64Url, Hex, hmac } from "@sdxc/crypto";
+import { failure, isFailure, success } from "@sdxc/result";
+import { InvalidUnsubscribeTokenError, MailError } from "./errors.js";
+import { isValidAddress } from "./lib/address.js";
+export { InvalidUnsubscribeTokenError } from "./errors.js";
+/**
+ * Prefixed to every signed payload unless a caller names its own, so a MAC made here
+ * authenticates only an unsubscribe even when the secret also signs something else.
+ */
+const DEFAULT_PURPOSE = "unsubscribe:v1:";
+/** Length of the hex SHA-256 MAC that opens every token, which is what lets it need no separator. */
+const SIGNATURE_LENGTH = 64;
+/** Control characters, which the payload uses as its field separator. */
+const CONTROL_CHARACTERS = /\p{Cc}/u;
+/**
+ * Serializes the claims as `list:subject`, followed by the issue time and optional
+ * expiry in Unix seconds on their own lines. The list holds no colon and neither field
+ * a control character, so the first colon and each line break split it unambiguously.
+ */
+function encodePayload(claims, issuedAt, expiresAt) {
+    let lines = [`${claims.list}:${claims.subject}`, String(Math.floor(issuedAt.getTime() / 1000))];
+    if (expiresAt)
+        lines.push(String(Math.floor(expiresAt.getTime() / 1000)));
+    return lines.join("\n");
+}
+/**
+ * Reads a payload back, or `null` when it is malformed or expired at `now`. A payload
+ * with only `list:subject` verifies with a `null` issue time and no expiry.
+ */
+function decodePayload(payload, now) {
+    let [head = "", issued, expires, ...rest] = payload.split("\n");
+    if (rest.length > 0)
+        return null;
+    let separator = head.indexOf(":");
+    let list = head.slice(0, separator);
+    let subject = head.slice(separator + 1);
+    if (separator <= 0 || !subject)
+        return null;
+    let issuedAt = issued === undefined ? null : fromSeconds(issued);
+    if (issuedAt === undefined)
+        return null;
+    if (expires !== undefined) {
+        let expiresAt = fromSeconds(expires);
+        if (!expiresAt || now >= expiresAt)
+            return null;
+    }
+    return { subject, list, issuedAt };
+}
+/** Parses a decimal Unix-seconds field, or `undefined` for anything else. */
+function fromSeconds(value) {
+    if (!/^\d+$/.test(value))
+        return undefined;
+    return new Date(Number(value) * 1000);
+}
+/**
+ * Signs an unsubscribe token: the hex HMAC-SHA-256 followed by the base64url payload, so
+ * the whole token is one URL path segment that needs no escaping. The subject must be
+ * an opaque id; an email address is refused because the token travels in URLs and logs.
+ *
+ * @param secret - The app's unsubscribe secret; rotating it invalidates every delivered link.
+ * @param claims - The recipient's opaque id and the list they leave.
+ * @param options - An expiry, and the purpose prefix the verifier must also use.
+ * @returns The token, or a `MailError` for unusable claims or a failed signature.
+ * @example let token = await signUnsubscribeToken(env.UNSUBSCRIBE_SECRET, { subject: member.id, list: "digest" });
+ */
+export async function signUnsubscribeToken(secret, claims, options = {}) {
+    if (!claims.list || claims.list.includes(":") || CONTROL_CHARACTERS.test(claims.list)) {
+        return failure(new MailError("An unsubscribe list must be a non-empty name without colons."));
+    }
+    if (!claims.subject || CONTROL_CHARACTERS.test(claims.subject)) {
+        return failure(new MailError("An unsubscribe subject must be a non-empty opaque id."));
+    }
+    if (isValidAddress({ email: claims.subject })) {
+        return failure(new MailError("An unsubscribe subject must be an opaque id, not an address."));
+    }
+    let payload = encodePayload(claims, new Date(), options.expiresAt);
+    let purpose = options.purpose ?? DEFAULT_PURPOSE;
+    let mac = await hmac.sign(secret, `${purpose}${payload}`);
+    if (isFailure(mac)) {
+        return failure(new MailError("Failed to sign the unsubscribe token.", { cause: mac.error }));
+    }
+    return success(`${Hex.encode(mac.data)}${Base64Url.encode(payload)}`);
+}
+/**
+ * Verifies a token from an unsubscribe URL in constant time and returns what it
+ * authorizes. Every way a token can be unusable arrives as the same error, so the
+ * endpoint answers them alike.
+ *
+ * @param secret - The secret the token was signed with.
+ * @param token - The path segment from the unsubscribe URL.
+ * @param options - The purpose prefix the token was signed with.
+ * @returns The claims, or an `InvalidUnsubscribeTokenError`.
+ */
+export async function verifyUnsubscribeToken(secret, token, options = {}) {
+    let signature = token.slice(0, SIGNATURE_LENGTH);
+    let encoded = token.slice(SIGNATURE_LENGTH);
+    if (signature.length < SIGNATURE_LENGTH || !encoded) {
+        return failure(new InvalidUnsubscribeTokenError());
+    }
+    let decoded = Base64Url.decode(encoded);
+    if (isFailure(decoded))
+        return failure(new InvalidUnsubscribeTokenError());
+    let payload = new TextDecoder().decode(decoded.data);
+    let purpose = options.purpose ?? DEFAULT_PURPOSE;
+    let valid = await hmac.verify(secret, `${purpose}${payload}`, signature);
+    if (isFailure(valid))
+        return failure(new InvalidUnsubscribeTokenError({ cause: valid.error }));
+    if (!valid.data)
+        return failure(new InvalidUnsubscribeTokenError());
+    let claims = decodePayload(payload, new Date());
+    if (!claims)
+        return failure(new InvalidUnsubscribeTokenError());
+    return success(claims);
+}
+/**
+ * Reports whether a parsed form body is RFC 8058's `List-Unsubscribe=One-Click`, which
+ * is how an endpoint tells the mailbox provider's POST, which reads no response body,
+ * from a person pressing the confirmation page's button.
+ *
+ * @param form - The request's parsed form data, URL-encoded or multipart.
+ * @returns `true` only for the exact field and value RFC 8058 defines.
+ */
+export function isOneClickUnsubscribe(form) {
+    return form.get("List-Unsubscribe") === "One-Click";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sdxc/mail",
-	"version": "2026.9.15",
+	"version": "2026.9.28",
 	"description": "Transport-agnostic transactional email with pluggable transports and remix/ui rendering",
 	"license": "MIT",
 	"type": "module",
@@ -9,16 +9,18 @@
 		"./markdown": "./dist/markdown.js",
 		"./memory": "./dist/memory.js",
 		"./middleware": "./dist/middleware.js",
-		"./cloudflare": "./dist/cloudflare.js"
+		"./cloudflare": "./dist/cloudflare.js",
+		"./unsubscribe": "./dist/unsubscribe.js"
 	},
 	"dependencies": {
-		"@sdxc/highlight": "2026.9.15",
+		"@sdxc/crypto": "2026.9.28",
+		"@sdxc/highlight": "2026.9.28",
 		"@sdxc/logger": "2026.9.11",
-		"@sdxc/markdown": "2026.9.15",
+		"@sdxc/markdown": "2026.9.28",
 		"@sdxc/result": "2026.9.15",
 		"remix": "3.0.0-rc.2"
 	},
-	"gitHead": "d56f75a79171aab3be101d8fa624d51972cd6028",
+	"gitHead": "00c01e349b11f65b9f47902c5345a817e8afd2b1",
 	"publishConfig": {
 		"access": "public"
 	},