How to Use the List-Unsubscribe Header Generator
Enter your unsubscribe URL and optional mailbox, then copy the headers and the request your endpoint must handle.
- Enter the HTTPS unsubscribe URL, including your platform’s per-recipient placeholder.
- Add an optional mailto address and subject as a fallback for mail apps.
- Keep one-click on if you send marketing or bulk mail, then select Build headers.
- Copy the headers into your sending platform and test the endpoint with the example POST request.
List-Unsubscribe Header Format
The List-Unsubscribe header format is a comma-separated list of URIs in angle brackets, optionally paired with a List-Unsubscribe-Post header for one-click.
List-Unsubscribe Header Example
A complete header looks like List-Unsubscribe: <https://example.com/unsubscribe?u=abc123>, <mailto:unsubscribe@example.com?subject=unsubscribe>. Each URI sits in angle brackets, separated by a comma, with the preferred HTTPS link first. The generator percent-encodes the mailto subject and any comma inside the URL so the list stays unambiguous.
List-Unsubscribe-Post Header
The second header is always List-Unsubscribe-Post: List-Unsubscribe=One-Click. It tells the mailbox provider that it may unsubscribe the recipient with an automatic POST to the HTTPS URL. The generator adds it only when an HTTPS URL exists and one-click is turned on.
One-Click Unsubscribe RFC 8058
RFC 8058 requires an HTTPS URI in List-Unsubscribe and a valid DKIM signature that covers both headers. The provider posts the body List-Unsubscribe=One-Click without cookies or login details, so the URL must identify the recipient on its own. Your endpoint should unsubscribe on that POST and never on a plain GET.
One-Click Unsubscribe Requirements
Since 2024, Gmail requires senders of more than 5,000 messages a day to Gmail accounts to support one-click unsubscribe in marketing mail. Yahoo sets the same requirement for bulk senders, and both ask for unsubscribes to be processed within 2 days. A visible unsubscribe link in the message body is still expected as well.
Frequently Asked Questions
What Is a List-Unsubscribe Header?
It is an email header, defined in RFC 2369, that lists one or more addresses for leaving a mailing list. Mail apps use it to show their own unsubscribe button next to the sender. A message without it can show the warning that your email is missing the List-Unsubscribe header in deliverability tools.
How Does One-Click Unsubscribe Work?
When a recipient selects the provider’s unsubscribe button, the provider sends an HTTPS POST request to your List-Unsubscribe URL with the body List-Unsubscribe=One-Click. Your server removes the recipient identified by the URL and answers with a success status. The recipient never has to open your website.
Is One-Click Unsubscribe Required?
Gmail and Yahoo require it from bulk senders of marketing and subscribed mail, and Gmail applies its rule to senders of more than 5,000 messages a day. Transactional messages such as receipts and password resets are not covered by that requirement. Smaller senders also benefit, because an easy unsubscribe reduces spam complaints.
How Do You Add a List-Unsubscribe Header?
Most sending platforms add the header for you or offer a custom-header field. Paste the List-Unsubscribe and List-Unsubscribe-Post values from this generator there, and make sure your DKIM signature includes both headers. Then send a test message and check its raw headers.
Related Email Tools
Continue with the guide Why Are My Emails Going to Spam?. Investigate configuration, content and reputation.