@nxgt/mail 0.2.0 → 0.4.0

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, 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';
@@ -75,6 +75,7 @@ interface MailMessage extends Rendered {
 	readonly replyTo?: Address;
 	readonly headers?: Readonly<Record<string, string>>;
 	readonly attachments?: readonly MailAttachment[];
+	readonly idempotencyKey?: string;
 }
 
 interface MailAttachment {
@@ -92,8 +93,9 @@ 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 |
 
 `Rendered` is what the renderer answers — `mails.render('verify-email', { name, link })`
 fills the values only known at send time into a built Maizzle template — and a
@@ -209,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` |
@@ -223,6 +226,213 @@ const message: MailMessage = {
 | `{ Bcc: 'eve@example.com' }` | `MailRefused`: `send: header Bcc is reserved — addresses, the subject and the MIME structure are never custom headers` |
 | `{ 'content-type': 'text/plain' }` | `MailRefused`: `send: header content-type is reserved — …` |
 
+## One-click unsubscribe
+
+`listUnsubscribe` answers the two headers that give an e-mail the
+"Unsubscribe" button Gmail and Yahoo show next to the sender (RFC 8058, with
+RFC 2369's `List-Unsubscribe`), to spread into `headers`:
+
+```ts
+import { listUnsubscribe } from '@nxgt/mail';
+
+listUnsubscribe({ url: 'https://example.com/unsubscribe?token=s3cr3t' });
+// {
+//   'List-Unsubscribe': '<https://example.com/unsubscribe?token=s3cr3t>',
+//   'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
+// }
+
+listUnsubscribe({ url: 'https://example.com/unsubscribe?token=s3cr3t', mailto: 'unsubscribe@example.com' });
+// 'List-Unsubscribe': '<https://example.com/unsubscribe?token=s3cr3t>, <mailto:unsubscribe@example.com>'
+```
+
+```ts
+interface ListUnsubscribeOptions {
+	readonly url: string;
+	readonly mailto?: string;
+}
+
+// A type, not an interface, so it goes into `headers` as it is.
+type ListUnsubscribeHeaders = {
+	readonly 'List-Unsubscribe': string;
+	readonly 'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click';
+};
+
+function listUnsubscribe(options: ListUnsubscribeOptions): ListUnsubscribeHeaders;
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `url` | `string` | required | The `https:` URL a mail client POSTs `List-Unsubscribe=One-Click` to. One per recipient, carrying what identifies them — `https://example.com/unsubscribe?token=…`. Written first in `List-Unsubscribe` |
+| `mailto` | `string` | none | A bare address that unsubscribes whoever writes to it, for clients that only send mail. Written after the URL as `<mailto:…>` |
+
+The headers travel as any other: `checkMessage` accepts them, and every
+transport sends them unchanged. Spread them into `headers` — alone, as
+`headers: { ...listUnsubscribe({ url }) }`, or beside headers of your own:
+
+```ts
+import { listUnsubscribe, type MailMessage, type Rendered } from '@nxgt/mail';
+
+declare const rendered: Rendered;
+declare const token: string;
+
+const message: MailMessage = {
+	...rendered,
+	to: 'ada@example.com',
+	headers: {
+		...listUnsubscribe({ url: `https://example.com/unsubscribe?token=${encodeURIComponent(token)}` }),
+		'X-Entity-Ref-ID': 'newsletter-2026-09',
+	},
+};
+```
+
+### What Gmail and Yahoo require
+
+Since 2024, a sender of bulk mail to Gmail or Yahoo addresses must, on
+marketing and subscribed mail:
+
+- carry **both** headers, `List-Unsubscribe` with an `https:` URL and
+  `List-Unsubscribe-Post: List-Unsubscribe=One-Click`;
+- have them covered by a **DKIM signature** of the sending domain, so nobody
+  can add or change them on the way;
+- honour the unsubscribe promptly — within two days.
+
+The DKIM signature is the sender's, not this package's: `listUnsubscribe`
+writes the headers, and whatever signs the message must include them.
+
+| Transport | Who signs |
+| --- | --- |
+| `@nxgt/mail-resend` | Resend, with the DKIM key of your verified domain. Check that its `h=` names both headers in a received message's `DKIM-Signature` |
+| `@nxgt/mail-smtp` | Your relay, or nodemailer's own `dkim` option on the transporter you create. A relay that does not DKIM-sign leaves the headers unsigned, and the message fails the requirement |
+
+### Which e-mails carry it
+
+**Marketing and bulk mail** — a newsletter, a digest, a product announcement,
+anything the recipient subscribed to and can stop receiving.
+
+**Not transactional mail** — a password reset, a sign-in code, an e-mail
+verification, a receipt, a security alert. The recipient cannot opt out of
+those, and an "Unsubscribe" button next to a sign-in code invites them to
+try. Leave `headers` without it.
+
+### The endpoint
+
+The URL is yours. It must:
+
+- **unsubscribe on a `POST`** whose form body is `List-Unsubscribe=One-Click`
+  — sent as `application/x-www-form-urlencoded` or `multipart/form-data`,
+  which `request.formData()` both reads;
+- do it **with no login, no confirmation page and no redirect**, from the
+  URL alone — the mail client sends no cookie, so the endpoint takes no CSRF
+  token either — and answer **2xx**;
+- on a **`GET`** — the same URL in the body of the e-mail, clicked by a
+  person — **show a page, never unsubscribe**: link scanners and previews
+  fetch every URL in an e-mail. The page's button can post the same form.
+
+```ts
+// Yours: the token store.
+declare function unsubscribeByToken(token: string): Promise<boolean>; // false: unknown token
+
+export async function unsubscribeHandler(request: Request): Promise<Response> {
+	const token = new URL(request.url).searchParams.get('token') ?? '';
+
+	if (request.method === 'POST') {
+		const form = await request.formData();
+		if (form.get('List-Unsubscribe') !== 'One-Click') return new Response(null, { status: 400 });
+		await unsubscribeByToken(token); // an unknown token answers 200 too: nothing to tell a mail client
+		return new Response(null, { status: 200 });
+	}
+
+	// GET: a person followed the link in the e-mail. Show, do not act.
+	const page = `<!doctype html><title>Unsubscribe</title>
+<form method="post"><input type="hidden" name="List-Unsubscribe" value="One-Click">
+<button>Unsubscribe</button></form>`;
+	return new Response(page, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+}
+```
+
+The form posts to its own URL, token included, so the page and the mail
+client take the same path. In a framework, mount it at the URL you pass:
+with Hono, `app.on(['GET', 'POST'], '/unsubscribe', (c) => unsubscribeHandler(c.req.raw))`.
+
+### The token is a credential
+
+Anyone holding the URL can unsubscribe that recipient. Make the token
+unguessable (random, or signed), keep it valid for as long as the e-mail may
+be read, and **never log it** — nor the URL that carries it, nor the query
+string of the endpoint's access log. `listUnsubscribe` does its part: a
+refused `url` is reported by the rule it broke, never quoted.
+
+### Commas must be percent-encoded
+
+`List-Unsubscribe` is a comma-separated list of URLs: a raw `,` in the URL
+would start a second one, so it is refused. `encodeURIComponent` and
+`URLSearchParams` both write `%2C`; a URL built with `URL` is passed as
+`url.href` — a `URL` object is a compile error:
+
+```ts
+import { listUnsubscribe } from '@nxgt/mail';
+
+declare const token: string;
+
+const url = new URL('https://example.com/unsubscribe');
+url.searchParams.set('token', token);
+url.searchParams.set('lists', 'news,offers'); // written lists=news%2Coffers
+
+listUnsubscribe({ url: url.href });
+```
+
+### Refusals
+
+The URL and the address are checked when the headers are built, before
+anything is sent. A `MailRefused` names the rule, never the value:
+
+| Written | Answer |
+| --- | --- |
+| `url: 'https://example.com/u?token=…'`, `'https://example.com:8443/u?list=a%2Cb'` | accepted |
+| `url: 'http://example.com/u'`, `'mailto:u@example.com'`, `'/unsubscribe'`, `''`, `'https://user:pass@example.com/u'`, `'https://exämple.com/u'` | `MailRefused`: `listUnsubscribe: url must be an https:// URL in printable ASCII, without credentials, <, >, quotes or a raw comma` |
+| a `url` holding a space, a tab, a line break, a character outside ASCII, `<`, `>`, a double quote, a backtick, a backslash, a brace, `|`, `^` or a raw `,` | `MailRefused`: the same message |
+| `mailto: 'Unsub <u@example.com>'`, `'u@example.com, v@example.com'`, `'unsubscribe'`, `'mailto:u@example.com'`, `'u@example.com?subject=x'`, `'ü@example.com'` | `MailRefused`: `listUnsubscribe: mailto must be a bare e-mail address, as unsubscribe@example.com` |
+| `listUnsubscribe(null)` | `TypeError`: `listUnsubscribe: options must be an object, as { url }` |
+| `url: new URL(…)` | a compile error; at run time `TypeError`: `listUnsubscribe: url must be a string` |
+| `mailto: 42` | a compile error; at run time `TypeError`: `listUnsubscribe: mailto must be a string` |
+
+A `TypeError` is a mistake in the code, not in the data: no request handler
+should answer one. A `MailRefused` usually means a URL built from a value that
+was not encoded — keep the call inside the `try` that handles `MailError`.
+
+### A realistic case — a newsletter, one URL per subscriber
+
+```ts
+import { listUnsubscribe, MailError, type Mailer } from '@nxgt/mail';
+import { createMailRenderer } from '@nxgt/mail/renderer';
+
+// Yours: the subscriber store.
+declare function subscribersOf(list: string): AsyncIterable<{ id: string; email: string; name: string; token: string }>;
+
+const mails = createMailRenderer({ dir: 'dist' });
+
+export async function sendIssue(mailer: Mailer, issue: string): Promise<{ sent: number; failed: string[] }> {
+	let sent = 0;
+	const failed: string[] = [];
+	for await (const subscriber of subscribersOf('news')) {
+		const unsubscribe = `https://example.com/unsubscribe?token=${encodeURIComponent(subscriber.token)}`;
+		try {
+			await mailer.send({
+				to: subscriber.email,
+				...mails.render('newsletter', { name: subscriber.name, unsubscribe }), // the link in the body
+				headers: { ...listUnsubscribe({ url: unsubscribe }) }, // the button in the mail client
+				idempotencyKey: `newsletter-${issue}/${subscriber.id}`,
+			});
+			sent += 1;
+		} catch (error) {
+			if (!(error instanceof MailError)) throw error;
+			failed.push(subscriber.id); // an id, never the address or the token
+		}
+	}
+	return { sent, failed };
+}
+```
+
 ## Attachments
 
 An attachment is a file's **bytes**, its name and its type:
@@ -302,6 +512,91 @@ carry — is a `MailRefused` from the transport (an SMTP `552`; a Resend `400`,
 `413` or `422`), and sending it again unchanged fails again: send a link
 instead.
 
+## Idempotency — sending once
+
+A send that fails with `MailFailure` may still have reached the provider: a
+timeout, a dropped connection. Retrying it can deliver the e-mail twice.
+`idempotencyKey` names the send, so a transport that can deduplicate delivers
+it once however often it is sent:
+
+```ts
+import type { Mailer, Rendered } from '@nxgt/mail';
+
+export async function sendReceipt(mailer: Mailer, order: { id: string; email: string }, rendered: Rendered): Promise<void> {
+	await mailer.send({
+		...rendered,
+		to: order.email,
+		idempotencyKey: `order-${order.id}/receipt`, // the same for every retry of this receipt
+	});
+}
+```
+
+**Derive the key from what the e-mail is about** — an order id, a user id
+and a purpose (`user-7/welcome`, `invitation-19`) — **never from the time or
+a random value**: a retry would carry a new key, and deliver again. **A key
+names one e-mail**: two different e-mails about the same thing need two keys
+(`order-42/receipt`, `order-42/shipped`) — a transport that deduplicates
+refuses a different message under a key it already delivered.
+
+```ts
+declare const order: { id: string };
+declare const userId: string;
+declare const resetRequestId: string;
+
+const receipt = `order-${order.id}/receipt`; // one receipt per order
+const welcome = `user-${userId}/welcome`; // one welcome per user
+const reset = `password-reset/${resetRequestId}`; // per request, not per user: a second request is a second e-mail
+
+const wrong = `receipt-${Date.now()}`; // a retry gets a new key, and delivers again
+const wrongToo = crypto.randomUUID(); // the same
+```
+
+**What each transport does with it:**
+
+| Transport | Effect |
+| --- | --- |
+| `createMemoryMailer()` | The same message under a key it already delivered answers that delivery's `messageId`, and delivers nothing more; a different message under that key is a `MailRefused`. A send that failed leaves its key free. See [Testing — idempotency](testing.md#idempotencykey--a-retry-delivers-once) |
+| `@nxgt/mail-resend` | Sent as Resend's `Idempotency-Key` header. Resend keeps a key for 24 hours: a retry within them answers the first send's id and delivers nothing more; the same key with a different message is refused (`MailRefused`) |
+| `@nxgt/mail-smtp` | Ignored: SMTP has no such mechanism, so a message sent twice is delivered twice |
+
+A transport that cannot deduplicate ignores the key; it never refuses the
+message for carrying one. So a key is always safe to set, and only makes a
+retry safe where the transport honours it. It is never written into the
+e-mail itself.
+
+`checkMessage` refuses a key that is not 1 to 256 visible ASCII characters —
+empty, too long, holding a space, a line break or an accented letter, or not
+a string — without quoting it:
+
+| Written | Answer |
+| --- | --- |
+| `'order-42/receipt'`, `'a:b_c.d~e'`, `'k'.repeat(256)` | accepted |
+| `''`, `'k'.repeat(257)`, `'order 42'`, `'commande-42-reçu'`, `'order-42\r\nX-Evil: 1'`, `42` | `MailRefused`: `send: idempotencyKey must be 1 to 256 visible ASCII characters, as order-42/receipt` |
+
+A transport that deduplicates also refuses **a different message** under a
+key it already delivered, with `MailRefused` — the memory mailer with
+`send: idempotencyKey was already used for a different message — a key names one e-mail`,
+Resend's transport with `send: Resend refused the message` on its `409`.
+Sending it again fails again: give that e-mail its own key.
+
+A retry from a queue, with the key the job carries:
+
+```ts
+import { MailFailure, type Mailer, type MailMessage } from '@nxgt/mail';
+
+// Yours: the queue that runs a job again later.
+declare function retryLater(job: { message: MailMessage }, delaySeconds: number): Promise<void>;
+
+export async function runSendJob(mailer: Mailer, job: { message: MailMessage }): Promise<void> {
+	try {
+		await mailer.send(job.message); // job.message.idempotencyKey was set when the job was queued
+	} catch (error) {
+		if (error instanceof MailFailure) return retryLater(job, 60); // the same key: delivered once, where the transport deduplicates
+		throw error; // MailRefused: sending it again fails again
+	}
+}
+```
+
 ## Errors
 
 ```ts
