@nxgt/mail 0.3.0 → 0.5.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 |
 
@@ -57,7 +57,7 @@ so a missing build fails there, not at the first send:
 ```ts
 import { type Mailer, pickLocale } from '@nxgt/mail';
 import { createMailRenderer } from '@nxgt/mail/renderer';
-import type { MailEmails } from './generated/mail'; // written by the build, committed
+import type { MailEmails } from './generated/mail'; // written by each build, git-ignored
 
 export const mails = createMailRenderer<MailEmails>({ dir: 'dist' }); // throws now if dist/ is missing
 
@@ -78,7 +78,8 @@ throws `MailRefused`. A missing or unknown variable, e-mail or locale throws an
 `Error`.
 
 `<MailEmails>` is optional. `@nxgt/mail-i18n` writes it after each build, in
-`generated/mail.ts`, from the manifest; commit it. With it, the compiler
+`generated/mail.ts`, from the manifest; git-ignore it, and build before
+type-checking. With it, the compiler
 refuses what `render` would throw: an e-mail the build does not have, a
 variable missing or unknown, and a number for a URL variable, as
 `Argument of type '"verify-emial"' is not assignable to parameter of type
@@ -193,6 +194,48 @@ 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, raw comma (percent-encode
+it: `%2C`) or `%` that starts no escape, and `mailto` must be a bare ASCII
+address. The URL is written as a parser reads it (`new URL(url).href`: the
+host lowered, an empty `@` or extra slashes dropped), and checked again:
+`https://a%2Cb.test/` writes a raw comma, so it is refused. 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 +439,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 +481,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 +498,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/conformance/cases/send.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../../src/conformance/cases/send.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,uDAAuD;AACvD,eAAO,MAAM,SAAS,EAAE,SAAS,UAAU,EAqO1C,CAAC"}
+{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../../src/conformance/cases/send.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,uDAAuD;AACvD,eAAO,MAAM,SAAS,EAAE,SAAS,UAAU,EAqQ1C,CAAC"}

package/dist/conformance/index.js

@@ -162,6 +162,22 @@ var sendCases = [
       check(mail.text === sampleMessage.text && mail.html === sampleMessage.html, "the parts of a message with an attachment were not delivered as sent");
     }
   },
