@ultimat3/mail 22.2.2 → 22.3.1

package/README.md

@@ -34,6 +34,7 @@ delivers inline only when `{ sync: true }` is passed or no job driver is configu
 | 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 |
 | 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.2.2",
+  "version": "22.3.1",
   "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.2.2",
-    "@ultimat3/i18n": "22.2.2",
-    "@ultimat3/jobs": "22.2.2",
-    "@ultimat3/schema": "22.2.2",
-    "@ultimat3/time": "22.2.2"
+    "@ultimat3/core": "22.3.1",
+    "@ultimat3/i18n": "22.3.1",
+    "@ultimat3/jobs": "22.3.1",
+    "@ultimat3/schema": "22.3.1",
+    "@ultimat3/time": "22.3.1"
   }
 }

package/src/driver.ts

@@ -27,6 +27,12 @@ export interface MailMessage {
   readonly cc?: readonly string[] | undefined;
   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.
+   */
+  readonly unsubscribeOneClick?: boolean | undefined;
   readonly idempotencyKey?: string | undefined;
 }
 
@@ -47,14 +53,17 @@ export interface MailDriver {
 
 /**
  * RFC 8058 one-click unsubscribe. Gmail and Yahoo require it for bulk senders and
- * reward it for transactional ones, so it is computed here rather than per driver.
+ * reward it for transactional ones, so it is computed here rather than per driver. The `-Post`
+ * line is a promise that a POST to the URL unsubscribes, so `unsubscribeOneClick: false` omits it.
  */
 export function messageHeaders(message: MailMessage): Readonly<Record<string, string>> {
   const headers: Record<string, string> = { 'Auto-Submitted': 'auto-generated' };
   if (message.replyTo !== undefined) headers['Reply-To'] = message.replyTo;
   if (message.unsubscribeUrl !== undefined) {
     headers['List-Unsubscribe'] = `<${message.unsubscribeUrl}>`;
-    headers['List-Unsubscribe-Post'] = 'List-Unsubscribe=One-Click';
+    if (message.unsubscribeOneClick !== false) {
+      headers['List-Unsubscribe-Post'] = 'List-Unsubscribe=One-Click';
+    }
   }
   return headers;
 }

package/src/idempotency.ts

@@ -42,6 +42,8 @@ export function mailIdempotencyKey(message: MailMessage): string {
       tz: message.tz,
       replyTo: message.replyTo ?? '',
       unsubscribeUrl: message.unsubscribeUrl ?? '',
+      // Only when it changes the wire: every key minted before the option existed stays the same.
+      ...(message.unsubscribeOneClick === false ? { unsubscribeOneClick: false } : {}),
     }),
   );
   return `mail:${message.mailId}:${digest}`;

package/src/job.ts

@@ -21,6 +21,7 @@ export const mailMessageSchema: StandardSchemaV1<unknown, MailMessage> = t.objec
   cc: t.array(t.email).optional(),
   bcc: t.array(t.email).optional(),
   unsubscribeUrl: t.url.optional(),
+  unsubscribeOneClick: t.boolean.optional(),
   idempotencyKey: t.string.optional(),
 });
 

package/src/mail.ts

@@ -43,6 +43,12 @@ export interface SendOptions {
   readonly cc?: readonly string[] | undefined;
   readonly bcc?: readonly string[] | undefined;
   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.
+   */
+  readonly unsubscribeOneClick?: boolean | undefined;
   readonly idempotencyKey?: string | undefined;
   /** Deliver inline instead of through the queue. Tests and CLI one-shots only. */
   readonly sync?: boolean | undefined;
@@ -133,6 +139,7 @@ export function renderMessage<I>(
     cc: options.cc,
     bcc: options.bcc,
     unsubscribeUrl: options.unsubscribeUrl,
+    unsubscribeOneClick: options.unsubscribeOneClick,
     idempotencyKey: options.idempotencyKey,
   };
   // Here, not in a driver: interpolated data reaches `Subject`, and whether a break in it injects