@@ -325,8 +620,8 @@ 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. 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, or the provider answering that the message is malformed or too large | Fails again, unchanged |
+| `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, 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/testing.md

@@ -143,18 +143,105 @@ await mailer
 mailer.attempts; // 0 — and the failure is still queued for the next well-formed send
 ```
 
+## `idempotencyKey` — a retry delivers once
+
+The memory mailer honours a message's
+[`idempotencyKey`](sending.md#idempotency--sending-once) as Resend does:
+
+- the **same message** under a key it already delivered answers that
+  delivery's `messageId`, and nothing more reaches `sent`;
+- a **different message** under that key — another subject, another
+  recipient, other attachment bytes, any field — is refused with
+  `MailRefused`: `send: idempotencyKey was already used for a different message — a key names one e-mail`,
+  as Resend answers `409 invalid_idempotent_request`;
+- a send that **failed** delivered nothing, so its key stays free, and the
+  retry delivers;
+- each send still counts in `attempts`, the answered duplicate and the
+  refused reuse included: both reached the hand-over;
+- `clear()` forgets the keys.
+
+A test proving that a job run twice e-mails once:
+
+```ts
+import { expect, it } from 'bun:test';
+import { createMemoryMailer, type Mailer, MailRefused } from '@nxgt/mail';
+
+// The code under test: a job that may run more than once for the same order.
+async function sendReceipt(mailer: Mailer, orderId: string): Promise<string | null> {
+	const { messageId } = await mailer.send({
+		to: 'ada@example.com',
+		subject: 'Your receipt',
+		html: '<p>Thank you for your order.</p>',
+		text: 'Thank you for your order.',
+		idempotencyKey: `order-${orderId}/receipt`,
+	});
+	return messageId;
+}
+
+it('sends one receipt, however often the job runs', async () => {
+	const mailer = createMemoryMailer();
+
+	const first = await sendReceipt(mailer, '42');
+	const again = await sendReceipt(mailer, '42');
+
+	expect(again).toBe(first); // 'memory-1', both times
+	expect(mailer.sent).toHaveLength(1);
+	expect(mailer.attempts).toBe(2);
+});
+
+it('refuses another e-mail under the same key', async () => {
+	const mailer = createMemoryMailer();
+	await sendReceipt(mailer, '42');
+
+	const error = await mailer
+		.send({
+			to: 'ada@example.com',
+			subject: 'Your order has shipped', // another e-mail, the receipt's key
+			html: '<p>Your order has shipped.</p>',
+			text: 'Your order has shipped.',
+			idempotencyKey: 'order-42/receipt',
+		})
+		.then(() => null, (e: unknown) => e);
+
+	expect(error).toBeInstanceOf(MailRefused); // give it its own key: order-42/shipped
+	expect(mailer.sent).toHaveLength(1);
+});
+
+it('delivers the retry of a send that failed', async () => {
+	const mailer = createMemoryMailer();
+	mailer.failNext();
+
+	await sendReceipt(mailer, '42').then(() => null, (e: unknown) => e); // MailFailure
+	await sendReceipt(mailer, '42');
+
+	expect(mailer.sent).toHaveLength(1);
+	expect(mailer.sent[0]?.idempotencyKey).toBe('order-42/receipt');
+});
+```
+
+"The same message" is what it would deliver: every field of `MailMessage`,
+read by name, the attachments by their bytes. How the object was written
+does not count — the order of its fields or of its headers, `to` as one
+address or a list of one, no `headers` or `attachments` or an empty one,
+the bytes in a `Buffer` or a plain `Uint8Array` — and neither does a field
+`MailMessage` does not have. SMTP ignores
+the key altogether, so this is the behaviour of a deduplicating transport,
+not of every one. A queued `failNext` fails the next send even when its key
+was already delivered.
+
 ## `clear()`
 
-Forgets the outbox, the attempts, and any queued failure. The id counter keeps
-going, so an id is never reused within one mailer.
+Forgets the outbox, the attempts, any queued failure, and the idempotency
+keys. The id counter keeps going, so an id is never reused within one mailer.
 
 ## What it refuses
 
 Exactly what every transport refuses, because it calls
 [`checkMessage`](transports.md#checkmessage-first) first: no recipient, something
 that is not an address, a line break in a name, the subject or a header, a
-missing part, an attachment that is not bytes, or whose file name or type is
-malformed. A test that passes against the memory mailer does not pass by
+missing part, an attachment that is not bytes or whose file name or type is
+malformed, or an idempotency key that is not 1 to 256 visible ASCII
+characters. A test that passes against the memory mailer does not pass by
 accident a message a real transport would refuse. The full list is in
 [Sending](sending.md#addresses) and
 [Sending — attachments](sending.md#attachments).

package/docs/guide/transports.md

@@ -54,9 +54,12 @@ A transport:
    type — base64 in a JSON body, a MIME part over SMTP, the name encoded when
    it is not ASCII — and **never reads a file or fetches a URL** to attach
    one: `MailAttachment` holds bytes only;
-7. **never retries in secret**, never resolves `false`, never logs and
+7. **uses `idempotencyKey` if the provider deduplicates, and ignores it
+   otherwise** — see [The idempotency key](#the-idempotency-key). It never
+   refuses a message for carrying one, and never writes it into the e-mail;
+8. **never retries in secret**, never resolves `false`, never logs and
    resolves;
-8. **defines no error class of its own**. It throws the classes imported from
+9. **defines no error class of its own**. It throws the classes imported from
    `@nxgt/mail`, declared as a required peer, so `error instanceof MailFailure`
    holds in the application whichever transport threw it. `MailError` is
    abstract, so a bare one cannot be thrown:
@@ -64,14 +67,15 @@ A transport:
 ```json
 {
 	"peerDependencies": {
-		"@nxgt/mail": "^0.2.0"
+		"@nxgt/mail": "^0.3.0"
 	}
 }
 ```
 
-On `0.x`, a caret covers one minor: `^0.2.0` is `>=0.2.0 <0.3.0`. Declare the
+On `0.x`, a caret covers one minor: `^0.3.0` is `>=0.3.0 <0.4.0`. Declare the
 minor whose `MailMessage` your transport reads — `0.2` is the one with
-`attachments` — and release your transport when `@nxgt/mail` moves to the next.
+`attachments`, `0.3` the one with `idempotencyKey` — and release your
+transport when `@nxgt/mail` moves to the next.
 
 An error's `message` reports a shape, never a value: never an address, a
 subject, a link, an API key or a connection string. What the provider said goes
@@ -105,9 +109,12 @@ Throws `MailRefused`, naming **where** the problem is and never the value:
 | an attachment whose `content` is not a `Uint8Array` — a string, a path, an `ArrayBuffer` | `send: attachments[0].content must be a Uint8Array — the file's bytes, never a path or a URL` |
 | a file name that is empty, `.` or `..`, or holds `/`, `\`, a line break, a control character or a format character | `send: attachments[0].filename must be a file name — not empty, not . or .., without / or \, a line break or a control character` |
 | a content type that is not a bare `type/subtype`, or is `multipart/*` or `message/*` | `send: attachments[0].contentType must be a file's type/subtype, as application/pdf — never multipart/* or message/*` |
+| an `idempotencyKey` that is not 1 to 256 visible ASCII characters — empty, a space, a line break, a letter outside ASCII, not a string | `send: idempotencyKey must be 1 to 256 visible ASCII characters, as order-42/receipt` |
 
 An empty `attachments` is accepted, and is the same as none: send no
-attachment field to the provider then.
+attachment field to the provider then. A key that passes is safe to write in
+an HTTP header as it is: no line break, no character a header would need to
+encode.
 
 Two helpers turn addresses into what a provider wants:
 
@@ -153,6 +160,8 @@ export function createHttpMailer(options: HttpMailerOptions): Mailer {
 	return {
 		async send(message) {
 			checkMessage(message);
+			// The key names the send; it is not part of the e-mail, so it stays out of the body.
+			const { idempotencyKey, ...fields } = message;
 			// A JSON API takes an attachment's bytes as base64.
 			// An empty list is none: the field is left out of the request.
 			const attachments = message.attachments?.length
@@ -167,8 +176,13 @@ export function createHttpMailer(options: HttpMailerOptions): Mailer {
 			try {
 				response = await post(options.endpoint, {
 					method: 'POST',
-					headers: { authorization: `Bearer ${options.apiKey}`, 'content-type': 'application/json' },
-					body: JSON.stringify({ ...message, from: message.from ?? options.from, attachments }),
+					headers: {
+						authorization: `Bearer ${options.apiKey}`,
+						'content-type': 'application/json',
+						// This provider deduplicates on a header; with one that does not, leave the key out.
+						...(idempotencyKey === undefined ? {} : { 'idempotency-key': idempotencyKey }),
+					},
+					body: JSON.stringify({ ...fields, from: message.from ?? options.from, attachments }),
 				});
 			} catch (cause) {
 				throw new MailFailure('send: the provider could not be reached', { cause });
@@ -190,6 +204,51 @@ export function createHttpMailer(options: HttpMailerOptions): Mailer {
 }
 ```
 
+## The idempotency key
+
+`idempotencyKey` names a send, so that sending the same message again — a
+retry after a timeout, a job run twice — delivers it once. What a transport
+does with it depends on its provider:
+
+| The provider | The transport |
+| --- | --- |
+| deduplicates requests on a key — an `Idempotency-Key` header, a field of its API | passes the key there, as it is. A repeated key answers the first send's id: resolve with it, as for any hand-over. Map the provider's answers: a key reused for a **different** message is a `MailRefused` (sending it again fails again); a key whose first send is **still in progress** is a `MailFailure` (a later retry may work) |
+| has no such mechanism — SMTP, most relays | ignores the key. It does not refuse the message, and does not emulate deduplication with state of its own: a cache in one process is not what the caller was promised |
+
+Either way, **never put the key in the e-mail** — not in the body, not as a
+header the recipient receives. It names the send, not the message, and it is
+derived from what the e-mail is about (`order-42/receipt`): a caller did not
+choose to show it. `@nxgt/mail-resend` sends it as Resend's `Idempotency-Key`;
+`@nxgt/mail-smtp` ignores it.
+
+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.
+
+```ts
+import { expect, test } from 'bun:test';
+import { sampleMessage } from '@nxgt/mail/conformance';
+import { createHttpMailer } from './http-mailer';
+
+test('sends the idempotency key as a header, never in the body', async () => {
+	const requests: { headers: Headers; body: Record<string, unknown> }[] = [];
+	const mailer = createHttpMailer({
+		endpoint: 'https://mail.example.test/send',
+		apiKey: 'test',
+		fetch: async (_url, init) => {
+			requests.push({ headers: new Headers(init.headers), body: JSON.parse(String(init.body)) });
+			return Response.json({ id: 'm-1' });
+		},
+	});
+	await mailer.send({ ...sampleMessage, idempotencyKey: 'order-42/receipt' });
+	expect(requests[0]?.headers.get('idempotency-key')).toBe('order-42/receipt');
+	expect('idempotencyKey' in (requests[0]?.body ?? {})).toBe(false);
+});
+```
+
 ## The conformance suite
 
 ```ts

package/docs/roadmap.md

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