+  {
+    id: "send.idempotencyKey",
+    title: "a message with an idempotency key is delivered, and the key is in none of its recipients, subject, HTML or text",
+    async run(context) {
+      const key = `conformance-${crypto.randomUUID()}`;
+      const sent = await context.mailer.send({
+        ...sampleMessage,
+        idempotencyKey: key
+      });
+      check(typeof sent === "object" && sent !== null && "messageId" in sent, "a send with an idempotency key did not answer SentMail");
+      const delivered = await context.delivered();
+      check(delivered.length === 1, `expected 1 delivered message, got ${delivered.length}`);
+      const [mail] = delivered;
+      check(![mail?.subject, mail?.html, mail?.text, ...mail?.to ?? []].some((part) => part?.includes(key)), "the idempotency key was written into the e-mail");
+    }
+  },
   {
     id: "send.refusesNoRecipient",
     title: "a message with no recipient is refused with MailRefused, and nothing is sent",
@@ -334,5 +350,5 @@ export {
   sendCases
 };
 
-//# debugId=D8FC228C191C6BF264756E2164756E21
+//# debugId=5D29AA162B05B41464756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/conformance/index.js.map

@@ -5,12 +5,12 @@
     "import type { MailerCaseContext } from './types';\n\n/** Throws when `condition` is false. The suite depends on no assertion library. */\nexport function check(condition: boolean, what: string): asserts condition {\n\tif (!condition) throw new Error(`conformance: ${what}`);\n}\n\nexport const same = (a: unknown, b: unknown) =>\n\tJSON.stringify(a) === JSON.stringify(b);\n\n/**\n * Settles an expected rejection where it is created, and answers the error —\n * or throws when the promise resolved.\n */\nexport async function rejection(\n\tpromise: Promise<unknown>,\n\twhat: string,\n): Promise<unknown> {\n\treturn promise.then(\n\t\t() => {\n\t\t\tthrow new Error(`conformance: ${what} resolved; it must reject`);\n\t\t},\n\t\t(error: unknown) => error,\n\t);\n}\n\n/** Throws when the receiving end got anything. */\nexport async function nothingDelivered(\n\tcontext: MailerCaseContext,\n\twhat: string,\n) {\n\tcheck(\n\t\t(await context.delivered()).length === 0,\n\t\t`${what}, yet something was delivered`,\n\t);\n}\n",
     "import type { MailAttachment, MailMessage } from '../types';\n\n/** A message with the characters a transport most often mangles. */\nexport const sampleMessage: MailMessage = {\n\tto: 'ada@example.test',\n\tfrom: 'noreply@example.test',\n\tsubject: 'Réinitialisez votre mot de passe — ça expire à 23 h',\n\thtml: '<p>Bonjour Ada 👋, <a href=\"https://example.test/r?t=abc&amp;x=1\">réinitialiser</a></p>',\n\ttext: 'Bonjour Ada 👋,\\n\\nréinitialiser : https://example.test/r?t=abc&x=1\\n',\n};\n\n/**\n * A small binary file, every byte from 0 to 255 once — a NUL, a CR and an LF\n * among them, and bytes that are not UTF-8 — with a name a header must encode.\n */\nexport const sampleAttachment: MailAttachment = {\n\tfilename: 'reçu n° 42.pdf',\n\tcontent: Uint8Array.from({ length: 256 }, (_, byte) => byte),\n\tcontentType: 'application/pdf',\n};\n",
     "import { MailError, MailFailure, MailRefused } from '../../errors';\nimport { check, nothingDelivered, rejection } from '../assert';\nimport { sampleMessage } from '../sample';\nimport type { MailerCase } from '../types';\n\n/** What a send must do when the transport fails. Needs {@link MailerFaults}. */\nexport const failureCases: readonly MailerCase[] = [\n\t{\n\t\tid: 'failure.outage',\n\t\ttitle:\n\t\t\t'an outage throws MailFailure with the cause, and nothing is retried',\n\t\tneeds: 'faults',\n\t\tasync run(context) {\n\t\t\tconst faults = context.faults;\n\t\t\tcheck(faults !== null, 'faults are required');\n\t\t\tawait faults.failNext('outage');\n\t\t\tconst error = await rejection(\n\t\t\t\tcontext.mailer.send(sampleMessage),\n\t\t\t\t'a send during an outage',\n\t\t\t);\n\t\t\t// The class is the one imported from @nxgt/mail: a transport that\n\t\t\t// defines its own copy fails here.\n\t\t\tcheck(\n\t\t\t\terror instanceof MailFailure,\n\t\t\t\t'an outage must throw MailFailure from @nxgt/mail',\n\t\t\t);\n\t\t\tcheck(error instanceof MailError, 'MailFailure must extend MailError');\n\t\t\tcheck(\n\t\t\t\terror.code === 'MAIL_FAILED',\n\t\t\t\t'an outage must carry the code MAIL_FAILED',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\terror.cause !== undefined,\n\t\t\t\t\"an outage must carry the transport's error as cause\",\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\t(await faults.attempts()) === 1,\n\t\t\t\t'the transport retried a failed hand-over',\n\t\t\t);\n\t\t\tawait nothingDelivered(context, 'the hand-over failed');\n\t\t},\n\t},\n\t{\n\t\tid: 'failure.refusal',\n\t\ttitle: 'a message the provider refuses throws MailRefused with the cause',\n\t\tneeds: 'faults',\n\t\tasync run(context) {\n\t\t\tconst faults = context.faults;\n\t\t\tcheck(faults !== null, 'faults are required');\n\t\t\tawait faults.failNext('refusal');\n\t\t\tconst error = await rejection(\n\t\t\t\tcontext.mailer.send(sampleMessage),\n\t\t\t\t'a refused send',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\terror instanceof MailRefused,\n\t\t\t\t'a refusal must throw MailRefused from @nxgt/mail',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\terror.code === 'MAIL_REFUSED',\n\t\t\t\t'a refusal must carry the code MAIL_REFUSED',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\terror.cause !== undefined,\n\t\t\t\t\"a refusal must carry the transport's error as cause\",\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\t(await faults.attempts()) === 1,\n\t\t\t\t'the transport retried a refused message',\n\t\t\t);\n\t\t},\n\t},\n\t{\n\t\tid: 'failure.recovers',\n\t\ttitle: 'after a failure, the next send goes through',\n\t\tneeds: 'faults',\n\t\tasync run(context) {\n\t\t\tconst faults = context.faults;\n\t\t\tcheck(faults !== null, 'faults are required');\n\t\t\tawait faults.failNext('outage');\n\t\t\tawait rejection(\n\t\t\t\tcontext.mailer.send(sampleMessage),\n\t\t\t\t'a send during an outage',\n\t\t\t);\n\t\t\tawait context.mailer.send(sampleMessage);\n\t\t\tcheck(\n\t\t\t\t(await context.delivered()).length === 1,\n\t\t\t\t'the send after a failure was not delivered',\n\t\t\t);\n\t\t},\n\t},\n];\n",
-    "import { MailRefused } from '../../errors';\nimport { check, nothingDelivered, rejection, same } from '../assert';\nimport { sampleAttachment, sampleMessage } from '../sample';\nimport type { MailerCase } from '../types';\n\n/** What every send must do, with no fault injected. */\nexport const sendCases: readonly MailerCase[] = [\n\t{\n\t\tid: 'send.answersSentMail',\n\t\ttitle: 'a send answers SentMail, with a string id or null',\n\t\tasync run({ mailer }) {\n\t\t\tconst sent = await mailer.send(sampleMessage);\n\t\t\tcheck(\n\t\t\t\ttypeof sent === 'object' && sent !== null && 'messageId' in sent,\n\t\t\t\t'send did not answer an object with messageId',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\tsent.messageId === null ||\n\t\t\t\t\t(typeof sent.messageId === 'string' && sent.messageId !== ''),\n\t\t\t\t'messageId must be a non-empty string or null',\n\t\t\t);\n\t\t},\n\t},\n\t{\n\t\tid: 'send.deliversBytes',\n\t\ttitle:\n\t\t\t'a message is delivered byte for byte: accents, an emoji, a text part',\n\t\tasync run(context) {\n\t\t\tawait context.mailer.send(sampleMessage);\n\t\t\tconst delivered = await context.delivered();\n\t\t\tcheck(\n\t\t\t\tdelivered.length === 1,\n\t\t\t\t`expected 1 delivered message, got ${delivered.length}`,\n\t\t\t);\n\t\t\tconst [mail] = delivered;\n\t\t\tcheck(\n\t\t\t\tmail?.subject === sampleMessage.subject,\n\t\t\t\t'the subject was not delivered as sent',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\tmail?.html === sampleMessage.html,\n\t\t\t\t'the html part was not delivered as sent',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\tmail?.text === sampleMessage.text,\n\t\t\t\t'the text part was not delivered as sent',\n\t\t\t);\n\t\t},\n\t},\n\t{\n\t\tid: 'send.recipients',\n\t\ttitle:\n\t\t\t'every recipient is delivered to, written as a string or with a name',\n\t\tasync run(context) {\n\t\t\tawait context.mailer.send({\n\t\t\t\t...sampleMessage,\n\t\t\t\tto: [\n\t\t\t\t\t'ada@example.test',\n\t\t\t\t\t{ name: 'Grace Hopper', address: 'grace@example.test' },\n\t\t\t\t],\n\t\t\t});\n\t\t\tconst [mail] = await context.delivered();\n\t\t\tcheck(\n\t\t\t\tsame(mail?.to, ['ada@example.test', 'grace@example.test']),\n\t\t\t\t'the recipients delivered are not the recipients sent',\n\t\t\t);\n\t\t},\n\t},\n\t{\n\t\tid: 'send.hostileName',\n\t\ttitle: 'a name holding an address and a comma reaches only its own address',\n\t\tasync run(context) {\n\t\t\t// A name is free text, and quoting it is the transport's job. One that\n\t\t\t// pastes it into a header unquoted hands mallory a copy.\n\t\t\tawait context.mailer.send({\n\t\t\t\t...sampleMessage,\n\t\t\t\tto: {\n\t\t\t\t\tname: 'Ada <mallory@example.test>, \"Eve\" <eve@example.test>;',\n\t\t\t\t\taddress: 'ada@example.test',\n\t\t\t\t},\n\t\t\t});\n\t\t\tconst [mail] = await context.delivered();\n\t\t\tcheck(\n\t\t\t\tsame(mail?.to, ['ada@example.test']),\n\t\t\t\t'a name let a second recipient through',\n\t\t\t);\n\t\t},\n\t},\n\t{\n\t\tid: 'send.attachment',\n\t\ttitle:\n\t\t\t'an attachment is delivered byte for byte, with its name and its type',\n\t\tasync run(context) {\n\t\t\tawait context.mailer.send({\n\t\t\t\t...sampleMessage,\n\t\t\t\tattachments: [sampleAttachment],\n\t\t\t});\n\t\t\tconst [mail] = await context.delivered();\n\t\t\tcheck(\n\t\t\t\tmail !== undefined,\n\t\t\t\t'the message with an attachment was not delivered',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\tmail.attachments !== undefined,\n\t\t\t\t\"the harness's delivered() reads back no attachments — read them from the receiving end, or skip send.attachment with the reason\",\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\tmail.attachments.length === 1,\n\t\t\t\t`expected 1 delivered attachment, got ${mail.attachments.length}`,\n\t\t\t);\n\t\t\tconst [file] = mail.attachments;\n\t\t\tcheck(\n\t\t\t\tfile?.filename === sampleAttachment.filename,\n\t\t\t\t'the attachment was not delivered with its file name',\n\t\t\t);\n\t\t\t// A media type is case-insensitive: a parser may lower it.\n\t\t\tcheck(\n\t\t\t\tfile.contentType.toLowerCase() === sampleAttachment.contentType,\n\t\t\t\t'the attachment was not delivered with its content type',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\tfile.content instanceof Uint8Array &&\n\t\t\t\t\tsame([...file.content], [...sampleAttachment.content]),\n\t\t\t\t'the attachment was not delivered byte for byte',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\tmail.text === sampleMessage.text && mail.html === sampleMessage.html,\n\t\t\t\t'the parts of a message with an attachment were not delivered as sent',\n\t\t\t);\n\t\t},\n\t},\n\t{\n\t\tid: 'send.refusesNoRecipient',\n\t\ttitle:\n\t\t\t'a message with no recipient is refused with MailRefused, and nothing is sent',\n\t\tasync run(context) {\n\t\t\tconst error = await rejection(\n\t\t\t\tcontext.mailer.send({ ...sampleMessage, to: [] }),\n\t\t\t\t'a send with no recipient',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\terror instanceof MailRefused,\n\t\t\t\t'a send with no recipient must throw MailRefused',\n\t\t\t);\n\t\t\tawait nothingDelivered(context, 'the message was refused');\n\t\t},\n\t},\n\t{\n\t\tid: 'send.refusesLineBreakInSubject',\n\t\ttitle:\n\t\t\t'a line break in the subject is refused with MailRefused: it is a header injection',\n\t\tasync run(context) {\n\t\t\tconst error = await rejection(\n\t\t\t\tcontext.mailer.send({\n\t\t\t\t\t...sampleMessage,\n\t\t\t\t\tsubject: 'Hello\\r\\nBcc: eve@example.test',\n\t\t\t\t}),\n\t\t\t\t'a send with a line break in the subject',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\terror instanceof MailRefused,\n\t\t\t\t'a line break in the subject must throw MailRefused',\n\t\t\t);\n\t\t\tawait nothingDelivered(context, 'the message was refused');\n\t\t},\n\t},\n\t{\n\t\tid: 'send.refusesAddressHeader',\n\t\ttitle:\n\t\t\t'a Bcc among the custom headers is refused with MailRefused: it would add an unchecked recipient',\n\t\tasync run(context) {\n\t\t\t// A custom header named Bcc, To or Cc reaches the envelope of an SMTP\n\t\t\t// transport, and writes a line no address check ever saw.\n\t\t\tconst error = await rejection(\n\t\t\t\tcontext.mailer.send({\n\t\t\t\t\t...sampleMessage,\n\t\t\t\t\t// biome-ignore lint/style/useNamingConvention: a header's name, as a mail client writes it.\n\t\t\t\t\theaders: { Bcc: 'eve@example.test' },\n\t\t\t\t}),\n\t\t\t\t'a send with a Bcc header',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\terror instanceof MailRefused,\n\t\t\t\t'a Bcc header must throw MailRefused',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\t!error.message.includes('eve@example.test'),\n\t\t\t\t'the refusal message holds the refused value',\n\t\t\t);\n\t\t\tawait nothingDelivered(context, 'the message was refused');\n\t\t},\n\t},\n\t{\n\t\tid: 'send.refusesAttachmentPath',\n\t\ttitle:\n\t\t\t'an attachment named with a path is refused with MailRefused: a mail client could save it elsewhere',\n\t\tasync run(context) {\n\t\t\tconst error = await rejection(\n\t\t\t\tcontext.mailer.send({\n\t\t\t\t\t...sampleMessage,\n\t\t\t\t\tattachments: [\n\t\t\t\t\t\t{ ...sampleAttachment, filename: '../secret-7f3a/report.pdf' },\n\t\t\t\t\t],\n\t\t\t\t}),\n\t\t\t\t'a send with an attachment named with a path',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\terror instanceof MailRefused,\n\t\t\t\t'an attachment named with a path must throw MailRefused',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\t!error.message.includes('secret-7f3a'),\n\t\t\t\t'the refusal message holds the refused value',\n\t\t\t);\n\t\t\tawait nothingDelivered(context, 'the message was refused');\n\t\t},\n\t},\n\t{\n\t\tid: 'send.refusesWithoutTheValue',\n\t\ttitle: 'a refusal names where the problem is, never the value',\n\t\tasync run({ mailer }) {\n\t\t\tconst error = await rejection(\n\t\t\t\tmailer.send({ ...sampleMessage, to: 'not-an-address-7f3a' }),\n\t\t\t\t'a send to something that is not an address',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\terror instanceof MailRefused,\n\t\t\t\t'a malformed address must throw MailRefused',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\t!error.message.includes('not-an-address-7f3a'),\n\t\t\t\t'the refusal message holds the refused value',\n\t\t\t);\n\t\t},\n\t},\n];\n",
+    "import { MailRefused } from '../../errors';\nimport { check, nothingDelivered, rejection, same } from '../assert';\nimport { sampleAttachment, sampleMessage } from '../sample';\nimport type { MailerCase } from '../types';\n\n/** What every send must do, with no fault injected. */\nexport const sendCases: readonly MailerCase[] = [\n\t{\n\t\tid: 'send.answersSentMail',\n\t\ttitle: 'a send answers SentMail, with a string id or null',\n\t\tasync run({ mailer }) {\n\t\t\tconst sent = await mailer.send(sampleMessage);\n\t\t\tcheck(\n\t\t\t\ttypeof sent === 'object' && sent !== null && 'messageId' in sent,\n\t\t\t\t'send did not answer an object with messageId',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\tsent.messageId === null ||\n\t\t\t\t\t(typeof sent.messageId === 'string' && sent.messageId !== ''),\n\t\t\t\t'messageId must be a non-empty string or null',\n\t\t\t);\n\t\t},\n\t},\n\t{\n\t\tid: 'send.deliversBytes',\n\t\ttitle:\n\t\t\t'a message is delivered byte for byte: accents, an emoji, a text part',\n\t\tasync run(context) {\n\t\t\tawait context.mailer.send(sampleMessage);\n\t\t\tconst delivered = await context.delivered();\n\t\t\tcheck(\n\t\t\t\tdelivered.length === 1,\n\t\t\t\t`expected 1 delivered message, got ${delivered.length}`,\n\t\t\t);\n\t\t\tconst [mail] = delivered;\n\t\t\tcheck(\n\t\t\t\tmail?.subject === sampleMessage.subject,\n\t\t\t\t'the subject was not delivered as sent',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\tmail?.html === sampleMessage.html,\n\t\t\t\t'the html part was not delivered as sent',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\tmail?.text === sampleMessage.text,\n\t\t\t\t'the text part was not delivered as sent',\n\t\t\t);\n\t\t},\n\t},\n\t{\n\t\tid: 'send.recipients',\n\t\ttitle:\n\t\t\t'every recipient is delivered to, written as a string or with a name',\n\t\tasync run(context) {\n\t\t\tawait context.mailer.send({\n\t\t\t\t...sampleMessage,\n\t\t\t\tto: [\n\t\t\t\t\t'ada@example.test',\n\t\t\t\t\t{ name: 'Grace Hopper', address: 'grace@example.test' },\n\t\t\t\t],\n\t\t\t});\n\t\t\tconst [mail] = await context.delivered();\n\t\t\tcheck(\n\t\t\t\tsame(mail?.to, ['ada@example.test', 'grace@example.test']),\n\t\t\t\t'the recipients delivered are not the recipients sent',\n\t\t\t);\n\t\t},\n\t},\n\t{\n\t\tid: 'send.hostileName',\n\t\ttitle: 'a name holding an address and a comma reaches only its own address',\n\t\tasync run(context) {\n\t\t\t// A name is free text, and quoting it is the transport's job. One that\n\t\t\t// pastes it into a header unquoted hands mallory a copy.\n\t\t\tawait context.mailer.send({\n\t\t\t\t...sampleMessage,\n\t\t\t\tto: {\n\t\t\t\t\tname: 'Ada <mallory@example.test>, \"Eve\" <eve@example.test>;',\n\t\t\t\t\taddress: 'ada@example.test',\n\t\t\t\t},\n\t\t\t});\n\t\t\tconst [mail] = await context.delivered();\n\t\t\tcheck(\n\t\t\t\tsame(mail?.to, ['ada@example.test']),\n\t\t\t\t'a name let a second recipient through',\n\t\t\t);\n\t\t},\n\t},\n\t{\n\t\tid: 'send.attachment',\n\t\ttitle:\n\t\t\t'an attachment is delivered byte for byte, with its name and its type',\n\t\tasync run(context) {\n\t\t\tawait context.mailer.send({\n\t\t\t\t...sampleMessage,\n\t\t\t\tattachments: [sampleAttachment],\n\t\t\t});\n\t\t\tconst [mail] = await context.delivered();\n\t\t\tcheck(\n\t\t\t\tmail !== undefined,\n\t\t\t\t'the message with an attachment was not delivered',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\tmail.attachments !== undefined,\n\t\t\t\t\"the harness's delivered() reads back no attachments — read them from the receiving end, or skip send.attachment with the reason\",\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\tmail.attachments.length === 1,\n\t\t\t\t`expected 1 delivered attachment, got ${mail.attachments.length}`,\n\t\t\t);\n\t\t\tconst [file] = mail.attachments;\n\t\t\tcheck(\n\t\t\t\tfile?.filename === sampleAttachment.filename,\n\t\t\t\t'the attachment was not delivered with its file name',\n\t\t\t);\n\t\t\t// A media type is case-insensitive: a parser may lower it.\n\t\t\tcheck(\n\t\t\t\tfile.contentType.toLowerCase() === sampleAttachment.contentType,\n\t\t\t\t'the attachment was not delivered with its content type',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\tfile.content instanceof Uint8Array &&\n\t\t\t\t\tsame([...file.content], [...sampleAttachment.content]),\n\t\t\t\t'the attachment was not delivered byte for byte',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\tmail.text === sampleMessage.text && mail.html === sampleMessage.html,\n\t\t\t\t'the parts of a message with an attachment were not delivered as sent',\n\t\t\t);\n\t\t},\n\t},\n\t{\n\t\tid: 'send.idempotencyKey',\n\t\ttitle:\n\t\t\t'a message with an idempotency key is delivered, and the key is in none of its recipients, subject, HTML or text',\n\t\tasync run(context) {\n\t\t\t// A transport either passes the key to a provider that deduplicates, or\n\t\t\t// ignores it. Neither refuses the message, and neither writes the key\n\t\t\t// where the reader sees it. A key per run: a harness that remembers\n\t\t\t// keys, as a provider's sandbox does, would otherwise replay the send.\n\t\t\tconst key = `conformance-${crypto.randomUUID()}`;\n\t\t\tconst sent = await context.mailer.send({\n\t\t\t\t...sampleMessage,\n\t\t\t\tidempotencyKey: key,\n\t\t\t});\n\t\t\tcheck(\n\t\t\t\ttypeof sent === 'object' && sent !== null && 'messageId' in sent,\n\t\t\t\t'a send with an idempotency key did not answer SentMail',\n\t\t\t);\n\t\t\tconst delivered = await context.delivered();\n\t\t\tcheck(\n\t\t\t\tdelivered.length === 1,\n\t\t\t\t`expected 1 delivered message, got ${delivered.length}`,\n\t\t\t);\n\t\t\tconst [mail] = delivered;\n\t\t\tcheck(\n\t\t\t\t![mail?.subject, mail?.html, mail?.text, ...(mail?.to ?? [])].some(\n\t\t\t\t\t(part) => part?.includes(key),\n\t\t\t\t),\n\t\t\t\t'the idempotency key was written into the e-mail',\n\t\t\t);\n\t\t},\n\t},\n\t{\n\t\tid: 'send.refusesNoRecipient',\n\t\ttitle:\n\t\t\t'a message with no recipient is refused with MailRefused, and nothing is sent',\n\t\tasync run(context) {\n\t\t\tconst error = await rejection(\n\t\t\t\tcontext.mailer.send({ ...sampleMessage, to: [] }),\n\t\t\t\t'a send with no recipient',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\terror instanceof MailRefused,\n\t\t\t\t'a send with no recipient must throw MailRefused',\n\t\t\t);\n\t\t\tawait nothingDelivered(context, 'the message was refused');\n\t\t},\n\t},\n\t{\n\t\tid: 'send.refusesLineBreakInSubject',\n\t\ttitle:\n\t\t\t'a line break in the subject is refused with MailRefused: it is a header injection',\n\t\tasync run(context) {\n\t\t\tconst error = await rejection(\n\t\t\t\tcontext.mailer.send({\n\t\t\t\t\t...sampleMessage,\n\t\t\t\t\tsubject: 'Hello\\r\\nBcc: eve@example.test',\n\t\t\t\t}),\n\t\t\t\t'a send with a line break in the subject',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\terror instanceof MailRefused,\n\t\t\t\t'a line break in the subject must throw MailRefused',\n\t\t\t);\n\t\t\tawait nothingDelivered(context, 'the message was refused');\n\t\t},\n\t},\n\t{\n\t\tid: 'send.refusesAddressHeader',\n\t\ttitle:\n\t\t\t'a Bcc among the custom headers is refused with MailRefused: it would add an unchecked recipient',\n\t\tasync run(context) {\n\t\t\t// A custom header named Bcc, To or Cc reaches the envelope of an SMTP\n\t\t\t// transport, and writes a line no address check ever saw.\n\t\t\tconst error = await rejection(\n\t\t\t\tcontext.mailer.send({\n\t\t\t\t\t...sampleMessage,\n\t\t\t\t\t// biome-ignore lint/style/useNamingConvention: a header's name, as a mail client writes it.\n\t\t\t\t\theaders: { Bcc: 'eve@example.test' },\n\t\t\t\t}),\n\t\t\t\t'a send with a Bcc header',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\terror instanceof MailRefused,\n\t\t\t\t'a Bcc header must throw MailRefused',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\t!error.message.includes('eve@example.test'),\n\t\t\t\t'the refusal message holds the refused value',\n\t\t\t);\n\t\t\tawait nothingDelivered(context, 'the message was refused');\n\t\t},\n\t},\n\t{\n\t\tid: 'send.refusesAttachmentPath',\n\t\ttitle:\n\t\t\t'an attachment named with a path is refused with MailRefused: a mail client could save it elsewhere',\n\t\tasync run(context) {\n\t\t\tconst error = await rejection(\n\t\t\t\tcontext.mailer.send({\n\t\t\t\t\t...sampleMessage,\n\t\t\t\t\tattachments: [\n\t\t\t\t\t\t{ ...sampleAttachment, filename: '../secret-7f3a/report.pdf' },\n\t\t\t\t\t],\n\t\t\t\t}),\n\t\t\t\t'a send with an attachment named with a path',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\terror instanceof MailRefused,\n\t\t\t\t'an attachment named with a path must throw MailRefused',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\t!error.message.includes('secret-7f3a'),\n\t\t\t\t'the refusal message holds the refused value',\n\t\t\t);\n\t\t\tawait nothingDelivered(context, 'the message was refused');\n\t\t},\n\t},\n\t{\n\t\tid: 'send.refusesWithoutTheValue',\n\t\ttitle: 'a refusal names where the problem is, never the value',\n\t\tasync run({ mailer }) {\n\t\t\tconst error = await rejection(\n\t\t\t\tmailer.send({ ...sampleMessage, to: 'not-an-address-7f3a' }),\n\t\t\t\t'a send to something that is not an address',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\terror instanceof MailRefused,\n\t\t\t\t'a malformed address must throw MailRefused',\n\t\t\t);\n\t\t\tcheck(\n\t\t\t\t!error.message.includes('not-an-address-7f3a'),\n\t\t\t\t'the refusal message holds the refused value',\n\t\t\t);\n\t\t},\n\t},\n];\n",
     "import type { MailerCase } from '../types';\nimport { failureCases } from './failure';\nimport { sendCases } from './send';\n\nexport { failureCases } from './failure';\nexport { sendCases } from './send';\n\n/** Every case, in the order they are described. */\nexport const allMailerCases: readonly MailerCase[] = [\n\t...sendCases,\n\t...failureCases,\n];\n",
     "import { allMailerCases } from './cases/index';\nimport type { MailerCase, MailerHarness, MailerRunner } from './types';\n\n/** Why a case did not run. A skip is always reported with its reason, never silent. */\nexport const MAILER_SKIP_REASONS = {\n\tfaults:\n\t\t'faults not provided: the failure contract is not proven for this transport',\n} as const;\n\n/**\n * Runs one case against a freshly opened transport, and closes it, pass or\n * fail. Answers the reason when the case cannot run on this harness.\n */\nexport async function runMailerCase(\n\tmailerCase: MailerCase,\n\tharness: MailerHarness,\n): Promise<{ readonly skipped: string } | { readonly passed: true }> {\n\tconst opened = await harness.open();\n\tlet outcome: { readonly skipped: string } | { readonly passed: true };\n\ttry {\n\t\tif (mailerCase.needs === 'faults' && opened.faults === undefined) {\n\t\t\toutcome = { skipped: MAILER_SKIP_REASONS.faults };\n\t\t} else {\n\t\t\tawait mailerCase.run({\n\t\t\t\tmailer: opened.mailer,\n\t\t\t\tdelivered: () => opened.delivered(),\n\t\t\t\tfaults: opened.faults ?? null,\n\t\t\t});\n\t\t\toutcome = { passed: true };\n\t\t}\n\t} catch (error) {\n\t\t// The case's failure is what the author needs to read: a close that\n\t\t// fails too must not replace it.\n\t\tawait opened.close?.().then(\n\t\t\t() => undefined,\n\t\t\t() => undefined,\n\t\t);\n\t\tthrow error;\n\t}\n\tawait opened.close?.();\n\treturn outcome;\n}\n\nfunction globalRunner(): MailerRunner {\n\tconst { describe, it } = globalThis as unknown as Partial<MailerRunner>;\n\tif (typeof describe !== 'function' || typeof it !== 'function') {\n\t\tthrow new TypeError(\n\t\t\t'describeMailer: no test runner found — pass runner: { describe, it } from your test framework',\n\t\t);\n\t}\n\treturn { describe, it };\n}\n\n/**\n * Describes every case against one transport, under bun:test, vitest or jest.\n *\n * ```ts\n * import { describe, it } from 'bun:test';\n * import { describeMailer } from '@nxgt/mail/conformance';\n *\n * describeMailer({ name: 'my transport', harness, runner: { describe, it } });\n * ```\n *\n * `runner` defaults to the global `describe` and `it`, when the framework\n * defines them.\n */\nexport function describeMailer(options: {\n\treadonly name: string;\n\treadonly harness: MailerHarness;\n\treadonly runner?: MailerRunner;\n\t/** Case ids to skip, each with the reason — reported, never silent. */\n\treadonly skip?: Readonly<Record<string, string>>;\n\t/** Declared up front, so a missing `faults` is reported before the first case runs. */\n\treadonly faults?: boolean;\n}): void {\n\tconst runner = options.runner ?? globalRunner();\n\tconst skip = options.skip ?? {};\n\tfor (const id of Object.keys(skip)) {\n\t\tif (!allMailerCases.some((c) => c.id === id)) {\n\t\t\tthrow new TypeError(`describeMailer: skip names no case: ${id}`);\n\t\t}\n\t}\n\n\trunner.describe(`${options.name} — @nxgt/mail conformance`, () => {\n\t\tfor (const mailerCase of allMailerCases) {\n\t\t\tconst title = `${mailerCase.id}: ${mailerCase.title}`;\n\t\t\tconst reason =\n\t\t\t\tskip[mailerCase.id] ??\n\t\t\t\t(mailerCase.needs === 'faults' && options.faults === false\n\t\t\t\t\t? MAILER_SKIP_REASONS.faults\n\t\t\t\t\t: undefined);\n\t\t\tif (reason !== undefined) {\n\t\t\t\trunner.it.skip(`${title} (skipped: ${reason})`, async () => {});\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\trunner.it(title, async () => {\n\t\t\t\tconst result = await runMailerCase(mailerCase, options.harness);\n\t\t\t\tif ('skipped' in result) {\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t`conformance: ${mailerCase.id}: ${result.skipped} — pass faults: false to describeMailer to skip it on purpose`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t});\n\t\t}\n\t});\n}\n",
     "import { MailFailure, MailRefused } from '../errors';\nimport { createMemoryMailer } from '../memory';\nimport { recipientsOf } from '../message';\nimport type { MailerHarness } from './types';\n\n/**\n * The harness of the memory mailer, the transport the suite is proven\n * against. Also a working example of a harness.\n */\nexport function referenceMailerHarness(): MailerHarness {\n\treturn {\n\t\tasync open() {\n\t\t\tconst mailer = createMemoryMailer();\n\t\t\treturn {\n\t\t\t\tmailer,\n\t\t\t\tasync delivered() {\n\t\t\t\t\treturn mailer.sent.map((mail) => ({\n\t\t\t\t\t\tto: recipientsOf(mail),\n\t\t\t\t\t\tsubject: mail.subject,\n\t\t\t\t\t\thtml: mail.html,\n\t\t\t\t\t\ttext: mail.text,\n\t\t\t\t\t\tattachments: mail.attachments ?? [],\n\t\t\t\t\t}));\n\t\t\t\t},\n\t\t\t\tfaults: {\n\t\t\t\t\tasync failNext(kind) {\n\t\t\t\t\t\tconst cause = new Error(`simulated ${kind}`);\n\t\t\t\t\t\tmailer.failNext(\n\t\t\t\t\t\t\tkind === 'outage'\n\t\t\t\t\t\t\t\t? new MailFailure('send: the transport could not be reached', {\n\t\t\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t\t\t})\n\t\t\t\t\t\t\t\t: new MailRefused('send: the transport refused the message', {\n\t\t\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t);\n\t\t\t\t\t},\n\t\t\t\t\tasync attempts() {\n\t\t\t\t\t\treturn mailer.attempts;\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t};\n\t\t},\n\t};\n}\n"
   ],
