@ultimat3/mail 22.5.1 → 22.6.0

package/README.md

@@ -58,7 +58,7 @@ setMailTransform(async (rendered, meta) =>
 | Every colour is a token | `MAIL_TOKENS` in `layout.ts` holds light + dark hexes; templates never see a hex |
 | Every date takes an IANA zone | `options.tz`, else `ctx.tz`, else `UTC` |
 | No CR/LF in a header-bound field | checked in `renderMessage` and again in `sendMailJob`, so every driver refuses the same message (`X_MAIL_HEADER_INVALID`). `mime.ts` keeps its own gate for the headers the SMTP transport mints itself |
-| `unsubscribeUrl` is one-click unless you say otherwise | it emits `List-Unsubscribe: <url>` plus `List-Unsubscribe-Post: List-Unsubscribe=One-Click` (RFC 8058), a promise that a POST to that URL unsubscribes. When the URL is a confirm page — GET shows a button and must never unsubscribe, because scanners prefetch — pass `unsubscribeOneClick: false`: the `-Post` line goes, `List-Unsubscribe` and the footer link stay |
+| `unsubscribeUrl` is one-click, and one-click is the supported path | it emits `List-Unsubscribe: <url>` plus `List-Unsubscribe-Post: List-Unsubscribe=One-Click` (RFC 8058), and the footer links the SAME url. Make that url one page that answers both: `GET` renders a confirm button and never unsubscribes (scanners prefetch), and `POST` — the mail client's one-click, or the button's own form — runs the action: `defineRoute({ render: 'ssr', …, post: 'unsubscribe' })` (`@ultimat3/render`) binds it, with the url's query (`?t=<token>`) merged into the input. `unsubscribeOneClick: false` drops the `-Post` line for a url that still cannot take a POST; it is the fallback, not the path |
 | Sending is a job | `retry: { attempts: 5, backoff: 'exponential' }`, idempotency key `mail:<mailId>:<hash(recipients + rendered)>` — 128 bits, ASCII, under Resend's 256-character limit at any recipient count — or `(mailId, your key)` when you pass one (digested if it is not a short ASCII token) — a caller's key is scoped to its mail so two templates cannot dedupe each other away |
 
 ## Drivers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mail",
-  "version": "22.5.1",
+  "version": "22.6.0",
   "description": "Transactional email as data: one template renders HTML and text, sent through a job.",
   "license": "MIT",
   "type": "module",
@@ -31,10 +31,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.5.1",
-    "@ultimat3/i18n": "22.5.1",
-    "@ultimat3/jobs": "22.5.1",
-    "@ultimat3/schema": "22.5.1",
-    "@ultimat3/time": "22.5.1"
+    "@ultimat3/core": "22.6.0",
+    "@ultimat3/i18n": "22.6.0",
+    "@ultimat3/jobs": "22.6.0",
+    "@ultimat3/schema": "22.6.0",
+    "@ultimat3/time": "22.6.0"
   }
 }

package/src/driver.ts

@@ -28,9 +28,11 @@ export interface MailMessage {
   readonly bcc?: readonly string[] | undefined;
   readonly unsubscribeUrl?: string | undefined;
   /**
-   * `false` drops `List-Unsubscribe-Post` and keeps the GET-only `List-Unsubscribe`: for an
-   * `unsubscribeUrl` that is a confirm page, which cannot honour RFC 8058's promise that a POST to
-   * it unsubscribes. Absent means `true` — one-click, what Gmail and Yahoo require of bulk senders.
+   * Absent means `true` — one-click, what Gmail and Yahoo require of bulk senders, and the
+   * supported path: the url is a page whose `GET` confirms and whose `POST` unsubscribes
+   * (`defineRoute({ post: '<action>' })` in `@ultimat3/render`). `false` drops
+   * `List-Unsubscribe-Post` and keeps the GET-only `List-Unsubscribe`, for a url that cannot yet
+   * honour RFC 8058's promise that a POST to it unsubscribes.
    */
   readonly unsubscribeOneClick?: boolean | undefined;
   readonly idempotencyKey?: string | undefined;

package/src/mail.ts

@@ -46,8 +46,10 @@ export interface SendOptions {
   readonly unsubscribeUrl?: string | undefined;
   /**
    * Default `true`: `List-Unsubscribe-Post: List-Unsubscribe=One-Click` (RFC 8058) rides with
-   * `List-Unsubscribe`. `false` when `unsubscribeUrl` is a GET confirm page that cannot take the
-   * one-click POST — the header and the footer link stay, the POST promise goes.
+   * `List-Unsubscribe`, and it is the supported path — one url for the header and the footer, a
+   * page whose `GET` confirms and whose `POST` unsubscribes (`defineRoute({ post: '<action>' })`).
+   * `false` is the fallback for a url that cannot take the POST: the header and the footer link
+   * stay, the POST promise goes.
    */
   readonly unsubscribeOneClick?: boolean | undefined;
   readonly idempotencyKey?: string | undefined;