@zerotal/notifications 1.11.0 → 1.11.1

package/CHANGELOG.md

@@ -8,6 +8,38 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.11.1] — 2026-08-31
+
+### Added
+
+- **`MailMessage.header()` and `MailPayload.headers`** — set a header the driver does
+  not build itself. `MailPayload` had `to`/`from`/`subject`/`text`/`html`/`cc`/`bcc`/
+  `replyTo`/`attachments` and no way to add one, so a team that wanted
+  `List-Unsubscribe` had to patch a vendored copy of this package and settled for a
+  footer link instead.
+
+  That is not an equivalent substitute. Gmail and Yahoo draw their native unsubscribe
+  control from the header, and a recipient who cannot find a control marks the message
+  as spam instead — a judgement that attaches to the sending domain and degrades
+  delivery of everything else it sends. Pair it with `List-Unsubscribe-Post` for the
+  one-click form both providers now expect.
+
+  Wired through all three drivers: SMTP writes them into the message, Resend sends
+  them as the API's `headers` object, and the log driver prints them, since the reason
+  to set one is that a client does something with it and the log driver is where that
+  gets checked before anything is sent for real.
+
+  Names the drivers build themselves are refused rather than sent twice — a second
+  `Subject` is an ambiguous message, not an override — and the error names the
+  `MailMessage` method to use instead. The list is exported as
+  `RESERVED_MAIL_HEADERS`, with `resolveHeaders()` beside it for anyone writing a
+  custom transport. Validation runs when the header is set, so the throw carries the
+  stack of the code that wrote it rather than of a queue worker three hops away, and
+  again in the driver, because a payload can reach one without passing through
+  `MailMessage`. CR and LF in a value are folded to a space: left raw they end the
+  header and let the remainder be read as further headers, which is how a `Bcc`
+  arrives courtesy of whoever supplied a tracking ID.
+
 ## [1.11.0] — 2026-08-31
 
 ### Changed

package/api-surface.md