-  "mappings": ";;;;;;;;;;;AAGO,SAAS,KAAK,CAAC,WAAoB,MAAiC;AAAA,EAC1E,IAAI,CAAC;AAAA,IAAW,MAAM,IAAI,MAAM,gBAAgB,MAAM;AAAA;AAGhD,IAAM,OAAO,CAAC,GAAY,MAChC,KAAK,UAAU,CAAC,MAAM,KAAK,UAAU,CAAC;AAMvC,eAAsB,SAAS,CAC9B,SACA,MACmB;AAAA,EACnB,OAAO,QAAQ,KACd,MAAM;AAAA,IACL,MAAM,IAAI,MAAM,gBAAgB,+BAA+B;AAAA,KAEhE,CAAC,UAAmB,KACrB;AAAA;AAID,eAAsB,gBAAgB,CACrC,SACA,MACC;AAAA,EACD,OACE,MAAM,QAAQ,UAAU,GAAG,WAAW,GACvC,GAAG,mCACJ;AAAA;;;AC/BM,IAAM,gBAA6B;AAAA,EACzC,IAAI;AAAA,EACJ,MAAM;AAAA,EACN,SAAS;AAAA,EACT,MAAM;AAAA,EACN,MAAM;AAAA;AAAA;AAAA;AACP;AAMO,IAAM,mBAAmC;AAAA,EAC/C,UAAU;AAAA,EACV,SAAS,WAAW,KAAK,EAAE,QAAQ,IAAI,GAAG,CAAC,GAAG,SAAS,IAAI;AAAA,EAC3D,aAAa;AACd;;;ACbO,IAAM,eAAsC;AAAA,EAClD;AAAA,IACC,IAAI;AAAA,IACJ,OACC;AAAA,IACD,OAAO;AAAA,SACD,IAAG,CAAC,SAAS;AAAA,MAClB,MAAM,SAAS,QAAQ;AAAA,MACvB,MAAM,WAAW,MAAM,qBAAqB;AAAA,MAC5C,MAAM,OAAO,SAAS,QAAQ;AAAA,MAC9B,MAAM,QAAQ,MAAM,UACnB,QAAQ,OAAO,KAAK,aAAa,GACjC,yBACD;AAAA,MAGA,MACC,iBAAiB,cACjB,kDACD;AAAA,MACA,MAAM,iBAAiB,YAAW,mCAAmC;AAAA,MACrE,MACC,MAAM,SAAS,eACf,2CACD;AAAA,MACA,MACC,MAAM,UAAU,WAChB,qDACD;AAAA,MACA,MACE,MAAM,OAAO,SAAS,MAAO,GAC9B,0CACD;AAAA,MACA,MAAM,iBAAiB,SAAS,sBAAsB;AAAA;AAAA,EAExD;AAAA,EACA;AAAA,IACC,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,OAAO;AAAA,SACD,IAAG,CAAC,SAAS;AAAA,MAClB,MAAM,SAAS,QAAQ;AAAA,MACvB,MAAM,WAAW,MAAM,qBAAqB;AAAA,MAC5C,MAAM,OAAO,SAAS,SAAS;AAAA,MAC/B,MAAM,QAAQ,MAAM,UACnB,QAAQ,OAAO,KAAK,aAAa,GACjC,gBACD;AAAA,MACA,MACC,iBAAiB,cACjB,kDACD;AAAA,MACA,MACC,MAAM,SAAS,gBACf,4CACD;AAAA,MACA,MACC,MAAM,UAAU,WAChB,qDACD;AAAA,MACA,MACE,MAAM,OAAO,SAAS,MAAO,GAC9B,yCACD;AAAA;AAAA,EAEF;AAAA,EACA;AAAA,IACC,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,OAAO;AAAA,SACD,IAAG,CAAC,SAAS;AAAA,MAClB,MAAM,SAAS,QAAQ;AAAA,MACvB,MAAM,WAAW,MAAM,qBAAqB;AAAA,MAC5C,MAAM,OAAO,SAAS,QAAQ;AAAA,MAC9B,MAAM,UACL,QAAQ,OAAO,KAAK,aAAa,GACjC,yBACD;AAAA,MACA,MAAM,QAAQ,OAAO,KAAK,aAAa;AAAA,MACvC,OACE,MAAM,QAAQ,UAAU,GAAG,WAAW,GACvC,4CACD;AAAA;AAAA,EAEF;AACD;;;ACrFO,IAAM,YAAmC;AAAA,EAC/C;AAAA,IACC,IAAI;AAAA,IACJ,OAAO;AAAA,SACD,IAAG,GAAG,UAAU;AAAA,MACrB,MAAM,OAAO,MAAM,OAAO,KAAK,aAAa;AAAA,MAC5C,MACC,OAAO,SAAS,YAAY,SAAS,QAAQ,eAAe,MAC5D,8CACD;AAAA,MACA,MACC,KAAK,cAAc,QACjB,OAAO,KAAK,cAAc,YAAY,KAAK,cAAc,IAC3D,8CACD;AAAA;AAAA,EAEF;AAAA,EACA;AAAA,IACC,IAAI;AAAA,IACJ,OACC;AAAA,SACK,IAAG,CAAC,SAAS;AAAA,MAClB,MAAM,QAAQ,OAAO,KAAK,aAAa;AAAA,MACvC,MAAM,YAAY,MAAM,QAAQ,UAAU;AAAA,MAC1C,MACC,UAAU,WAAW,GACrB,qCAAqC,UAAU,QAChD;AAAA,MACA,OAAO,QAAQ;AAAA,MACf,MACC,MAAM,YAAY,cAAc,SAChC,uCACD;AAAA,MACA,MACC,MAAM,SAAS,cAAc,MAC7B,yCACD;AAAA,MACA,MACC,MAAM,SAAS,cAAc,MAC7B,yCACD;AAAA;AAAA,EAEF;AAAA,EACA;AAAA,IACC,IAAI;AAAA,IACJ,OACC;AAAA,SACK,IAAG,CAAC,SAAS;AAAA,MAClB,MAAM,QAAQ,OAAO,KAAK;AAAA,WACtB;AAAA,QACH,IAAI;AAAA,UACH;AAAA,UACA,EAAE,MAAM,gBAAgB,SAAS,qBAAqB;AAAA,QACvD;AAAA,MACD,CAAC;AAAA,MACD,OAAO,QAAQ,MAAM,QAAQ,UAAU;AAAA,MACvC,MACC,KAAK,MAAM,IAAI,CAAC,oBAAoB,oBAAoB,CAAC,GACzD,sDACD;AAAA;AAAA,EAEF;AAAA,EACA;AAAA,IACC,IAAI;AAAA,IACJ,OAAO;AAAA,SACD,IAAG,CAAC,SAAS;AAAA,MAGlB,MAAM,QAAQ,OAAO,KAAK;AAAA,WACtB;AAAA,QACH,IAAI;AAAA,UACH,MAAM;AAAA,UACN,SAAS;AAAA,QACV;AAAA,MACD,CAAC;AAAA,MACD,OAAO,QAAQ,MAAM,QAAQ,UAAU;AAAA,MACvC,MACC,KAAK,MAAM,IAAI,CAAC,kBAAkB,CAAC,GACnC,uCACD;AAAA;AAAA,EAEF;AAAA,EACA;AAAA,IACC,IAAI;AAAA,IACJ,OACC;AAAA,SACK,IAAG,CAAC,SAAS;AAAA,MAClB,MAAM,QAAQ,OAAO,KAAK;AAAA,WACtB;AAAA,QACH,aAAa,CAAC,gBAAgB;AAAA,MAC/B,CAAC;AAAA,MACD,OAAO,QAAQ,MAAM,QAAQ,UAAU;AAAA,MACvC,MACC,SAAS,WACT,kDACD;AAAA,MACA,MACC,KAAK,gBAAgB,WACrB,iIACD;AAAA,MACA,MACC,KAAK,YAAY,WAAW,GAC5B,wCAAwC,KAAK,YAAY,QAC1D;AAAA,MACA,OAAO,QAAQ,KAAK;AAAA,MACpB,MACC,MAAM,aAAa,iBAAiB,UACpC,qDACD;AAAA,MAEA,MACC,KAAK,YAAY,YAAY,MAAM,iBAAiB,aACpD,wDACD;AAAA,MACA,MACC,KAAK,mBAAmB,cACvB,KAAK,CAAC,GAAG,KAAK,OAAO,GAAG,CAAC,GAAG,iBAAiB,OAAO,CAAC,GACtD,gDACD;AAAA,MACA,MACC,KAAK,SAAS,cAAc,QAAQ,KAAK,SAAS,cAAc,MAChE,sEACD;AAAA;AAAA,EAEF;AAAA,EACA;AAAA,IACC,IAAI;AAAA,IACJ,OACC;AAAA,SACK,IAAG,CAAC,SAAS;AAAA,MAClB,MAAM,QAAQ,MAAM,UACnB,QAAQ,OAAO,KAAK,KAAK,eAAe,IAAI,CAAC,EAAE,CAAC,GAChD,0BACD;AAAA,MACA,MACC,iBAAiB,cACjB,iDACD;AAAA,MACA,MAAM,iBAAiB,SAAS,yBAAyB;AAAA;AAAA,EAE3D;AAAA,EACA;AAAA,IACC,IAAI;AAAA,IACJ,OACC;AAAA,SACK,IAAG,CAAC,SAAS;AAAA,MAClB,MAAM,QAAQ,MAAM,UACnB,QAAQ,OAAO,KAAK;AAAA,WAChB;AAAA,QACH,SAAS;AAAA;AAAA,MACV,CAAC,GACD,yCACD;AAAA,MACA,MACC,iBAAiB,cACjB,oDACD;AAAA,MACA,MAAM,iBAAiB,SAAS,yBAAyB;AAAA;AAAA,EAE3D;AAAA,EACA;AAAA,IACC,IAAI;AAAA,IACJ,OACC;AAAA,SACK,IAAG,CAAC,SAAS;AAAA,MAGlB,MAAM,QAAQ,MAAM,UACnB,QAAQ,OAAO,KAAK;AAAA,WAChB;AAAA,QAEH,SAAS,EAAE,KAAK,mBAAmB;AAAA,MACpC,CAAC,GACD,0BACD;AAAA,MACA,MACC,iBAAiB,cACjB,qCACD;AAAA,MACA,MACC,CAAC,MAAM,QAAQ,SAAS,kBAAkB,GAC1C,6CACD;AAAA,MACA,MAAM,iBAAiB,SAAS,yBAAyB;AAAA;AAAA,EAE3D;AAAA,EACA;AAAA,IACC,IAAI;AAAA,IACJ,OACC;AAAA,SACK,IAAG,CAAC,SAAS;AAAA,MAClB,MAAM,QAAQ,MAAM,UACnB,QAAQ,OAAO,KAAK;AAAA,WAChB;AAAA,QACH,aAAa;AAAA,UACZ,KAAK,kBAAkB,UAAU,4BAA4B;AAAA,QAC9D;AAAA,MACD,CAAC,GACD,6CACD;AAAA,MACA,MACC,iBAAiB,cACjB,wDACD;AAAA,MACA,MACC,CAAC,MAAM,QAAQ,SAAS,aAAa,GACrC,6CACD;AAAA,MACA,MAAM,iBAAiB,SAAS,yBAAyB;AAAA;AAAA,EAE3D;AAAA,EACA;AAAA,IACC,IAAI;AAAA,IACJ,OAAO;AAAA,SACD,IAAG,GAAG,UAAU;AAAA,MACrB,MAAM,QAAQ,MAAM,UACnB,OAAO,KAAK,KAAK,eAAe,IAAI,sBAAsB,CAAC,GAC3D,4CACD;AAAA,MACA,MACC,iBAAiB,cACjB,4CACD;AAAA,MACA,MACC,CAAC,MAAM,QAAQ,SAAS,qBAAqB,GAC7C,6CACD;AAAA;AAAA,EAEF;AACD;;;ACnOO,IAAM,iBAAwC;AAAA,EACpD,GAAG;AAAA,EACH,GAAG;AACJ;;ACPO,IAAM,sBAAsB;AAAA,EAClC,QACC;AACF;AAMA,eAAsB,aAAa,CAClC,YACA,SACoE;AAAA,EACpE,MAAM,SAAS,MAAM,QAAQ,KAAK;AAAA,EAClC,IAAI;AAAA,EACJ,IAAI;AAAA,IACH,IAAI,WAAW,UAAU,YAAY,OAAO,WAAW,WAAW;AAAA,MACjE,UAAU,EAAE,SAAS,oBAAoB,OAAO;AAAA,IACjD,EAAO;AAAA,MACN,MAAM,WAAW,IAAI;AAAA,QACpB,QAAQ,OAAO;AAAA,QACf,WAAW,MAAM,OAAO,UAAU;AAAA,QAClC,QAAQ,OAAO,UAAU;AAAA,MAC1B,CAAC;AAAA,MACD,UAAU,EAAE,QAAQ,KAAK;AAAA;AAAA,IAEzB,OAAO,OAAO;AAAA,IAGf,MAAM,OAAO,QAAQ,EAAE,KACtB,MAAG;AAAA,MAAG;AAAA,OACN,MAAG;AAAA,MAAG;AAAA,KACP;AAAA,IACA,MAAM;AAAA;AAAA,EAEP,MAAM,OAAO,QAAQ;AAAA,EACrB,OAAO;AAAA;AAGR,SAAS,YAAY,GAAiB;AAAA,EACrC,QAAQ,UAAU,OAAO;AAAA,EACzB,IAAI,OAAO,aAAa,cAAc,OAAO,OAAO,YAAY;AAAA,IAC/D,MAAM,IAAI,UACT,+FACD;AAAA,EACD;AAAA,EACA,OAAO,EAAE,UAAU,GAAG;AAAA;AAgBhB,SAAS,cAAc,CAAC,SAQtB;AAAA,EACR,MAAM,SAAS,QAAQ,UAAU,aAAa;AAAA,EAC9C,MAAM,OAAO,QAAQ,QAAQ,CAAC;AAAA,EAC9B,WAAW,MAAM,OAAO,KAAK,IAAI,GAAG;AAAA,IACnC,IAAI,CAAC,eAAe,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG;AAAA,MAC7C,MAAM,IAAI,UAAU,uCAAuC,IAAI;AAAA,IAChE;AAAA,EACD;AAAA,EAEA,OAAO,SAAS,GAAG,QAAQ,iCAAiC,MAAM;AAAA,IACjE,WAAW,cAAc,gBAAgB;AAAA,MACxC,MAAM,QAAQ,GAAG,WAAW,OAAO,WAAW;AAAA,MAC9C,MAAM,SACL,KAAK,WAAW,QACf,WAAW,UAAU,YAAY,QAAQ,WAAW,QAClD,oBAAoB,SACpB;AAAA,MACJ,IAAI,WAAW,WAAW;AAAA,QACzB,OAAO,GAAG,KAAK,GAAG,mBAAmB,WAAW,YAAY,EAAE;AAAA,QAC9D;AAAA,MACD;AAAA,MACA,OAAO,GAAG,OAAO,YAAY;AAAA,QAC5B,MAAM,SAAS,MAAM,cAAc,YAAY,QAAQ,OAAO;AAAA,QAC9D,IAAI,aAAa,QAAQ;AAAA,UACxB,MAAM,IAAI,MACT,gBAAgB,WAAW,OAAO,OAAO,sEAC1C;AAAA,QACD;AAAA,OACA;AAAA,IACF;AAAA,GACA;AAAA;;AC/FK,SAAS,sBAAsB,GAAkB;AAAA,EACvD,OAAO;AAAA,SACA,KAAI,GAAG;AAAA,MACZ,MAAM,SAAS,oBAAmB;AAAA,MAClC,OAAO;AAAA,QACN;AAAA,aACM,UAAS,GAAG;AAAA,UACjB,OAAO,OAAO,KAAK,IAAI,CAAC,UAAU;AAAA,YACjC,IAAI,cAAa,IAAI;AAAA,YACrB,SAAS,KAAK;AAAA,YACd,MAAM,KAAK;AAAA,YACX,MAAM,KAAK;AAAA,YACX,aAAa,KAAK,eAAe,CAAC;AAAA,UACnC,EAAE;AAAA;AAAA,QAEH,QAAQ;AAAA,eACD,SAAQ,CAAC,MAAM;AAAA,YACpB,MAAM,QAAQ,IAAI,MAAM,aAAa,MAAM;AAAA,YAC3C,OAAO,SACN,SAAS,WACN,IAAI,aAAY,4CAA4C;AAAA,cAC5D;AAAA,YACD,CAAC,IACA,IAAI,aAAY,2CAA2C;AAAA,cAC3D;AAAA,YACD,CAAC,CACJ;AAAA;AAAA,eAEK,SAAQ,GAAG;AAAA,YAChB,OAAO,OAAO;AAAA;AAAA,QAEhB;AAAA,MACD;AAAA;AAAA,EAEF;AAAA;",
-  "debugId": "D8FC228C191C6BF264756E2164756E21",
+  "mappings": "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",
+  "debugId": "5D29AA162B05B41464756E2164756E21",
   "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,35 @@ import {
   MailFailure2,
   MailRefused2
 } from "./chunks/index-we4n5yfz.js";
