P H O T O N

CONSOLE

Loading

RFC 8058 Standard Blueprint

How to Implement RFC 8058 One-Click List-Unsubscribe
Mandatory Header Syntax & HTTP POST Endpoint Setup

Comply with Google and Yahoo's mandatory unsubscribe rules. Add RFC 8058 headers to Node.js, PHP, and Python email dispatches and handle automated POST callbacks.

5 min read • RFC 8058 & RFC 2369 • Tested Code Snippets
Direct Answer: RFC 8058 One-Click Unsubscribe

RFC 8058 requires two headers: List-Unsubscribe: <https://yourdomain.com/unsubscribe?token=...> and List-Unsubscribe-Post: List-Unsubscribe=One-Click. When a recipient clicks the native 'Unsubscribe' button in Gmail or Yahoo, the receiving server sends an HTTP POST request to that URL. The sender must honor the opt-out within 48 hours without prompting the user for confirmation or login credentials.

1. Why Google & Yahoo Made One-Click Unsubscribe Mandatory

When subscribers cannot easily locate an unsubscribe option, their instinctive reaction is to click **"Report Spam"**. High spam complaint rates (>0.10%) destroy domain reputation and cause mailbox algorithms to throttle future deliveries.

By rendering a prominent native "Unsubscribe" button directly adjacent to the sender name in the webmail UI, mailbox providers enable frictionless opt-outs, protecting your primary inbox placement.

2. RFC 8058 Header Syntax Anatomy

Under RFC 8058, compliant messages must transmit both headers in the MIME envelope:

List-Unsubscribe: <https://notifications.yourdomain.com/api/unsubscribe/usr_98a72b>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
Critical Requirement: The POST request sent by Gmail or Yahoo will have an empty body or contain List-Unsubscribe=One-Click. Your server must NOT require authentication cookies or redirect to an HTML confirmation prompt.

3. Code Implementations: Node.js, PHP & Python

Node.js (Nodemailer)
const mailOptions = {
  from: '"Company News" <newsletter@yourdomain.com>',
  to: user.email,
  subject: "Monthly Product Engineering Digest",
  text: "...",
  headers: {
    'List-Unsubscribe': `<https://yourdomain.com/unsubscribe?token=${user.unsubToken}>`,
    'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click'
  }
};
PHP (PHPMailer)
$mail->addCustomHeader('List-Unsubscribe', '<https://yourdomain.com/unsubscribe?token='.$token.'>');
$mail->addCustomHeader('List-Unsubscribe-Post', 'List-Unsubscribe=One-Click');

4. Building the Inbound HTTP POST Webhook Receiver

Here is a clean Express.js / Node.js endpoint to handle incoming RFC 8058 POST dispatches:

app.post('/api/unsubscribe', async (req, res) => {
  const { token } = req.query;
  if (!token) return res.status(400).send('Missing token');

  // 1. Mark subscriber as unsubscribed in database
  await db.subscribers.update({ token }, { status: 'unsubscribed' });

  // 2. Respond immediately with HTTP 200 OK
  res.status(200).send('Unsubscribed successfully');
});

Automate One-Click Unsubscribe with PhotonRelay

Photon Console automatically injects RFC 8058 headers and syncs unsubscribe webhooks directly to your CRM, ensuring 100% compliance with Google and Yahoo.

6. Frequently Asked Questions

No. While mailto: was acceptable in the past, Google and Yahoo's latest requirements explicitly mandate HTTP POST support via List-Unsubscribe-Post: List-Unsubscribe=One-Click for all bulk and promotional dispatches.

Pure transactional emails (such as one-time passwords, password reset links, order confirmations, and security fraud notices) are exempt from one-click unsubscribe mandates. However, marketing broadcasts, newsletters, and promotional announcements must include them.

Under Google and Yahoo sender guidelines, unsubscribe requests submitted via RFC 8058 one-click headers must be honored and suppressed from future marketing dispatches within 48 hours.