Since February 2024, Gmail and Yahoo require bulk senders (5,000+ emails per day) to include a List-Unsubscribe header in every marketing email. Miss it and you are in violation of their sender requirements. Even below that threshold, missing this header is one of the faster ways to accumulate spam complaints.
What the header does
List-Unsubscribe tells inbox providers where to send unsubscribe requests on behalf of the recipient. When present, Gmail shows a visible "Unsubscribe" link next to the sender name at the top of the email.
When a recipient clicks it, they unsubscribe cleanly instead of hitting "Report spam." Spam reports damage your sender reputation. Clean unsubscribes do not. This header converts would-be complainers into clean unsubscribes.
What you need to include
Two headers are required for full compliance:
List-Unsubscribe: <mailto:unsub@yourdomain.com>, <https://yourdomain.com/unsubscribe?uid=123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
The List-Unsubscribe-Post header is what enables one-click unsubscribe, which is specifically what Gmail and Yahoo require. The mailto: is a fallback for older clients.
Your unsubscribe URL must handle a POST request and actually remove the contact from your list.
Adding it in PHP
$headers[] = 'List-Unsubscribe: <mailto:unsub@yourdomain.com>, <https://yourdomain.com/unsubscribe?uid=' . $uid . '>';
$headers[] = 'List-Unsubscribe-Post: List-Unsubscribe=One-Click';
In ESPs
Mailchimp: Added automatically when you use the standard unsubscribe footer. Do not remove it.
SendGrid: Settings > Tracking > Subscription Tracking. Enable it and SendGrid adds the header automatically. For API sends, add it manually in the headers object of your payload.
Verify it worked
Send a test to a Gmail address. If the header is present, Gmail shows "Unsubscribe" next to the sender name. You can also open Show original and search for List-Unsubscribe in the raw headers.
Run a full check at InboxGreen to verify alongside SPF, DKIM, and DMARC.
For the full guide with code examples and common mistakes: List-Unsubscribe missing: fix guide
Top comments (0)