@nxgt/mail 0.3.0 → 0.4.0

package/README.md

@@ -41,7 +41,7 @@ import without extensions, so `nodenext` is not supported.
 
 | Import | What it holds |
 | --- | --- |
-| `@nxgt/mail` | The port (`Mailer`, `MailMessage`, `Rendered`, `SentMail`, `Address`, `MailAttachment`), the errors (`MailError`, `MailFailure`, `MailRefused`), `createMemoryMailer`, `pickLocale` and `parseAcceptLanguage`, and what a transport calls first: `checkMessage`, `recipientsOf`, `addressOf`. No Node built-in: it runs anywhere |
+| `@nxgt/mail` | The port (`Mailer`, `MailMessage`, `Rendered`, `SentMail`, `Address`, `MailAttachment`), the errors (`MailError`, `MailFailure`, `MailRefused`), `createMemoryMailer`, `pickLocale` and `parseAcceptLanguage`, `listUnsubscribe` with `ListUnsubscribeOptions` and `ListUnsubscribeHeaders`, and what a transport calls first: `checkMessage`, `recipientsOf`, `addressOf`. No Node built-in: it runs anywhere |
 | `@nxgt/mail/renderer` | The renderer: `createMailRenderer`, `MailRenderer`, `MailRendererOptions`, `RenderOptions`, `MailVariables`, and the types that type it with a build's `MailEmails` (`MailEmailsOf`, `AnyMailEmails`, `RenderArguments`). Reads the build with `node:fs` |
 | `@nxgt/mail/conformance` | **For transport authors**: `describeMailer`, its cases as data, `runMailerCase`, the messages they send (`sampleMessage`, `sampleAttachment`), and the memory mailer's harness as a worked example |
 
