Nodemailer one-click unsubscribe: RFC 8058 example

Nodemailer can add RFC 8058 headers to marketing and subscribed messages without a provider-specific API. Ordinary transactional messages such as password resets and receipts do not require one-click unsubscribe.

Quick primer: required headers

• List-Unsubscribe: include an HTTPS endpoint; mailto can be an additional fallback.
• List-Unsubscribe-Post: List-Unsubscribe=One-Click: signals that the provider should send an RFC 8058 POST.
• Process requests within 48 hours (aim for immediate suppression).

Minimal Nodemailer setup

Use a transport that already aligns SPF/DKIM/DMARC (SMTP Zen or your relay). Then add headers to each message or via defaults.

import nodemailer from "nodemailer";

const transporter = nodemailer.createTransport({
  host: process.env.SMTP_HOST,
  port: 465,
  secure: true,
  auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS }
});

const listId = "abcd1234"; // signed token mapping to recipient+list

await transporter.sendMail({
  from: '"Product Updates" <[email protected]>',
  to: "[email protected]",
  subject: "Service notice",
  text: "Plain text body",
  html: "<p>HTML body with visible unsubscribe link below.</p>",
  headers: {
    "List-Unsubscribe": `<https://example.com/unsub/${listId}>, <mailto:[email protected]?subject=unsubscribe>`,
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
  }
});

Notes:

• Keep the body unsubscribe link visible. Hiding it raises complaints.
• The HTTPS endpoint must accept POST without login, cookies, or CSRF and return a successful response quickly.
• Do not expose raw emails in the URL; use signed tokens.

Setting defaults per transport (recommended)

Avoid duplicating headers by configuring transporter.set in Nodemailer 6.x:

transporter.set("headers", {
  "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
});

Still set List-Unsubscribe per message, because the token must map to the recipient.

Handling the one-click endpoint

• Accept POST with List-Unsubscribe=One-Click; reserve GET for a human-facing preference page.
• Immediately suppress the address from the list represented by the token.
• Keep essential transactional messages in a separate mailstream.
• Log timestamp, token/list, and IP for auditability.

Testing checklist

• Send a test to Gmail and Yahoo; verify both headers exist in “Show original.”
• Click the HTTPS link; confirm instant suppression and a 200 response.
• Fire a follow-up test within 24 hours; the unsubscribed recipient must be excluded.
• Monitor complaint rates; aim for <0.1%.

Where SMTP Zen helps

SMTP Zen handles authentication and safe SMTP delivery. Add the headers above in Nodemailer, point the links to your suppression logic, and you stay compliant without adopting a marketing platform.