patternjavascriptMajor
Unsubscribe handling with List-Unsubscribe header
Viewed 0 times
list-unsubscribeone-click unsubscribeemail headersunsubscribe headergmail bulk senderemail compliance
Problem
Emails without a machine-readable unsubscribe mechanism force users to mark emails as spam instead of unsubscribing, directly harming sender reputation. Since 2024, Gmail and Yahoo require one-click unsubscribe for bulk senders.
Solution
Add the List-Unsubscribe and List-Unsubscribe-Post headers to all marketing emails. List-Unsubscribe should include a mailto: and/or https: URL. The https endpoint must handle POST requests and immediately unsubscribe the recipient without requiring login.
Why
The List-Unsubscribe-Post header enables one-click unsubscribe directly from Gmail and Outlook's UI. When users can unsubscribe easily, they are less likely to mark your email as spam. Google/Yahoo now enforce this for bulk senders (>5000/day).
Gotchas
- The https: URL in List-Unsubscribe-Post must process unsubscribe without authentication or confirmation screens
- List-Unsubscribe-Post requires the POST body to contain List-Unsubscribe=One-Click — your endpoint must accept this parameter
- This header is for marketing email only — transactional emails (receipts, alerts) do not need it
- Some ESPs add this header automatically if you configure unsubscribe URLs through their dashboard
Code Snippets
Set List-Unsubscribe headers with Nodemailer
await transporter.sendMail({
from: 'Brand <newsletter@example.com>',
to: 'user@example.com',
subject: 'Monthly Newsletter',
html: emailHtml,
headers: {
'List-Unsubscribe': '<https://example.com/unsubscribe?token=TOKEN>, <mailto:unsubscribe@example.com?subject=unsubscribe>',
'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
},
});
// Unsubscribe endpoint (Express)
app.post('/unsubscribe', async (req, res) => {
const { token } = req.query;
await db.users.unsubscribeByToken(token);
res.status(200).send('Unsubscribed');
});Context
Bulk marketing email senders (newsletters, promotional campaigns)
Revisions (0)
No revisions yet.