@@ -193,6 +193,45 @@ twice is delivered twice. A key that is not 1 to 256 visible ASCII characters
 is refused with `MailRefused`. See
 [Sending — idempotency](docs/guide/sending.md#idempotency--sending-once).
 
+### One-click unsubscribe — `listUnsubscribe`
+
+Gmail and Yahoo require bulk senders to offer one-click unsubscribe on
+marketing mail. `listUnsubscribe` answers its two headers, to spread into
+`headers`, with a URL per recipient:
+
+```ts
+import { listUnsubscribe, type Mailer, type Rendered } from '@nxgt/mail';
+
+export async function sendNewsletter(
+	mailer: Mailer,
+	rendered: Rendered,
+	subscriber: { email: string; unsubscribeToken: string },
+): Promise<void> {
+	await mailer.send({
+		...rendered,
+		to: subscriber.email,
+		headers: {
+			...listUnsubscribe({
+				url: `https://example.com/unsubscribe?token=${encodeURIComponent(subscriber.unsubscribeToken)}`,
+				mailto: 'unsubscribe@example.com', // optional
+			}),
+		},
+	});
+}
+// List-Unsubscribe: <https://example.com/unsubscribe?token=…>, <mailto:unsubscribe@example.com>
+// List-Unsubscribe-Post: List-Unsubscribe=One-Click
+```
+
+The URL must start with `https://`, be printable ASCII, carry no user or
+password, and hold no `<`, `>`, double quote or raw comma (percent-encode
+it: `%2C`), and `mailto` must be a bare ASCII address; anything else is a
+`MailRefused` that never quotes the URL — its token is a credential. Your
+endpoint must unsubscribe on a `POST` with the body
+`List-Unsubscribe=One-Click`, with no login and no confirmation. It belongs on
+marketing and bulk mail, not on a password reset or a sign-in code. See
+[Sending — one-click unsubscribe](docs/guide/sending.md#one-click-unsubscribe)
+for the endpoint and DKIM.
+
 ### Errors — switch on `code`
 
 Both errors extend `MailError`, whose `code` is a union a `switch` exhausts.
@@ -396,7 +435,7 @@ gives a test file `describe` and `it` as bare identifiers, not on `globalThis`.
 
 ## Type safety, counted
 
-**22 plausible mistakes, 22 refused** at compile time, each measured by a
+**23 plausible mistakes, 23 refused** at compile time, each measured by a
 `@ts-expect-error` in
 [`test/types/refusals.ts`](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail/test/types/refusals.ts)
 that fails the typecheck the moment it stops holding:
@@ -438,6 +477,11 @@ And the idempotency key:
 22. A number (`idempotencyKey: order.id`): the key is a string, as
     `order-42/receipt`.
 
+And one-click unsubscribe:
+
+23. A `URL` object as `listUnsubscribe`'s `url`: the header holds text, so
+    pass `url.href`.
+
 The same file holds the calls that must keep compiling: a refusal that refuses
 the correct call is a bug.
 
@@ -450,6 +494,8 @@ the correct call is a bug.
   planned.
 - [Vocabulary](https://github.com/softistx/nxgt-mail/blob/develop/docs/vocabulary.md)
   — the words these pages use, defined once.
+- [The starter](https://github.com/softistx/nxgt-mail/tree/develop/examples/starter)
+  — a Maizzle project that builds, renders and sends one e-mail, to copy.
 
 ## Licence
 

package/dist/chunks/index-we4n5yfz.js.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../src/errors.ts"],
   "sourcesContent": [
-    "/**\n * What a transport refuses, as a string a caller can switch on.\n *\n * Every code is a **refusal at call time**. A refusal that can only come from\n * how the application was wired — a bad option passed to a factory — is a\n * bare `TypeError` instead: no handler should ever answer one.\n *\n * The codes are `SCREAMING_SNAKE` because they are data values, not API\n * identifiers. Every key in this package is `camelCase`.\n */\nexport type MailErrorCode =\n\t/**\n\t * The transport could not hand the message over: a refused connection, a\n\t * timeout, a 5xx from the provider, an expired credential. The transport's\n\t * own error is the `cause`.\n\t *\n\t * **Nothing is known to have been sent** — after a timeout or a dropped\n\t * connection, the provider may have taken it all the same. Retry later,\n\t * or tell the user it failed. Never report it as sent.\n\t */\n\t| 'MAIL_FAILED'\n\t/**\n\t * The message itself was refused, before or by the transport: no\n\t * recipient, something that is not an address, a line break in the\n\t * subject or a header, an attachment that is not bytes or is badly named,\n\t * a provider answering that the message is malformed or too large, or —\n\t * from `@nxgt/mail/renderer` — a URL variable that is not an `http:`,\n\t * `https:` or `mailto:` URL. Sending it again unchanged fails again.\n\t */\n\t| 'MAIL_REFUSED';\n\n/** Options every error of this package accepts. */\nexport interface MailErrorOptions {\n\t/** The error that caused this one, typically the transport's. */\n\treadonly cause?: unknown;\n}\n\n/**\n * The base class of every error this package throws at call time. It is\n * abstract: a transport throws {@link MailFailure} or {@link MailRefused}.\n *\n * **There is exactly one definition of this class.** A transport defines no\n * error class of its own and throws these, imported from its `@nxgt/mail`\n * peer, so `error instanceof MailFailure` holds whatever transport threw it.\n *\n * A message reports **a shape, never a value**: never a recipient address,\n * never a subject, never a link — the link in a verification e-mail is a\n * credential.\n */\nexport abstract class MailError extends Error {\n\toverride name = 'MailError';\n\t/**\n\t * Abstract, so a transport cannot throw a bare `MailError` that passes a\n\t * `code` check and fails `instanceof MailFailure`: it throws one of the two\n\t * subclasses.\n\t */\n\tabstract readonly code: MailErrorCode;\n\n\tconstructor(message: string, options?: MailErrorOptions) {\n\t\tsuper(message, { cause: options?.cause });\n\t}\n}\n\n/** The transport could not hand the message over. Code `MAIL_FAILED`. */\nexport class MailFailure extends MailError {\n\toverride name = 'MailFailure';\n\toverride readonly code = 'MAIL_FAILED' as const;\n}\n\n/** The message was refused as malformed. Code `MAIL_REFUSED`. */\nexport class MailRefused extends MailError {\n\toverride name = 'MailRefused';\n\toverride readonly code = 'MAIL_REFUSED' as const;\n}\n"
+    "/**\n * What a transport refuses, as a string a caller can switch on.\n *\n * Every code is a **refusal at call time**. A refusal that can only come from\n * how the application was wired — a bad option passed to a factory — is a\n * bare `TypeError` instead: no handler should ever answer one.\n *\n * The codes are `SCREAMING_SNAKE` because they are data values, not API\n * identifiers. Every key in this package is `camelCase`.\n */\nexport type MailErrorCode =\n\t/**\n\t * The transport could not hand the message over: a refused connection, a\n\t * timeout, a 5xx from the provider, an expired credential. The transport's\n\t * own error is the `cause`.\n\t *\n\t * **Nothing is known to have been sent** — after a timeout or a dropped\n\t * connection, the provider may have taken it all the same. Retry later,\n\t * or tell the user it failed. Never report it as sent.\n\t */\n\t| 'MAIL_FAILED'\n\t/**\n\t * The message itself was refused, before or by the transport: no\n\t * recipient, something that is not an address, a line break in the\n\t * subject or a header, an attachment that is not bytes or is badly named,\n\t * a provider answering that the message is malformed or too large, or —\n\t * from `@nxgt/mail/renderer` — a URL variable that is not an `http:`,\n\t * `https:` or `mailto:` URL, or, from `listUnsubscribe`, an unsubscribe URL\n\t * or address it will not write. Sending it again unchanged fails again.\n\t */\n\t| 'MAIL_REFUSED';\n\n/** Options every error of this package accepts. */\nexport interface MailErrorOptions {\n\t/** The error that caused this one, typically the transport's. */\n\treadonly cause?: unknown;\n}\n\n/**\n * The base class of every error this package throws at call time. It is\n * abstract: a transport throws {@link MailFailure} or {@link MailRefused}.\n *\n * **There is exactly one definition of this class.** A transport defines no\n * error class of its own and throws these, imported from its `@nxgt/mail`\n * peer, so `error instanceof MailFailure` holds whatever transport threw it.\n *\n * A message reports **a shape, never a value**: never a recipient address,\n * never a subject, never a link — the link in a verification e-mail is a\n * credential.\n */\nexport abstract class MailError extends Error {\n\toverride name = 'MailError';\n\t/**\n\t * Abstract, so a transport cannot throw a bare `MailError` that passes a\n\t * `code` check and fails `instanceof MailFailure`: it throws one of the two\n\t * subclasses.\n\t */\n\tabstract readonly code: MailErrorCode;\n\n\tconstructor(message: string, options?: MailErrorOptions) {\n\t\tsuper(message, { cause: options?.cause });\n\t}\n}\n\n/** The transport could not hand the message over. Code `MAIL_FAILED`. */\nexport class MailFailure extends MailError {\n\toverride name = 'MailFailure';\n\toverride readonly code = 'MAIL_FAILED' as const;\n}\n\n/** The message was refused as malformed. Code `MAIL_REFUSED`. */\nexport class MailRefused extends MailError {\n\toverride name = 'MailRefused';\n\toverride readonly code = 'MAIL_REFUSED' as const;\n}\n"
   ],
-  "mappings": ";AAiDO,MAAe,mBAAkB,MAAM;AAAA,EAS7C,WAAW,CAAC,SAAiB,SAA4B;AAAA,IACxD,MAAM,SAAS,EAAE,OAAO,SAAS,MAAM,CAAC;AAAA,IAThC,YAAO;AAAA;AAWjB;AAAA;AAGO,MAAM,qBAAoB,WAAU;AAAA;AAAA;AAAA,IACjC,YAAO;AAAA,IACE,YAAO;AAAA;AAC1B;AAAA;AAGO,MAAM,qBAAoB,WAAU;AAAA;AAAA;AAAA,IACjC,YAAO;AAAA,IACE,YAAO;AAAA;AAC1B;",
+  "mappings": ";AAkDO,MAAe,mBAAkB,MAAM;AAAA,EAS7C,WAAW,CAAC,SAAiB,SAA4B;AAAA,IACxD,MAAM,SAAS,EAAE,OAAO,SAAS,MAAM,CAAC;AAAA,IAThC,YAAO;AAAA;AAWjB;AAAA;AAGO,MAAM,qBAAoB,WAAU;AAAA;AAAA;AAAA,IACjC,YAAO;AAAA,IACE,YAAO;AAAA;AAC1B;AAAA;AAGO,MAAM,qBAAoB,WAAU;AAAA;AAAA;AAAA,IACjC,YAAO;AAAA,IACE,YAAO;AAAA;AAC1B;",
   "debugId": "5753AA1D988C668964756E2164756E21",
   "names": []
 }

package/dist/errors.d.ts

@@ -25,7 +25,8 @@ export type MailErrorCode =
  * subject or a header, an attachment that is not bytes or is badly named,
  * a provider answering that the message is malformed or too large, or —
  * from `@nxgt/mail/renderer` — a URL variable that is not an `http:`,
- * `https:` or `mailto:` URL. Sending it again unchanged fails again.
+ * `https:` or `mailto:` URL, or, from `listUnsubscribe`, an unsubscribe URL
+ * or address it will not write. Sending it again unchanged fails again.
  */
  | 'MAIL_REFUSED';
 /** Options every error of this package accepts. */

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa;AACxB;;;;;;;;GAQG;AACD,aAAa;AACf;;;;;;;GAOG;GACD,cAAc,CAAC;AAElB,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAChC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,8BAAsB,SAAU,SAAQ,KAAK;IACnC,IAAI,SAAe;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;gBAE1B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB;CAGvD;AAED,yEAAyE;AACzE,qBAAa,WAAY,SAAQ,SAAS;IAChC,IAAI,SAAiB;IAC9B,SAAkB,IAAI,EAAG,aAAa,CAAU;CAChD;AAED,iEAAiE;AACjE,qBAAa,WAAY,SAAQ,SAAS;IAChC,IAAI,SAAiB;IAC9B,SAAkB,IAAI,EAAG,cAAc,CAAU;CACjD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa;AACxB;;;;;;;;GAQG;AACD,aAAa;AACf;;;;;;;;GAQG;GACD,cAAc,CAAC;AAElB,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAChC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,8BAAsB,SAAU,SAAQ,KAAK;IACnC,IAAI,SAAe;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;gBAE1B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB;CAGvD;AAED,yEAAyE;AACzE,qBAAa,WAAY,SAAQ,SAAS;IAChC,IAAI,SAAiB;IAC9B,SAAkB,IAAI,EAAG,aAAa,CAAU;CAChD;AAED,iEAAiE;AACjE,qBAAa,WAAY,SAAQ,SAAS;IAChC,IAAI,SAAiB;IAC9B,SAAkB,IAAI,EAAG,cAAc,CAAU;CACjD"}

package/dist/index.d.ts

@@ -18,4 +18,5 @@ export { parseAcceptLanguage, pickLocale, type WantedLocales } from './locale';
 export { createMemoryMailer, type MemoryMail, type MemoryMailer, } from './memory';
 export { addressOf, checkMessage, recipientsOf } from './message';
 export type { Address, MailAttachment, Mailer, MailMessage, Rendered, SentMail, } from './types';
+export { type ListUnsubscribeHeaders, type ListUnsubscribeOptions, listUnsubscribe, } from './unsubscribe';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACN,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,WAAW,EACX,WAAW,GACX,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAC/E,OAAO,EACN,kBAAkB,EAClB,KAAK,UAAU,EACf,KAAK,YAAY,GACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAClE,YAAY,EACX,OAAO,EACP,cAAc,EACd,MAAM,EACN,WAAW,EACX,QAAQ,EACR,QAAQ,GACR,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACN,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,WAAW,EACX,WAAW,GACX,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAC/E,OAAO,EACN,kBAAkB,EAClB,KAAK,UAAU,EACf,KAAK,YAAY,GACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAClE,YAAY,EACX,OAAO,EACP,cAAc,EACd,MAAM,EACN,WAAW,EACX,QAAQ,EACR,QAAQ,GACR,MAAM,SAAS,CAAC;AACjB,OAAO,EACN,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,eAAe,GACf,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -13,6 +13,32 @@ import {
   MailFailure2,
   MailRefused2
 } from "./chunks/index-we4n5yfz.js";
+// src/unsubscribe.ts
+var URL_ALLOWED = /^https:\/\/[\x21-\x7E]+$/;
+var URL_REFUSED = /[<>,"`\\{}|^]/;
+var MAILTO = /^[A-Za-z0-9._~!$'*+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+$/;
+function listUnsubscribe(options) {
+  if (typeof options !== "object" || options === null) {
+    throw new TypeError("listUnsubscribe: options must be an object, as { url }");
+  }
+  if (typeof options.url !== "string") {
+    throw new TypeError("listUnsubscribe: url must be a string");
+  }
+  if (options.mailto !== undefined && typeof options.mailto !== "string") {
+    throw new TypeError("listUnsubscribe: mailto must be a string");
+  }
+  if (!URL_ALLOWED.test(options.url) || URL_REFUSED.test(options.url) || !URL.canParse(options.url) || new URL(options.url).username !== "" || new URL(options.url).password !== "") {
+    throw new MailRefused2("listUnsubscribe: url must be an https:// URL in printable ASCII, without credentials, <, >, quotes or a raw comma");
+  }
+  if (options.mailto !== undefined && !MAILTO.test(options.mailto)) {
+    throw new MailRefused2("listUnsubscribe: mailto must be a bare e-mail address, as unsubscribe@example.com");
+  }
+  const mailto = options.mailto === undefined ? "" : `, <mailto:${options.mailto}>`;
+  return {
+    "List-Unsubscribe": `<${options.url}>${mailto}`,
+    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
+  };
+}
 export {
   MailError2 as MailError,
   MailFailure2 as MailFailure,
@@ -20,10 +46,11 @@ export {
   addressOf2 as addressOf,
   checkMessage2 as checkMessage,
   createMemoryMailer2 as createMemoryMailer,
+  listUnsubscribe,
   parseAcceptLanguage2 as parseAcceptLanguage,
   pickLocale2 as pickLocale,
   recipientsOf2 as recipientsOf
 };
 
-//# debugId=F6BB19285305093D64756E2164756E21
+//# debugId=AB5848B04CC61C7064756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1,9 +1,10 @@
 {
   "version": 3,
-  "sources": [],
+  "sources": ["../src/unsubscribe.ts"],
   "sourcesContent": [
+    "import { MailRefused } from './errors';\n\n/** Where a recipient unsubscribes: the one-click URL, and an address as well. */\nexport interface ListUnsubscribeOptions {\n\t/**\n\t * The `https:` URL a mail client POSTs `List-Unsubscribe=One-Click` to —\n\t * one per recipient, carrying what identifies them, as\n\t * `https://example.com/unsubscribe?token=…`. It unsubscribes on that POST\n\t * alone: no login, no confirmation page, no redirect.\n\t */\n\treadonly url: string;\n\t/** An address that unsubscribes whoever writes to it, for clients that only send mail. */\n\treadonly mailto?: string;\n}\n\n/**\n * The two headers of RFC 8058's one-click unsubscribe. A type, not an\n * interface: an interface has no index signature, and would not go into\n * `headers` as it is.\n */\nexport type ListUnsubscribeHeaders = {\n\treadonly 'List-Unsubscribe': string;\n\treadonly 'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click';\n};\n\n// RFC 2369 wants an RFC 3986 URI inside `<…>`: printable ASCII only — a\n// transport would encode a header holding anything else, and no client\n// would find the URL in it — and none of what ends the URL (`<`, `>`), what\n// RFC 2369 reads as the next one (`,`), or what no URI holds as is (a double\n// quote, a backtick, a backslash, braces, `|`, `^`). Percent-encode it.\nconst URL_ALLOWED = /^https:\\/\\/[\\x21-\\x7E]+$/;\nconst URL_REFUSED = /[<>,\"`\\\\{}|^]/;\n// RFC 6068 reads `?`, `&`, `=`, `#` and `%` inside a mailto: as structure — a\n// subject, a second recipient — so the address is plain ASCII without them.\nconst MAILTO = /^[A-Za-z0-9._~!$'*+-]+@[A-Za-z0-9-]+(?:\\.[A-Za-z0-9-]+)+$/;\n\n/**\n * The headers that give an e-mail Gmail's and Yahoo's one-click unsubscribe\n * (RFC 8058, with RFC 2369's `List-Unsubscribe`), to spread into a message's\n * `headers`:\n *\n * ```ts\n * await mailer.send({\n *   ...rendered,\n *   to: user.email,\n *   headers: listUnsubscribe({ url: `https://example.com/unsubscribe?token=${token}` }),\n * });\n * ```\n *\n * Refuses, with a {@link MailRefused} that never quotes the value, a `url`\n * that is not `https://` — RFC 8058 requires it — or is not printable ASCII,\n * carries a user or a password, or holds `<`, `>`, a double quote or a raw `,`; and\n * a `mailto` that is not a bare ASCII address. The URL is\n * often built from a token, and a token is a credential: the message names\n * the rule, not the link.\n */\nexport function listUnsubscribe(\n\toptions: ListUnsubscribeOptions,\n): ListUnsubscribeHeaders {\n\tif (typeof options !== 'object' || options === null) {\n\t\tthrow new TypeError(\n\t\t\t'listUnsubscribe: options must be an object, as { url }',\n\t\t);\n\t}\n\tif (typeof options.url !== 'string') {\n\t\tthrow new TypeError('listUnsubscribe: url must be a string');\n\t}\n\tif (options.mailto !== undefined && typeof options.mailto !== 'string') {\n\t\tthrow new TypeError('listUnsubscribe: mailto must be a string');\n\t}\n\tif (\n\t\t!URL_ALLOWED.test(options.url) ||\n\t\tURL_REFUSED.test(options.url) ||\n\t\t!URL.canParse(options.url) ||\n\t\t// A user and a password in a header every relay and recipient reads.\n\t\tnew URL(options.url).username !== '' ||\n\t\tnew URL(options.url).password !== ''\n\t) {\n\t\tthrow new MailRefused(\n\t\t\t'listUnsubscribe: url must be an https:// URL in printable ASCII, without credentials, <, >, quotes or a raw comma',\n\t\t);\n\t}\n\tif (options.mailto !== undefined && !MAILTO.test(options.mailto)) {\n\t\tthrow new MailRefused(\n\t\t\t'listUnsubscribe: mailto must be a bare e-mail address, as unsubscribe@example.com',\n\t\t);\n\t}\n\tconst mailto =\n\t\toptions.mailto === undefined ? '' : `, <mailto:${options.mailto}>`;\n\treturn {\n\t\t'List-Unsubscribe': `<${options.url}>${mailto}`,\n\t\t'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',\n\t};\n}\n"
   ],
-  "mappings": "",
-  "debugId": "F6BB19285305093D64756E2164756E21",
+  "mappings": ";;;;;;;;;;;;;;;;AA8BA,IAAM,cAAc;AACpB,IAAM,cAAc;AAGpB,IAAM,SAAS;AAsBR,SAAS,eAAe,CAC9B,SACyB;AAAA,EACzB,IAAI,OAAO,YAAY,YAAY,YAAY,MAAM;AAAA,IACpD,MAAM,IAAI,UACT,wDACD;AAAA,EACD;AAAA,EACA,IAAI,OAAO,QAAQ,QAAQ,UAAU;AAAA,IACpC,MAAM,IAAI,UAAU,uCAAuC;AAAA,EAC5D;AAAA,EACA,IAAI,QAAQ,WAAW,aAAa,OAAO,QAAQ,WAAW,UAAU;AAAA,IACvE,MAAM,IAAI,UAAU,0CAA0C;AAAA,EAC/D;AAAA,EACA,IACC,CAAC,YAAY,KAAK,QAAQ,GAAG,KAC7B,YAAY,KAAK,QAAQ,GAAG,KAC5B,CAAC,IAAI,SAAS,QAAQ,GAAG,KAEzB,IAAI,IAAI,QAAQ,GAAG,EAAE,aAAa,MAClC,IAAI,IAAI,QAAQ,GAAG,EAAE,aAAa,IACjC;AAAA,IACD,MAAM,IAAI,aACT,mHACD;AAAA,EACD;AAAA,EACA,IAAI,QAAQ,WAAW,aAAa,CAAC,OAAO,KAAK,QAAQ,MAAM,GAAG;AAAA,IACjE,MAAM,IAAI,aACT,mFACD;AAAA,EACD;AAAA,EACA,MAAM,SACL,QAAQ,WAAW,YAAY,KAAK,aAAa,QAAQ;AAAA,EAC1D,OAAO;AAAA,IACN,oBAAoB,IAAI,QAAQ,OAAO;AAAA,IACvC,yBAAyB;AAAA,EAC1B;AAAA;",
+  "debugId": "AB5848B04CC61C7064756E2164756E21",
   "names": []
 }

package/dist/unsubscribe.d.ts

@@ -0,0 +1,43 @@
+/** Where a recipient unsubscribes: the one-click URL, and an address as well. */
+export interface ListUnsubscribeOptions {
+    /**
+     * The `https:` URL a mail client POSTs `List-Unsubscribe=One-Click` to —
+     * one per recipient, carrying what identifies them, as
+     * `https://example.com/unsubscribe?token=…`. It unsubscribes on that POST
+     * alone: no login, no confirmation page, no redirect.
+     */
+    readonly url: string;
+    /** An address that unsubscribes whoever writes to it, for clients that only send mail. */
+    readonly mailto?: string;
+}
+/**
+ * The two headers of RFC 8058's one-click unsubscribe. A type, not an
+ * interface: an interface has no index signature, and would not go into
+ * `headers` as it is.
+ */
+export type ListUnsubscribeHeaders = {
+    readonly 'List-Unsubscribe': string;
+    readonly 'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click';
+};
+/**
+ * The headers that give an e-mail Gmail's and Yahoo's one-click unsubscribe
+ * (RFC 8058, with RFC 2369's `List-Unsubscribe`), to spread into a message's
+ * `headers`:
+ *
+ * ```ts
+ * await mailer.send({
+ *   ...rendered,
+ *   to: user.email,
+ *   headers: listUnsubscribe({ url: `https://example.com/unsubscribe?token=${token}` }),
+ * });
+ * ```
+ *
+ * Refuses, with a {@link MailRefused} that never quotes the value, a `url`
+ * that is not `https://` — RFC 8058 requires it — or is not printable ASCII,
+ * carries a user or a password, or holds `<`, `>`, a double quote or a raw `,`; and
+ * a `mailto` that is not a bare ASCII address. The URL is
+ * often built from a token, and a token is a credential: the message names
+ * the rule, not the link.
+ */
+export declare function listUnsubscribe(options: ListUnsubscribeOptions): ListUnsubscribeHeaders;
+//# sourceMappingURL=unsubscribe.d.ts.map

package/dist/unsubscribe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsubscribe.d.ts","sourceRoot":"","sources":["../src/unsubscribe.ts"],"names":[],"mappings":"AAEA,iFAAiF;AACjF,MAAM,WAAW,sBAAsB;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACpC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,uBAAuB,EAAE,4BAA4B,CAAC;CAC/D,CAAC;AAaF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,sBAAsB,GAC7B,sBAAsB,CAmCxB"}

package/docs/README.md

@@ -8,7 +8,7 @@ mailer, transport, hand-over, refusal, failure — are defined once, in the
 | Page | Read it when |
 | --- | --- |
 | [Rendering](guide/rendering.md) | You are turning a Maizzle build of `@nxgt/mail-i18n` into an e-mail with `createMailRenderer`: its options, typing it with the build's `MailEmails`, choosing the locale, escaping, URL variables, deploying the build, and every error |
-| [Sending](guide/sending.md) | You are calling `mailer.send`: the `MailMessage` shape, addresses, headers, attachments, the idempotency key, what `send` answers, and turning `MailFailure` and `MailRefused` into a response |
+| [Sending](guide/sending.md) | You are calling `mailer.send`: the `MailMessage` shape, addresses, headers, one-click unsubscribe with `listUnsubscribe` (the headers, DKIM, the endpoint), attachments, the idempotency key, what `send` answers, and turning `MailFailure` and `MailRefused` into a response |
 | [Testing](guide/testing.md) | You are testing code that sends e-mail with `createMemoryMailer`: reading the outbox and its attachments, making a send fail, counting attempts, a retry under an idempotency key |
 | [Locales](guide/locales.md) | You are choosing the locale an e-mail is rendered in, with `pickLocale` and `parseAcceptLanguage` |
 | [Writing a transport](guide/transports.md) | You are implementing the `Mailer` port for a provider — the idempotency key included — and running `@nxgt/mail/conformance` against it |

package/docs/guide/sending.md

@@ -1,8 +1,8 @@
 # Sending
 
 This page is for calling `mailer.send`: the shape of what it takes, the
-addresses, headers and attachments it accepts, the idempotency key that makes
-a retry safe, what it answers, and what it throws.
+addresses, headers and attachments it accepts, one-click unsubscribe, the
+idempotency key that makes a retry safe, what it answers, and what it throws.
 
 ```ts
 import { createMemoryMailer } from '@nxgt/mail';
@@ -93,7 +93,7 @@ interface MailAttachment {
 | `to` | `Address \| readonly Address[]` | yes | One recipient or several, at least one |
 | `from` | `Address` | no | The sender. `checkMessage` does not require one: a transport is usually wired with a default sender, and one without a default may refuse a message without `from` — see its documentation |
 | `replyTo` | `Address` | no | Where replies go |
-| `headers` | `Record<string, string>` | no | Extra headers, such as `List-Unsubscribe` |
+| `headers` | `Record<string, string>` | no | Extra headers, such as `X-Entity-Ref-ID`, or the two of [one-click unsubscribe](#one-click-unsubscribe) |
 | `attachments` | `readonly MailAttachment[]` | no | Files sent with the e-mail, in order, as bytes — see [Attachments](#attachments). An empty list is the same as none |
 | `idempotencyKey` | `string` | no | Names this send, so sending it again delivers it once where the transport can deduplicate — see [Idempotency](#idempotency--sending-once). 1 to 256 visible ASCII characters |
 
@@ -211,13 +211,14 @@ declare const rendered: Rendered;
 const message: MailMessage = {
 	...rendered,
 	to: 'ada@example.com',
-	headers: {
-		'List-Unsubscribe': '<https://example.com/unsubscribe?u=42>',
-		'X-Entity-Ref-ID': 'welcome-42',
-	},
+	headers: { 'X-Entity-Ref-ID': 'welcome-42' },
 };
 ```
 
+`List-Unsubscribe` and `List-Unsubscribe-Post` are headers like any other,
+but write them with [`listUnsubscribe`](#one-click-unsubscribe), which checks
+the URL.
+
 | Written | Answer |
 | --- | --- |
 | `{ 'X Bad': 'v' }` | `MailRefused`: `send: a header name must be letters, digits and hyphens` |
@@ -225,6 +226,213 @@ const message: MailMessage = {
 | `{ Bcc: 'eve@example.com' }` | `MailRefused`: `send: header Bcc is reserved — addresses, the subject and the MIME structure are never custom headers` |
 | `{ 'content-type': 'text/plain' }` | `MailRefused`: `send: header content-type is reserved — …` |
 
+## One-click unsubscribe
+
+`listUnsubscribe` answers the two headers that give an e-mail the
+"Unsubscribe" button Gmail and Yahoo show next to the sender (RFC 8058, with
+RFC 2369's `List-Unsubscribe`), to spread into `headers`:
+
+```ts
+import { listUnsubscribe } from '@nxgt/mail';
+
+listUnsubscribe({ url: 'https://example.com/unsubscribe?token=s3cr3t' });
+// {
+//   'List-Unsubscribe': '<https://example.com/unsubscribe?token=s3cr3t>',
+//   'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
+// }
+
+listUnsubscribe({ url: 'https://example.com/unsubscribe?token=s3cr3t', mailto: 'unsubscribe@example.com' });
+// 'List-Unsubscribe': '<https://example.com/unsubscribe?token=s3cr3t>, <mailto:unsubscribe@example.com>'
+```
+
+```ts
+interface ListUnsubscribeOptions {
+	readonly url: string;
+	readonly mailto?: string;
+}
+
+// A type, not an interface, so it goes into `headers` as it is.
+type ListUnsubscribeHeaders = {
+	readonly 'List-Unsubscribe': string;
+	readonly 'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click';
+};
+
+function listUnsubscribe(options: ListUnsubscribeOptions): ListUnsubscribeHeaders;
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `url` | `string` | required | The `https:` URL a mail client POSTs `List-Unsubscribe=One-Click` to. One per recipient, carrying what identifies them — `https://example.com/unsubscribe?token=…`. Written first in `List-Unsubscribe` |
+| `mailto` | `string` | none | A bare address that unsubscribes whoever writes to it, for clients that only send mail. Written after the URL as `<mailto:…>` |
+
+The headers travel as any other: `checkMessage` accepts them, and every
+transport sends them unchanged. Spread them into `headers` — alone, as
+`headers: { ...listUnsubscribe({ url }) }`, or beside headers of your own:
+
+```ts
+import { listUnsubscribe, type MailMessage, type Rendered } from '@nxgt/mail';
+
+declare const rendered: Rendered;
+declare const token: string;
+
+const message: MailMessage = {
+	...rendered,
+	to: 'ada@example.com',
+	headers: {
+		...listUnsubscribe({ url: `https://example.com/unsubscribe?token=${encodeURIComponent(token)}` }),
+		'X-Entity-Ref-ID': 'newsletter-2026-09',
+	},
+};
+```
+
+### What Gmail and Yahoo require
+
+Since 2024, a sender of bulk mail to Gmail or Yahoo addresses must, on
+marketing and subscribed mail:
+
+- carry **both** headers, `List-Unsubscribe` with an `https:` URL and
+  `List-Unsubscribe-Post: List-Unsubscribe=One-Click`;
+- have them covered by a **DKIM signature** of the sending domain, so nobody
+  can add or change them on the way;
+- honour the unsubscribe promptly — within two days.
+
+The DKIM signature is the sender's, not this package's: `listUnsubscribe`
+writes the headers, and whatever signs the message must include them.
+
+| Transport | Who signs |
+| --- | --- |
+| `@nxgt/mail-resend` | Resend, with the DKIM key of your verified domain. Check that its `h=` names both headers in a received message's `DKIM-Signature` |
+| `@nxgt/mail-smtp` | Your relay, or nodemailer's own `dkim` option on the transporter you create. A relay that does not DKIM-sign leaves the headers unsigned, and the message fails the requirement |
+
+### Which e-mails carry it
+
+**Marketing and bulk mail** — a newsletter, a digest, a product announcement,
+anything the recipient subscribed to and can stop receiving.
+
+**Not transactional mail** — a password reset, a sign-in code, an e-mail
+verification, a receipt, a security alert. The recipient cannot opt out of
+those, and an "Unsubscribe" button next to a sign-in code invites them to
+try. Leave `headers` without it.
+
+### The endpoint
+
+The URL is yours. It must:
+
+- **unsubscribe on a `POST`** whose form body is `List-Unsubscribe=One-Click`
+  — sent as `application/x-www-form-urlencoded` or `multipart/form-data`,
+  which `request.formData()` both reads;
+- do it **with no login, no confirmation page and no redirect**, from the
+  URL alone — the mail client sends no cookie, so the endpoint takes no CSRF
+  token either — and answer **2xx**;
+- on a **`GET`** — the same URL in the body of the e-mail, clicked by a
+  person — **show a page, never unsubscribe**: link scanners and previews
+  fetch every URL in an e-mail. The page's button can post the same form.
+
+```ts
+// Yours: the token store.
+declare function unsubscribeByToken(token: string): Promise<boolean>; // false: unknown token
+
+export async function unsubscribeHandler(request: Request): Promise<Response> {
+	const token = new URL(request.url).searchParams.get('token') ?? '';
+
+	if (request.method === 'POST') {
+		const form = await request.formData();
+		if (form.get('List-Unsubscribe') !== 'One-Click') return new Response(null, { status: 400 });
+		await unsubscribeByToken(token); // an unknown token answers 200 too: nothing to tell a mail client
+		return new Response(null, { status: 200 });
+	}
+
+	// GET: a person followed the link in the e-mail. Show, do not act.
+	const page = `<!doctype html><title>Unsubscribe</title>
+<form method="post"><input type="hidden" name="List-Unsubscribe" value="One-Click">
+<button>Unsubscribe</button></form>`;
+	return new Response(page, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+}
+```
+
+The form posts to its own URL, token included, so the page and the mail
+client take the same path. In a framework, mount it at the URL you pass:
+with Hono, `app.on(['GET', 'POST'], '/unsubscribe', (c) => unsubscribeHandler(c.req.raw))`.
+
+### The token is a credential
+
+Anyone holding the URL can unsubscribe that recipient. Make the token
+unguessable (random, or signed), keep it valid for as long as the e-mail may
+be read, and **never log it** — nor the URL that carries it, nor the query
+string of the endpoint's access log. `listUnsubscribe` does its part: a
+refused `url` is reported by the rule it broke, never quoted.
+
+### Commas must be percent-encoded
+
+`List-Unsubscribe` is a comma-separated list of URLs: a raw `,` in the URL
+would start a second one, so it is refused. `encodeURIComponent` and
+`URLSearchParams` both write `%2C`; a URL built with `URL` is passed as
+`url.href` — a `URL` object is a compile error:
+
+```ts
+import { listUnsubscribe } from '@nxgt/mail';
+
+declare const token: string;
+
+const url = new URL('https://example.com/unsubscribe');
+url.searchParams.set('token', token);
+url.searchParams.set('lists', 'news,offers'); // written lists=news%2Coffers
+
+listUnsubscribe({ url: url.href });
+```
+
+### Refusals
+
+The URL and the address are checked when the headers are built, before
+anything is sent. A `MailRefused` names the rule, never the value:
+
+| Written | Answer |
+| --- | --- |
+| `url: 'https://example.com/u?token=…'`, `'https://example.com:8443/u?list=a%2Cb'` | accepted |
+| `url: 'http://example.com/u'`, `'mailto:u@example.com'`, `'/unsubscribe'`, `''`, `'https://user:pass@example.com/u'`, `'https://exämple.com/u'` | `MailRefused`: `listUnsubscribe: url must be an https:// URL in printable ASCII, without credentials, <, >, quotes or a raw comma` |
+| a `url` holding a space, a tab, a line break, a character outside ASCII, `<`, `>`, a double quote, a backtick, a backslash, a brace, `|`, `^` or a raw `,` | `MailRefused`: the same message |
+| `mailto: 'Unsub <u@example.com>'`, `'u@example.com, v@example.com'`, `'unsubscribe'`, `'mailto:u@example.com'`, `'u@example.com?subject=x'`, `'ü@example.com'` | `MailRefused`: `listUnsubscribe: mailto must be a bare e-mail address, as unsubscribe@example.com` |
+| `listUnsubscribe(null)` | `TypeError`: `listUnsubscribe: options must be an object, as { url }` |
+| `url: new URL(…)` | a compile error; at run time `TypeError`: `listUnsubscribe: url must be a string` |
+| `mailto: 42` | a compile error; at run time `TypeError`: `listUnsubscribe: mailto must be a string` |
+
+A `TypeError` is a mistake in the code, not in the data: no request handler
+should answer one. A `MailRefused` usually means a URL built from a value that
+was not encoded — keep the call inside the `try` that handles `MailError`.
+
+### A realistic case — a newsletter, one URL per subscriber
+
+```ts
+import { listUnsubscribe, MailError, type Mailer } from '@nxgt/mail';
+import { createMailRenderer } from '@nxgt/mail/renderer';
+
+// Yours: the subscriber store.
+declare function subscribersOf(list: string): AsyncIterable<{ id: string; email: string; name: string; token: string }>;
+
+const mails = createMailRenderer({ dir: 'dist' });
+
+export async function sendIssue(mailer: Mailer, issue: string): Promise<{ sent: number; failed: string[] }> {
+	let sent = 0;
+	const failed: string[] = [];
+	for await (const subscriber of subscribersOf('news')) {
+		const unsubscribe = `https://example.com/unsubscribe?token=${encodeURIComponent(subscriber.token)}`;
+		try {
+			await mailer.send({
+				to: subscriber.email,
+				...mails.render('newsletter', { name: subscriber.name, unsubscribe }), // the link in the body
+				headers: { ...listUnsubscribe({ url: unsubscribe }) }, // the button in the mail client
+				idempotencyKey: `newsletter-${issue}/${subscriber.id}`,
+			});
+			sent += 1;
+		} catch (error) {
+			if (!(error instanceof MailError)) throw error;
+			failed.push(subscriber.id); // an id, never the address or the token
+		}
+	}
+	return { sent, failed };
+}
+```
+
 ## Attachments
 
 An attachment is a file's **bytes**, its name and its type:
@@ -413,7 +621,7 @@ class MailRefused extends MailError {
 | Code | Class | When | Sending it again |
 | --- | --- | --- | --- |
 | `MAIL_FAILED` | `MailFailure` | The transport could not hand the e-mail over: a refused connection, a timeout, a 5xx from the provider, an expired credential. The transport's error is the `cause`. **Nothing is known to have been sent**: after a timeout or a dropped connection the provider may have taken it all the same | May work later — with an [`idempotencyKey`](#idempotency--sending-once), without a second delivery where the transport deduplicates. Never report it as sent |
-| `MAIL_REFUSED` | `MailRefused` | The e-mail itself was refused, before or by the transport: no recipient, something that is not an address, a line break in the subject or a header, a reserved header, an attachment that is not bytes or is badly named, a malformed idempotency key or one already used for a different message, or the provider answering that the message is malformed or too large | Fails again, unchanged |
+| `MAIL_REFUSED` | `MailRefused` | The e-mail itself was refused, before or by the transport: no recipient, something that is not an address, a line break in the subject or a header, a reserved header, an attachment that is not bytes or is badly named, an unsubscribe URL that is not `https:` or holds a raw comma, a malformed idempotency key or one already used for a different message, or the provider answering that the message is malformed or too large | Fails again, unchanged |
 
 `MailError` is **abstract**: catch it, test `instanceof MailError`, but
 `new MailError(…)` does not compile — a bare one would pass a `code` check and

package/docs/roadmap.md

@@ -6,15 +6,13 @@ the only number.
 
 ## Now
 
-- **An idempotency key per send** — `idempotencyKey` on a `MailMessage`
-  names the send, so sending it again — a retry after a timeout, a job run
-  twice — delivers it once where the transport can deduplicate; a transport
-  that cannot ignores it. `checkMessage` refuses a key that is not 1 to 256
-  visible ASCII characters, never quoting it. The memory mailer honours it as
-  Resend does: the same message under a key it already delivered answers
-  that delivery's `messageId` and delivers nothing more, a different message
-  under it is a `MailRefused`, a failed send leaves its key free, and
-  `clear()` forgets the keys. Built, not yet published.
+- **One-click unsubscribe** — `listUnsubscribe({ url, mailto? })` answers
+  RFC 8058's `List-Unsubscribe` and `List-Unsubscribe-Post` headers, to
+  spread into a message's `headers`, so Gmail and Yahoo offer their
+  one-click unsubscribe. A `url` that is not `https:`, or that would break
+  the header, and a `mailto` that is not a bare address are refused with
+  `MailRefused`, never quoting the value. No transport changes: the headers
+  travel as any other. Built, not yet published.
 
 ## Next
 
@@ -71,6 +69,15 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **An idempotency key per send, v0.3.0** — `idempotencyKey` on a `MailMessage`
+  names the send, so sending it again — a retry after a timeout, a job run
+  twice — delivers it once where the transport can deduplicate; a transport
+  that cannot ignores it. `checkMessage` refuses a key that is not 1 to 256
+  visible ASCII characters, never quoting it. The memory mailer honours it as
+  Resend does: the same message under a key it already delivered answers
+  that delivery's `messageId` and delivers nothing more, a different message
+  under it is a `MailRefused`, a failed send leaves its key free, and
+  `clear()` forgets the keys.
 - **Attachments, v0.2.0** — `attachments` on a `MailMessage`: each file's bytes as a
   `Uint8Array`, its name and its type. Bytes only — no path, no URL, no
   stream, so a transport never reads a file or fetches a URL for you; a large
@@ -125,8 +132,3 @@ before is in the [CHANGELOG](../CHANGELOG.md).
   time, one output per locale and the manifest this renderer reads; e-mail
   components in the style of `@nxgt/material-vue`, with shared messages in
   `en` and `fr`; and nine ready e-mails built with your own brand.
-- **A starter that sends, with v0.1.0** — `examples/starter`'s `send.ts` renders its
-  e-mails in `en` and `fr` through `createMailRenderer<MailEmails>` and
-  hands them to `createMemoryMailer()`, run in CI:
-  [`examples/starter`](https://github.com/softistx/nxgt-mail/tree/develop/examples/starter).
-  In the repository; its README says how to start your own from npm.

package/docs/troubleshooting.md

@@ -10,7 +10,8 @@ How the messages are shaped:
   verification e-mail is a credential, and it never reaches a log through an
   error.
 - **Every message starts with the call you wrote**: `send: …`,
-  `createMailRenderer: …`, `render: …`, `pickLocale: …`, `describeMailer: …`.
+  `listUnsubscribe: …`, `createMailRenderer: …`, `render: …`,
+  `pickLocale: …`, `describeMailer: …`.
   A conformance case that fails starts with `conformance: …`.
 - **A `TypeError` is a wiring mistake**: it comes from how the application
   was put together — or, from `render`, from how the call was written —
@@ -69,6 +70,14 @@ How the messages are shaped:
 - [An e-mail is delivered twice although it has an `idempotencyKey`](#an-e-mail-is-delivered-twice-although-it-has-an-idempotencykey)
 - [`send: the memory mailer was told to fail this send`](#send-the-memory-mailer-was-told-to-fail-this-send)
 
+**Unsubscribe**
+- [`listUnsubscribe: url must be an https:// URL in printable ASCII, without credentials, <, >, quotes or a raw comma`](#listunsubscribe-url-must-be-an-https-url-in-printable-ascii-without-credentials---quotes-or-a-raw-comma)
+- [`listUnsubscribe: mailto must be a bare e-mail address, as unsubscribe@example.com`](#listunsubscribe-mailto-must-be-a-bare-e-mail-address-as-unsubscribeexamplecom)
+- [`listUnsubscribe: options must be an object, as { url }`](#listunsubscribe-options-must-be-an-object-as--url-)
+- [`listUnsubscribe: url must be a string`](#listunsubscribe-url-must-be-a-string)
+- [`listUnsubscribe: mailto must be a string`](#listunsubscribe-mailto-must-be-a-string)
+- [Gmail shows no unsubscribe button](#gmail-shows-no-unsubscribe-button)
+
 **Locale**
 - [`pickLocale: supported must hold at least one locale`](#picklocale-supported-must-hold-at-least-one-locale)
 - [`pickLocale: fallback must be one of supported`](#picklocale-fallback-must-be-one-of-supported)
@@ -869,6 +878,164 @@ beforeEach(() => mailer.clear());
 
 ---
 
+## Unsubscribe
+
+`listUnsubscribe` checks its options **when it is called**, before any
+`send`. A value that is text but not a usable URL or address is a
+`MailRefused` (`code: 'MAIL_REFUSED'`), and it never quotes the value: the
+URL usually carries a per-recipient token, and a token is a credential. A
+value that is not text at all is a `TypeError`, a mistake in the code.
+
+### `listUnsubscribe: url must be an https:// URL in printable ASCII, without credentials, <, >, quotes or a raw comma`
+
+A `MailRefused`, `code: 'MAIL_REFUSED'`.
+
+**When:** `listUnsubscribe({ url })`, with a `url` that does not start with
+`https://` (`http:`, `mailto:`, relative, empty, `HTTPS://` in capitals), that
+carries a user or a password (`https://user:pass@…`), or that holds a space,
+a line break, a character outside ASCII, `<`, `>`, a double quote, a backtick, a backslash, a
+brace, `|`, `^` or a `,` as it is: typically a token or a list name pasted
+into a template string without being encoded, or an `http:` URL from a
+development configuration.
+**Why:** RFC 8058 accepts only an `https:` URL for one-click unsubscribe, and
+RFC 2369 an RFC 3986 URI — printable ASCII — between `<` and `>`. A
+transport encodes a header holding anything else, and no client finds the URL
+in it; a `>` would end the URL, and a raw comma is RFC 2369's separator
+between two URLs, so a mail client would read the rest as a second one. A
+user and a password would be read by every relay and recipient.
+**Fix:** build the URL with `new URL()` and set each value with
+`searchParams.set`, which percent-encodes it (`,` becomes `%2C`, a space
+`+`), then pass `.href`:
+
+```ts
+import { listUnsubscribe } from '@nxgt/mail';
+
+declare const token: string;
+
+const url = new URL('https://example.com/unsubscribe');
+url.searchParams.set('token', token);
+
+const headers = listUnsubscribe({ url: url.href });
+```
+
+A value in the path is encoded with `encodeURIComponent` (`/u/${encodeURIComponent(list)}`).
+In development, use an `https:` URL as well, or leave the headers out.
+
+### `listUnsubscribe: mailto must be a bare e-mail address, as unsubscribe@example.com`
+
+A `MailRefused`, `code: 'MAIL_REFUSED'`.
+
+**When:** `listUnsubscribe({ url, mailto })`, with a `mailto` that has a
+display name (`Unsubscribe <unsubscribe@example.com>`), a `mailto:` prefix,
+two addresses, no `@`, a domain without a dot, a character outside ASCII,
+or `?`, `&`, `=`, `#`, `%` or a double quote (`u@example.com?subject=stop`).
+**Why:** `mailto` is one mailbox, and `listUnsubscribe` writes the
+`<mailto:…>` around it itself; a name, a prefix or a second address would
+break the header or be read as something else — in a `mailto:`, `?` starts
+header fields, and `?cc=` would add a recipient.
+**Fix:** pass the address alone:
+
+```ts
+import { listUnsubscribe } from '@nxgt/mail';
+
+declare const token: string;
+
+const headers = listUnsubscribe({
+  url: `https://example.com/unsubscribe?token=${encodeURIComponent(token)}`,
+  mailto: 'unsubscribe@example.com', // ✗ 'mailto:unsubscribe@example.com'
+});
+```
+
+### `listUnsubscribe: options must be an object, as { url }`
+
+A `TypeError`.
+
+**When:** `listUnsubscribe()` with no argument, or with the URL alone:
+typically `listUnsubscribe(url)`.
+**Why:** the options are one object, and `url` is required in it.
+**Fix:** `listUnsubscribe({ url })`.
+
+### `listUnsubscribe: url must be a string`
+
+A `TypeError`.
+
+**When:** `listUnsubscribe({ url })`, with a `url` that is a `URL` object,
+`undefined` or anything else that is not text — from untyped code, since
+TypeScript already refuses a `URL` object (`Type 'URL' is not assignable to
+type 'string'`).
+**Why:** the header holds text; the helper does not guess how to turn a
+value into a URL.
+**Fix:** pass the URL's text:
+
+```ts
+import { listUnsubscribe } from '@nxgt/mail';
+
+const url = new URL('https://example.com/unsubscribe');
+
+const headers = listUnsubscribe({ url: url.href }); // ✗ { url }
+```
+
+### `listUnsubscribe: mailto must be a string`
+
+A `TypeError`.
+
+**When:** `listUnsubscribe({ url, mailto })`, with a `mailto` that is set
+but is not a string — `null`, or an `{ name, address }` object.
+**Why:** `mailto` is one bare address, as text; leave it out for none.
+**Fix:** `mailto: 'unsubscribe@example.com'`, or no `mailto` at all.
+
+### Gmail shows no unsubscribe button
+
+**When:** the message carries both headers from `listUnsubscribe`, yet
+Gmail (or Yahoo) shows no "Unsubscribe" link next to the sender.
+**Why:** the headers make the button possible; the mailbox provider decides
+whether to show it. The usual causes:
+
+- **The sender is not a bulk sender, or its reputation is low.** Gmail shows
+  the button to senders it recognises as sending bulk mail with a good
+  reputation; a new domain, or a handful of test messages, may never get it.
+- **The message is not DKIM-signed by the sending domain**, or the signature
+  does not cover the two headers. RFC 8058 requires a valid DKIM signature
+  whose `h=` includes `List-Unsubscribe` and `List-Unsubscribe-Post`, and
+  Gmail and Yahoo also want it aligned with the `From` domain. Check the received message's original: the
+  `DKIM-Signature` must have `d=` your domain and name both headers.
+- **The endpoint does not unsubscribe on the POST alone.** The client POSTs
+  `List-Unsubscribe=One-Click` to the URL, with no cookie and no session. An
+  answer that is a redirect, a login page, a confirmation page, or an error
+  for a `POST` (a route that only answers `GET`) is a failed unsubscribe.
+- **The e-mail is transactional** — a sign-in code, a password reset, a
+  receipt. Gmail does not offer to unsubscribe from those, and they should
+  not carry the headers: nobody unsubscribes from their own password reset.
+
+**Fix:** set the headers only on e-mails a recipient subscribed to, send
+from a domain that signs with DKIM, and make the URL unsubscribe on the
+`POST` itself:
+
+```ts
+declare function unsubscribeByToken(token: string): Promise<void>; // yours
+
+// POST https://example.com/unsubscribe?token=…, body List-Unsubscribe=One-Click
+async function unsubscribe(request: Request): Promise<Response> {
+  const token = new URL(request.url).searchParams.get('token') ?? '';
+  if (request.method === 'POST') {
+    const form = await request.formData();
+    if (form.get('List-Unsubscribe') !== 'One-Click') return new Response(null, { status: 400 });
+    await unsubscribeByToken(token); // no login, no confirmation
+    return new Response(null, { status: 200 }); // never a redirect
+  }
+  // GET: a person followed the link. Show a page that posts the same form.
+  return new Response(
+    '<form method="post"><input type="hidden" name="List-Unsubscribe" value="One-Click"><button>Unsubscribe</button></form>',
+    { headers: { 'content-type': 'text/html; charset=utf-8' } },
+  );
+}
+```
+
+The full handler, with what the `GET` page may show, is in
+[the sending guide](guide/sending.md#one-click-unsubscribe).
+
+---
+
 ## Locale
 
 ### `pickLocale: supported must hold at least one locale`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/mail",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "The run-time side of transactional e-mail: the renderer that fills a Maizzle build made with @nxgt/mail-i18n, the Mailer a transport implements, its errors, a memory transport and locale selection. No dependency.",
 	"license": "MIT",
 	"type": "module",