One-Click Unsubscribe Guide (RFC 8058)

Requirement 1: List-Unsubscribe Headers

All marketing emails must include both List-Unsubscribe and List-Unsubscribe-Post headers

Requirement 2: Immediate Processing

Unsubscribe requests must be processed within 2 days (48 hours maximum)

Requirement 3: Visible Link

Email body must still contain a visible unsubscribe link (one-click headers are supplementary)

Footer Placement

Include a clear, visible unsubscribe link in your email footer:

One-Click vs Traditional

The footer link can be the same URL as your List-Unsubscribe header. Users clicking this link should be immediately unsubscribed with a simple confirmation message - no login, no survey, no additional steps required.

URL Security

Always use unique, tokenized URLs for each recipient to prevent abuse and ensure you can identify who is unsubscribing. Never use a generic unsubscribe page requiring email address entry.

Complete Header Example

Add both headers to your email messages:

Node.js / Nodemailer Example

Configure headers in Nodemailer:

Python / Flask Example

Handle POST requests for one-click unsubscribe:

PHP Example

Add headers using mail() or PHPMailer:

1. Immediate Processing

Process unsubscribe requests immediately - within seconds, not hours or days. Gmail and Yahoo require processing within 2 days, but instant processing is best practice. Update your suppression list in real-time to prevent sending additional emails.

2. Simple Confirmation Pages

For GET requests (traditional link clicks), show a simple confirmation message. Don't ask why they're leaving, don't offer alternatives, don't make them confirm again. Just acknowledge the unsubscribe and thank them.

3. Use Secure, Unique Tokens

Generate unique, cryptographically secure tokens for each recipient. Include the token in your unsubscribe URL to identify the user without requiring login. Tokens should be long enough to prevent guessing (at least 32 characters).

4. Support Both GET and POST

Your unsubscribe endpoint must handle both GET requests (from users clicking links) and POST requests (from one-click unsubscribe). Return HTTP 200/201 for POST requests without any redirect or HTML response.

5. Use HTTPS Only

Always use HTTPS for your List-Unsubscribe URLs to ensure security and meet modern email client requirements. HTTP-only URLs may not work with one-click unsubscribe in Gmail and other providers.

6. Keep URLs Active

Ensure unsubscribe URLs remain functional for at least 30 days after sending (CAN-SPAM requirement). Consider keeping them active indefinitely to handle delayed unsubscribes gracefully.

7. Don't Resubscribe

Once someone unsubscribes, never add them back to your list without explicit re-subscription. Maintain a permanent suppression list and check it before adding any email address to your active lists.

8. Log All Unsubscribes

Keep detailed logs of all unsubscribe requests including timestamp, method (GET/POST), IP address, and processing status. These logs are valuable for compliance audits and troubleshooting.

Missing List-Unsubscribe-Post Header

Problem: Including List-Unsubscribe header but forgetting List-Unsubscribe-Post

Solution: Both headers are required for one-click functionality. Always include List-Unsubscribe-Post: List-Unsubscribe=One-Click when using HTTPS URLs.

Broken or Expired Links

Problem: Unsubscribe links returning 404 errors or expiring too quickly

Solution: Test your unsubscribe URLs before sending. Keep tokens valid for at least 30 days. Implement proper error handling and logging to catch broken links.

Slow Processing Times

Problem: Taking hours or days to process unsubscribe requests

Solution: Implement real-time unsubscribe processing. Update your suppression list immediately and ensure all sending systems check it before every send.

POST Request Not Supported

Problem: Unsubscribe endpoint only handles GET requests

Solution: Configure your endpoint to accept both GET and POST methods. For POST, return empty body with 200 status. For GET, show confirmation page.

Redirects or Login Required

Problem: Redirecting users to login page or requiring authentication

Solution: Use tokenized URLs that don't require login. For POST requests, don't redirect - just process and return 200. No authentication should be needed.

Using HTTP Instead of HTTPS

Problem: List-Unsubscribe URLs using http:// instead of https://

Solution: Always use HTTPS for unsubscribe URLs. Many email clients require HTTPS for one-click unsubscribe to work. HTTP URLs may be ignored or blocked.

1. Verify Headers

Send a test email to yourself and check the raw email headers. Verify that both List-Unsubscribe and List-Unsubscribe-Post headers are present and correctly formatted.

Use our Header Validator tool to analyze email headers and verify compliance.

2. Test GET Requests

Click the unsubscribe link in your test email. Verify that it unsubscribes you immediately and shows a simple confirmation page. The process should require no login and no additional clicks.

3. Test POST Requests

Manually test POST requests using curl or a similar tool:

Verify you receive HTTP 200 or 201 status with empty body.

4. Test in Gmail

Send a test email to a Gmail address. Check if the "Unsubscribe" link appears next to your sender name in the Gmail interface. Click it to test the one-click functionality from Gmail's perspective.

5. Verify Processing Time

After unsubscribing, verify that the email address is immediately added to your suppression list and that no additional emails are sent to it. Test that your system prevents re-sending within seconds, not minutes.

6. Monitor Logs

Check your server logs to ensure unsubscribe requests are being received and processed correctly. Look for any errors, failed requests, or unusual patterns that might indicate problems.