+// src/unsubscribe.ts
+var URL_ALLOWED = /^https:\/\/[\x21-\x7E]+$/;
+var URL_REFUSED = /[<>,"`\\{}|^]/;
+var BAD_ESCAPE = /%(?![0-9A-Fa-f]{2})/;
+var MAILTO = /^[A-Za-z0-9._~!$'*+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+$/;
+var fitsTheHeader = (url) => URL_ALLOWED.test(url) && !URL_REFUSED.test(url) && !BAD_ESCAPE.test(url);
+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");
+  }
+  const parsed = URL.canParse(options.url) ? new URL(options.url) : null;
+  if (parsed === null || parsed.username !== "" || parsed.password !== "" || ![options.url, parsed.href].every(fitsTheHeader)) {
+    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": `<${parsed.href}>${mailto}`,
+    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
+  };
+}
 export {
   MailError2 as MailError,
   MailFailure2 as MailFailure,
@@ -20,10 +49,11 @@ export {
   addressOf2 as addressOf,
   checkMessage2 as checkMessage,
   createMemoryMailer2 as createMemoryMailer,
+  listUnsubscribe,
   parseAcceptLanguage2 as parseAcceptLanguage,
   pickLocale2 as pickLocale,
   recipientsOf2 as recipientsOf
 };
 
-//# debugId=F6BB19285305093D64756E2164756E21
+//# debugId=467299297E6B375F64756E2164756E21
 //# 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// A `%` that does not start an escape: no URI parser reads it as intended.\nconst BAD_ESCAPE = /%(?![0-9A-Fa-f]{2})/;\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\nconst fitsTheHeader = (url: string): boolean =>\n\tURL_ALLOWED.test(url) && !URL_REFUSED.test(url) && !BAD_ESCAPE.test(url);\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, holds `<`, `>`, a double quote or a raw `,`,\n * or a `%` that starts no escape — before or after parsing — and a `mailto`\n * that is not a bare ASCII address. The URL is written as a parser reads it\n * (`new URL(url).href`: the host lowered, a `'` in the query as `%27`). It 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\t// The URL as a parser reads it: `https:///host` and an empty `@` are gone,\n\t// the host lowered. The parser also decodes a host's escapes — `a%2Cb`\n\t// comes back as `a,b` — so what is written is checked as well.\n\tconst parsed = URL.canParse(options.url) ? new URL(options.url) : null;\n\tif (\n\t\tparsed === null ||\n\t\t// A user and a password in a header every relay and recipient reads.\n\t\tparsed.username !== '' ||\n\t\tparsed.password !== '' ||\n\t\t![options.url, parsed.href].every(fitsTheHeader)\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': `<${parsed.href}>${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;AAEpB,IAAM,aAAa;AAGnB,IAAM,SAAS;AAEf,IAAM,gBAAgB,CAAC,QACtB,YAAY,KAAK,GAAG,KAAK,CAAC,YAAY,KAAK,GAAG,KAAK,CAAC,WAAW,KAAK,GAAG;AAwBjE,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,EAIA,MAAM,SAAS,IAAI,SAAS,QAAQ,GAAG,IAAI,IAAI,IAAI,QAAQ,GAAG,IAAI;AAAA,EAClE,IACC,WAAW,QAEX,OAAO,aAAa,MACpB,OAAO,aAAa,MACpB,CAAC,CAAC,QAAQ,KAAK,OAAO,IAAI,EAAE,MAAM,aAAa,GAC9C;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,OAAO,QAAQ;AAAA,IACvC,yBAAyB;AAAA,EAC1B;AAAA;",
+  "debugId": "467299297E6B375F64756E2164756E21",
   "names": []
 }

