List-Unsubscribe Header Missing: What It Means and How to Add It

Last updated 2026-05-29 — By The InboxGreen Team

A missing List-Unsubscribe header means your bulk or marketing emails do not include the standard email header that lets inbox providers offer a one-click unsubscribe option. Since February 2024, Gmail and Yahoo require this header for any sender sending more than 5,000 emails per day. Without it, complaints go up, inbox placement goes down, and your sending reputation weakens over time.

What it means

The <code>List-Unsubscribe</code> header is an email header that tells inbox providers where to send unsubscribe requests on behalf of the recipient. Gmail and Yahoo show a visible "Unsubscribe" link at the top of emails that include this header. When a recipient uses this link, complaints are replaced with clean unsubscribes, which is far better for your sender reputation.

Why it matters

Without List-Unsubscribe, users who want to stop receiving your emails hit the "Report spam" button instead of finding an unsubscribe link. Each spam report damages your sender reputation. Gmail and Yahoo have made this header a formal requirement for bulk senders. Even below the 5,000/day threshold, including it is best practice.

Example List-Unsubscribe header (PHP)

List-Unsubscribe: <mailto:[email protected]?subject=unsubscribe>, <https://yourdomain.com/unsubscribe?email={email}>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The List-Unsubscribe-Post header enables one-click unsubscribe (required by Gmail/Yahoo for bulk senders). The mailto: is a fallback. Replace the URL with your actual unsubscribe endpoint that handles a POST request.

How to fix it

PHP (custom mailer)

  1. Add the header to your outgoing email headers.
  2. List-Unsubscribe: <mailto:[email protected]>, <https://yourdomain.com/unsubscribe?uid={id}>
  3. List-Unsubscribe-Post: List-Unsubscribe=One-Click
  4. Ensure the unsubscribe URL handles a POST request and removes the contact from your list.

Mailchimp

  1. Mailchimp adds List-Unsubscribe headers automatically for all campaigns.
  2. Ensure you are using Mailchimp's standard unsubscribe footer and have not removed it.
  3. For transactional emails via Mandrill, add the header manually or use Mailchimp's merge tags.

SendGrid

  1. Go to Settings > Tracking > Subscription Tracking.
  2. Enable Subscription Tracking and SendGrid will add the header and manage unsubscribes.
  3. For the API, add the header manually in your mail send payload under headers.

How to verify the fix

  1. Send a test email to a Gmail address.
  2. Open the email in Gmail and look for an "Unsubscribe" link next to the sender name.
  3. In the raw headers (Show original), confirm List-Unsubscribe and List-Unsubscribe-Post are present.
  4. Run your domain through the InboxGreen free checker to confirm the List-Unsubscribe check passes.

Check your fix right now

Run your domain through InboxGreen's free checker to confirm the issue is resolved.

Check my domain

Common mistakes

  • Only adding the mailto: without a one-click HTTPS URL. Gmail requires the one-click URL for the requirement to be met.
  • Adding the header but not building the unsubscribe endpoint. The URL must actually work and process the unsubscribe.
  • Using the header only on marketing emails but not transactional. Bulk transactional email can also benefit.
  • Not adding List-Unsubscribe-Post. This is the one-click signal that Gmail and Yahoo specifically require.

Frequently asked questions

Is List-Unsubscribe required for all emails? +

Gmail and Yahoo require it for senders sending more than 5,000 emails per day to their platforms. Below that threshold it is best practice, not a hard requirement. Transactional emails (receipts, password resets) are generally exempt.

What is the difference between List-Unsubscribe and an unsubscribe link in the email body? +

They are separate and both are recommended. The List-Unsubscribe header enables Gmail and Yahoo to show a native unsubscribe option in their UI above the email. A link in the body is still required for users who read the email directly. Include both.

What happens if I do not add List-Unsubscribe? +

Inbox providers may suppress the native unsubscribe UI, leaving recipients with no easy way to opt out. This increases spam complaint rates. For bulk senders, Gmail and Yahoo can apply stricter filtering to senders who do not comply with the header requirement.

Related fix guides