@@ -54,6 +54,7 @@ class MailMessage = {
   embed: (cid: string, attachment: Omit<MailAttachment, 'cid' | 'inline'>) => MailMessage
   from: (address: AddressInput) => MailMessage
   greeting: {    (text: string): MailMessage;    (text: string, style: TextStyle): MailMessage;    (build: (t: RichLine) => void): MailMessage;}
+  header: (name: string, value: string) => MailMessage
   html: (content: string) => MailMessage
   line: {    (text: string): MailMessage;    (text: string, style: TextStyle): MailMessage;    (build: (t: RichLine) => void): MailMessage;}
   replyTo: (address: AddressInput) => MailMessage
@@ -304,12 +305,16 @@ const NotificationRegistry = {    _map: Map<string, NotificationClass>;    regis
 
 const Notify = NotificationManager
 
+const RESERVED_MAIL_HEADERS = readonly string[]
+
 function channelStats = () => ChannelStat[]
 
 function NotificationConfig = (options?: DeepPartial<NotificationConfigShape>) => NotificationConfigShape
 
 function recentDeliveries = () => RecentDelivery[]
 
+function resolveHeaders = (headers: Record<string, string>) => Record<string, string>
+
 interface ChannelStat = {
   avgMs: number
   channel: string
@@ -352,6 +357,7 @@ interface MailPayload = {
   bcc?: MailAddress[]
   cc?: MailAddress[]
   from: MailAddress
+  headers?: Record<string, string>
   html?: string
   replyTo?: MailAddress
   subject: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/notifications",
-  "version": "1.11.0",
+  "version": "1.11.1",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -30,12 +30,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.11.0",
-    "@zerotal/orm": "1.11.0",
-    "@zerotal/queue": "1.11.0"
+    "@zerotal/core": "1.11.1",
+    "@zerotal/orm": "1.11.1",
+    "@zerotal/queue": "1.11.1"
   },
   "devDependencies": {
-    "@zerotal/broadcasting": "1.11.0",
+    "@zerotal/broadcasting": "1.11.1",
     "typescript": "^5.8.0"
   },
   "description": "Multi-channel notifications for Zerotal — mail (SMTP/Resend), database, broadcast, Slack, and SMS.",

package/src/drivers/LogDriver.ts

@@ -15,6 +15,10 @@ export class LogDriver implements MailDriver {
       `From:    ${message.from.name ? `${message.from.name} <${message.from.address}>` : message.from.address}`,
       `Subject: ${message.subject}`,
       ...(message.cc?.length ? [`CC:      ${message.cc.map((a) => a.address).join(", ")}`] : []),
+      // Printed because the reason to set one is that a mail client does
+      // something with it, and the log driver is where that gets checked before
+      // anything is sent for real.
+      ...Object.entries(message.headers ?? {}).map(([n, v]) => `${n}: ${v}`),
       ...(message.attachments?.length
         ? [
             `Files:   ${message.attachments

package/src/drivers/MailDriver.ts

@@ -36,6 +36,70 @@ export interface MailAttachment {
   cid?: string;
 }
 
+/**
+ * Header names a driver builds itself, which a custom header may not set.
+ *
+ * Two reasons, and both are about a message that arrives wrong rather than one
+ * that fails to send. `Content-Type`, `MIME-Version` and
+ * `Content-Transfer-Encoding` describe the body a driver is assembling — a second
+ * copy makes the structure ambiguous and clients disagree about which to believe.
+ * The rest already have a dedicated method on {@link MailMessage}; setting one
+ * here would duplicate the header rather than replace it, because the driver has
+ * no way to know which was meant.
+ *
+ * Compared case-insensitively — header names are not case-sensitive, so
+ * `content-type` has to be refused as readily as `Content-Type`.
+ */
+export const RESERVED_MAIL_HEADERS: readonly string[] = [
+  "bcc",
+  "cc",
+  "content-transfer-encoding",
+  "content-type",
+  "date",
+  "from",
+  "message-id",
+  "mime-version",
+  "reply-to",
+  "subject",
+  "to",
+];
+
+/**
+ * Custom headers, sanitised and checked against {@link RESERVED_MAIL_HEADERS}.
+ *
+ * @param headers - Header names to values, as written by the caller.
+ * @returns The same headers with CR and LF removed from every value.
+ * @throws When a name is reserved, or a name is not a legal header token.
+ */
+export function resolveHeaders(headers: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [name, value] of Object.entries(headers)) {
+    const trimmed = name.trim();
+    if (RESERVED_MAIL_HEADERS.includes(trimmed.toLowerCase())) {
+      throw new Error(
+        `[Zerotal/notifications] "${trimmed}" is set by the mail driver and cannot be ` +
+          `passed as a custom header — it would be sent twice rather than replaced. ` +
+          `Use the MailMessage method for it (.subject(), .from(), .to(), .cc(), .bcc(), ` +
+          `.replyTo()) where there is one.`,
+      );
+    }
+    // RFC 5322 field names are printable ASCII except colon. A name carrying a
+    // colon, a space or a newline does not become a header — it becomes a way to
+    // write the rest of the message.
+    if (!/^[!-9;-~]+$/.test(trimmed)) {
+      throw new Error(
+        `[Zerotal/notifications] "${trimmed}" is not a valid header name — a header name is ` +
+          `printable ASCII with no spaces, colons or line breaks.`,
+      );
+    }
+    // CR/LF in a value ends the header and lets the remainder be read as further
+    // headers. Stripped rather than refused: unlike the name, a value is often
+    // built from content, and folding it to one line keeps the message intact.
+    out[trimmed] = value.replace(/[\r\n]+/g, " ").trim();
+  }
+  return out;
+}
+
 /** The resolved, ready-to-send shape of a single email. */
 export interface MailPayload {
   to: MailAddress[];
@@ -47,6 +111,25 @@ export interface MailPayload {
   bcc?: MailAddress[];
   replyTo?: MailAddress;
   attachments?: MailAttachment[];
+  /**
+   * Extra headers to put on the message, beyond the ones the driver builds.
+   *
+   * The reason this exists is `List-Unsubscribe`: Gmail and Yahoo draw their
+   * native unsubscribe control beside the sender from that header, and there is
+   * no way to ask for it other than sending it. A footer link is a different
+   * thing in a different place, and bulk senders are required to send the header.
+   *
+   * Names in {@link RESERVED_MAIL_HEADERS} are refused — see there for why.
+   *
+   * @example
+   * ```ts
+   * new MailMessage()
+   *   .subject("Your weekly digest")
+   *   .header("List-Unsubscribe", `<https://app.test/unsubscribe/${token}>`)
+   *   .header("List-Unsubscribe-Post", "List-Unsubscribe=One-Click");
+   * ```
+   */
+  headers?: Record<string, string>;
 }
 
 export interface MailDriver {

package/src/drivers/ResendDriver.ts

@@ -1,4 +1,5 @@
 import type { MailDriver, MailPayload } from "./MailDriver.ts";
+import { resolveHeaders } from "./MailDriver.ts";
 import { NotificationDeliveryError } from "../errors.ts";
 
 /**
@@ -21,6 +22,12 @@ export class ResendDriver implements MailDriver {
     if (message.cc?.length) body["cc"] = message.cc.map((a) => a.address);
     if (message.bcc?.length) body["bcc"] = message.bcc.map((a) => a.address);
     if (message.replyTo) body["reply_to"] = message.replyTo.address;
+    // Resend takes custom headers as an object and sets the rest itself, so the
+    // reserved names are refused here too rather than handed to the API to
+    // silently drop or duplicate.
+    if (message.headers && Object.keys(message.headers).length > 0) {
+      body["headers"] = resolveHeaders(message.headers);
+    }
     if (message.html !== undefined) body["html"] = message.html;
     if (message.text !== undefined) body["text"] = message.text;
     if (message.attachments?.length) {

package/src/drivers/SmtpDriver.ts

@@ -1,4 +1,5 @@
 import type { MailDriver, MailPayload, MailAddress } from "./MailDriver.ts";
+import { resolveHeaders } from "./MailDriver.ts";
 import { SmtpResponseError, SmtpConnectionError } from "../errors.ts";
 
 /** How long to wait for any single SMTP reply before giving up. */
@@ -616,6 +617,15 @@ function buildRawMessage(msg: MailPayload): string {
   );
   lines.push("MIME-Version: 1.0");
 
+  // Re-validated here, not just in `MailMessage.header()`, because a payload can
+  // reach a driver without ever passing through the builder — a job deserialising
+  // one, or an app constructing a MailPayload literal. Placing them after the
+  // headers this function owns would not be enough on its own: a second `Subject`
+  // is still a second `Subject`, wherever it sits.
+  for (const [name, value] of Object.entries(resolveHeaders(msg.headers ?? {}))) {
+    lines.push(`${name}: ${encodeHeaderValue(value)}`);
+  }
+
   const attachments = msg.attachments ?? [];
   const body = renderBody(msg);
 

package/src/index.ts

@@ -38,6 +38,10 @@ export type {
   MailAttachment,
   AddressInput,
 } from "./drivers/MailDriver.ts";
+// Exported for the same reason the drivers above are: writing a custom transport
+// is a supported thing to do, and a custom transport has to refuse the same header
+// names the built-in ones refuse.
+export { RESERVED_MAIL_HEADERS, resolveHeaders } from "./drivers/MailDriver.ts";
 
 export { SendNotificationJob } from "./SendNotificationJob.ts";
 export { BroadcastNotificationJob } from "./BroadcastNotificationJob.ts";

package/src/messages/MailMessage.ts

@@ -1,6 +1,7 @@
 import { tryCurrentApp } from "@zerotal/core";
 import {
   resolveAddress,
+  resolveHeaders,
   type AddressInput,
   type MailAddress,
   type MailAttachment,
@@ -165,6 +166,7 @@ export class MailMessage {
   private _from?: MailAddress;
   private _replyTo?: MailAddress;
   private _attachments: MailAttachment[] = [];
+  private _headers: Record<string, string> = {};
 
   subject(text: string): this {
     this._subject = text;
@@ -254,6 +256,44 @@ export class MailMessage {
     return this;
   }
 
+  /**
+   * Set a header on the message, beyond the ones the driver builds itself.
+   *
+   * The header this exists for is `List-Unsubscribe`. Gmail and Yahoo draw their
+   * native unsubscribe control — the one beside the sender's name, not the one in
+   * your footer — from that header, and there is no other way to ask for it. Bulk
+   * senders are required to send it; everyone else benefits from a recipient who
+   * unsubscribes instead of reporting spam, because the second one costs the
+   * sending domain its reputation and the first does not.
+   *
+   * Pair it with `List-Unsubscribe-Post` to get the one-click form, which is what
+   * both providers now expect: the header alone leaves the recipient a `mailto:`
+   * or a link to follow, and only the pair produces a button that resolves in one
+   * press.
+   *
+   * Header names the driver builds itself are refused rather than sent twice —
+   * see {@link RESERVED_MAIL_HEADERS}. Calling this twice with the same name
+   * replaces the value, since a driver cannot know which of two was meant.
+   *
+   * @param name - Header name. Printable ASCII, no spaces or colons.
+   * @param value - Header value. CR and LF are folded to a space.
+   * @throws When the name is reserved or malformed.
+   *
+   * @example
+   * ```ts
+   * new MailMessage()
+   *   .subject("Your weekly digest")
+   *   .header("List-Unsubscribe", `<https://app.test/unsubscribe/${token}>, <mailto:unsub@app.test>`)
+   *   .header("List-Unsubscribe-Post", "List-Unsubscribe=One-Click");
+   * ```
+   */
+  header(name: string, value: string): this {
+    // Validated here rather than at send time so the throw carries the stack of
+    // the code that wrote the header, not of a queue worker three hops away.
+    Object.assign(this._headers, resolveHeaders({ [name]: value }));
+    return this;
+  }
+
   /**
    * Attach a file to the message.
    *
@@ -321,6 +361,7 @@ export class MailMessage {
       ...(this._bcc.length > 0 ? { bcc: this._bcc } : {}),
       ...(this._replyTo ? { replyTo: this._replyTo } : {}),
       ...(this._attachments.length > 0 ? { attachments: this._attachments } : {}),
+      ...(Object.keys(this._headers).length > 0 ? { headers: this._headers } : {}),
     };
   }