package/dist/unsubscribe.d.ts

@@ -0,0 +1,45 @@
+/** 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, holds `<`, `>`, a double quote or a raw `,`,
+ * or a `%` that starts no escape — before or after parsing — and a `mailto`
+ * that is not a bare ASCII address. The URL is written as a parser reads it
+ * (`new URL(url).href`: the host lowered, a `'` in the query as `%27`). It 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;AAkBF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,sBAAsB,GAC7B,sBAAsB,CAsCxB"}

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/rendering.md

@@ -168,8 +168,9 @@ mails.render('sign-in-code', { code: 123456 }, { locale: 'fr' });
 
 After each `maizzle build`, `@nxgt/mail-i18n` writes `generated/mail.ts` in
 the project: `MailEmails`, each e-mail of the build with the variables it
-takes. Commit it, so the code that sends type-checks without running a build,
-and pass it to `createMailRenderer`:
+takes. Git-ignore it — each build rewrites it — and run `maizzle build`
+before type-checking, as `"typecheck": "maizzle build && tsc --noEmit"`
+does; then pass it to `createMailRenderer`:
 
 ```ts
 // generated/mail.ts — written by the build, never edited
@@ -251,7 +252,8 @@ so a helper written for any build takes a typed renderer.
 
 The manifest guide also shows
 [a test that holds the two sides together](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-i18n/docs/guide/manifest.md#checking-your-application-against-it),
-for a project that does not commit `generated/mail.ts`.
+for an application that only installs the built project, or is not
+written in TypeScript.
 
 ## Choosing the locale
 

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,217 @@ 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, and the URL is written as a parser reads it —
+`new URL(url).href`: the host lowered, `https:///host` or an empty `@`
+dropped, and any character a query cannot hold as is percent-encoded
+(a `'` in the query becomes `%27`). A host's escapes are decoded, so the URL
+written is checked as well: `https://a%2Cb.test/` is refused. 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, `|`, `^`, a raw `,`, or a `%` that starts no escape | `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 +625,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/guide/transports.md

@@ -224,9 +224,11 @@ choose to show it. `@nxgt/mail-resend` sends it as Resend's `Idempotency-Key`;
 Document which one yours does, and for how long the provider remembers a key:
 past that window, a retry delivers again.
 
-The conformance suite has no case for it — a transport that ignores the key
-is as correct as one that honours it. Test it in your own specs: the key
-reaches the provider where it should, and nowhere else.
+The conformance suite checks what both kinds share, in `send.idempotencyKey`:
+a message with a key is delivered, and the key is in none of its recipients,
+subject, HTML or text. The suite reads back no header and no provider request,
+so where the key goes is yours to test, as is whether a retry is
+deduplicated: the key reaches the provider where it should, and nowhere else.
 
 ```ts
 import { expect, test } from 'bun:test';
@@ -298,6 +300,7 @@ and when `skip` names a case that does not exist
 | `send.recipients` | every recipient is delivered to, written as a string or with a name | no |
 | `send.hostileName` | a name holding `<…>`, a comma and quotes — `Ada <mallory@example.test>, "Eve" <eve@example.test>;` — reaches only its own address: quoting the name is the transport's job | no |
 | `send.attachment` | an attachment — `sampleAttachment`, every byte from 0 to 255 named `reçu n° 42.pdf`, `application/pdf` — is delivered byte for byte, with its file name and its type (compared without case), and the parts beside it as sent | no |
+| `send.idempotencyKey` | a message with an `idempotencyKey` is delivered — never refused for it — and the key appears in none of its recipients, its subject, its HTML or its text. A fresh key per run, so a harness that remembers keys still delivers | no |
 | `send.refusesNoRecipient` | no recipient throws `MailRefused`, and nothing is delivered | no |
 | `send.refusesLineBreakInSubject` | a line break in the subject throws `MailRefused`, and nothing is delivered | no |
 | `send.refusesAddressHeader` | a `Bcc` among the custom headers throws `MailRefused` without the address in its message, and nothing is delivered: it would add a recipient no check saw | no |
@@ -442,7 +445,7 @@ export function fakeProvider() {
 ```
 
 With the transport and the fake above, the example at the top of this page
-passes all thirteen cases.
+passes all fourteen cases.
 
 ### Without faults
 

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.
+- **The conformance suite checks the idempotency key** — a fourteenth case,
+  `send.idempotencyKey`: a message with a key is delivered, never refused
+  for it, and the key is written nowhere in the e-mail. Built, not yet
+  published.
+- **`listUnsubscribe` writes the URL a parser reads** — `new URL(url).href`,
+  so the value written is the value checked, and a `%` that starts no escape
+  is refused. Built, not yet published.
 
 ## Next
 
@@ -71,6 +69,21 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **One-click unsubscribe, v0.4.0** — `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 an ASCII `https://` URL, 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.
+- **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
@@ -118,15 +131,3 @@ before is in the [CHANGELOG](../CHANGELOG.md).
   local server answering as Resend does — and throwing `@nxgt/mail`'s errors.
   See [the SMTP roadmap](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-smtp/docs/roadmap.md)
   and [the Resend roadmap](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-resend/docs/roadmap.md).
-- **The Maizzle side, `@nxgt/mail-config`, `@nxgt/mail-i18n`, `@nxgt/mail-ui`
-  and `@nxgt/mail-presets` v0.1.0** — packages for a normal Maizzle 6 project:
-  `defineMailConfig({ plugins })` with every plugin's build hooks chained;
-  one template per e-mail, its text keys into ICU catalogues checked at build
-  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)
@@ -329,7 +338,7 @@ that `generated/mail.ts` describes them, then fix the calls `tsc` still
 reports:
 
 ```sh
-bunx maizzle build   # rewrites dist/ and generated/mail.ts; commit the new generated/mail.ts
+bunx maizzle build   # rewrites dist/ and generated/mail.ts, both git-ignored
 ```
 
 Never edit `generated/mail.ts` by hand to silence the error: the next build
@@ -341,14 +350,17 @@ rewrites it, and the deployed build is what `render` checks at run time.
 fresh clone or a new project.
 **Why:** `generated/mail.ts` is written by `@nxgt/mail-i18n` at the end of
 `maizzle build`, in the Maizzle project, unless its `rendererTypes` option
-moved it or turned it off (`false`). It is not there until the first build,
-or it was not committed, or the import points at another folder.
-**Fix:** build once and commit the file, so the code that sends type-checks
-without a build; import it from where `rendererTypes` writes it:
+moved it or turned it off (`false`). It is git-ignored, as `dist/` is, so it
+is not there until the first build — or the import points at another folder.
+**Fix:** build before type-checking, in the script CI runs too, and import it
+from where `rendererTypes` writes it:
 
-```sh
-bunx maizzle build
-git add generated/mail.ts
+```json
+{
+  "scripts": {
+    "typecheck": "maizzle build && tsc --noEmit"
+  }
+}
 ```
 
 To go without it, leave the type parameter out:
@@ -869,6 +881,166 @@ 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, `|`, `^`, a `,` as it is, or a `%` that starts no
+escape (`%`, `%zz`) — or an escape in the host that the parser decodes into
+one of those (`https://a%2Cb.test/`): 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`
@@ -1632,6 +1804,8 @@ test title:
 | `conformance: a Bcc header must throw MailRefused` | `send.refusesAddressHeader` | call `checkMessage`, from a version of `@nxgt/mail` that refuses reserved headers |
 | `conformance: an attachment named with a path must throw MailRefused` | `send.refusesAttachmentPath` | call `checkMessage`, from a version of `@nxgt/mail` that checks attachments (0.2 on) |
 | `conformance: the refusal message holds the refused value` | `send.refusesWithoutTheValue`, `send.refusesAddressHeader`, `send.refusesAttachmentPath` | name where the problem is, never the value |
+| `conformance: a send with an idempotency key did not answer SentMail` | `send.idempotencyKey` | accept the key, and resolve as for any message: a provider that cannot deduplicate is no reason to refuse |
+| `conformance: the idempotency key was written into the e-mail` | `send.idempotencyKey` | the recipients, subject, HTML or text read back hold the key: keep it out of what builds the e-mail, and send it as the provider's header (Resend's `Idempotency-Key`), or leave it out |
 | `conformance: the message with an attachment was not delivered` | `send.attachment` | a message with attachments is a message: deliver it |
 | `conformance: the attachment was not delivered with its file name` | `send.attachment` | pass the name as is; the name `reçu n° 42.pdf` needs RFC 2231 encoding in a raw header — nodemailer and a JSON API do it for you |
 | `conformance: the attachment was not delivered with its content type` | `send.attachment` | pass `contentType` through; do not guess it from the name |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/mail",
-	"version": "0.3.0",
+	"version": "0.5.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",