Skip to:

Opened 19 months ago

Closed 18 months ago

Last modified 17 months ago

#7390 closed enhancement (fixed)

Support List-Unsubscribe header in emails

Reported by: DJPaul Owned by: djpaul
Milestone: 2.8 Priority: normal
Severity: normal Version:
Component: Emails Keywords: good-first-bug has-patch dev-feedback
Cc: patel4net@…


Add the List-Unsubscribe header to the emails sent by BuddyPress.

Since 2.7 added true support for unsubscribe links, we can add these links to our email headers, allowing users to easily/automate to unsubscribe that kind of email notification in some email clients such as Gmail (web) and Windows Live (web).

If you don't use Gmail or haven't seen it before, you get this prompt when clicking on the "spam" button:

Attachments (3)

7390.patch (732 bytes) - added by chiragpatel 19 months ago.
Unsubscribe email
7390.2.patch (735 bytes) - added by chiragpatel 19 months ago.
Applied the latest changes as per suggestions.
7390.03.patch (887 bytes) - added by r-a-y 18 months ago.

Download all attachments as: .zip

Change History (25)

#1 @johnjamesjacoby
19 months ago

This seems like a great addition to Emails.

#2 @DJPaul
19 months ago

We already add some custom headers to emails in the bp_email_set_default_headers() function so it should be easy to add more. There is some basic documentation on the format at, and you can compare to the headers of a email in Gmail (that offers you this report/unsubscribe option).

Please also test this in Gmail. I am 99% sure this is the header that Gmail uses for this, but I couldn't find a definitive source to be absolutely sure.

#3 @chiragpatel
19 months ago

I am working on it, I will confirm with @DJPaul and update here.

19 months ago

Unsubscribe email

#4 @chiragpatel
19 months ago

  • Cc patel4net@… added
  • Keywords has-patch added

I added path for unsubscribing email bp_email_set_default_headers() in bp-core-filters.php Pleaes review it and share your feedback here.

#5 @chiragpatel
19 months ago

  • Keywords dev-feedback 2nd-opinion added

#6 @DJPaul
19 months ago

Thanks for the patch, @chiragpatel. Feedback:

  • You don't need to include the colon. BuddyPress takes care of that somewhere else when it builds the headers.
  • We can't support an email-based (mailto) unsubscribe mechanism. Please just use the web-based mechanism (i.e. the unsubscribe token).
  • If you look at bp_email_set_default_tokens(), you will see token is set to site_url( 'wp-login.php' ) in certain situations.
    • We obviously can't use that link as the unsubscribe mechanism.
    • I would suggest something like if ( ! empty( $tokens['unsubscribe'] ) && $tokens['unsubscribe'] !== site_url( 'wp-login.php' ) ) {
  • Did you test this in Gmail to verify the change works as expected?

#7 @chiragpatel
19 months ago

Thank you @DJPaul, As per your suggestions we will work on it and update here. Thanks again !!

#8 @chiragpatel
19 months ago

Hello @DJPaul

The unsubscribe link not shows for all the senders. Please see the link: and yes, List-Unsubscribe attribute support "mailto: not any "http" link (If you have any suggestion let me know)?

Yes for "would suggest something like if ( ! empty( $tokensunsubscribe? ) && $tokensunsubscribe? !== site_url( 'wp-login.php' ) ) {" -- I will add it once we submit the final patch.

Do let us know your suggestions for the same.

#9 @DJPaul
19 months ago

RE: Testing - fair enough. We can at least verify the header is in the email. says the spec does allow HTTP links.

#10 @chiragpatel
19 months ago

Thank you @DJPaul for prompt answer. Our code output look like below:

$headers['List-Unsubscribe'] = '<>,<>

#11 @chiragpatel
19 months ago

Or I pass like below:

$headers['List-Unsubscribe'] = '<>';

#12 @DJPaul
19 months ago is correct because that removes the unsubscribe email address (which as I said previously, we don't have).

19 months ago

Applied the latest changes as per suggestions.

This ticket was mentioned in Slack in #buddypress by chiragpatel. View the logs.

19 months ago

18 months ago

#14 @r-a-y
18 months ago

  • Keywords 2nd-opinion removed

The URL in the List-Unsubscribe header needs to be raw URL-decoded.

2.patch uses the URL from the {{unsubscribe}} token, which is meant to be used in HTML emails and is URL-escaped. This means that the 'List-Unsubscribe' URL will not work correctly.

03.patch fixes this up.

#15 @DJPaul
18 months ago

Very nice catch with the HTML-encoded URL.

#16 @DJPaul
18 months ago

(Before anyone else asks, yes, this won't support multiple recipients (on the TO line) but neither does almost everywhere else we send email in BuddyPress, so that's an edge case I am not worried about at the moment).

This ticket was mentioned in Slack in #buddypress by djpaul. View the logs.

18 months ago

#18 @djpaul
18 months ago

  • Owner set to djpaul
  • Resolution set to fixed
  • Status changed from new to closed

In 11395:

Emails: add List-Unsubscribe header to emails.

The List-Unsubscribe header is an optional chunk of text that email publishers can include in the header portion of the messages they send. In supported email clients, like some versions of Outlook, Gmail, and Apple Mail, recipients will see an Unsubscribe button they can click if they would like to automatically stop future messages.

Fixes #7390

Props chiragpatel, r-a-y.

#19 @rogercoathup
18 months ago

@djpaul -- can you clarify a couple of things on how this works in BP:

Does it only unsubscribe from that particular type of notification? i.e. will the recipient continue to receive other types of email notification from the site?

Does the user have to login to complete the unsubscribe, or do they merely have to click the unsubscribe button?

Last edited 18 months ago by rogercoathup (previous) (diff)

#20 @DJPaul
18 months ago

Sure. The unsubscribe links (this one, and the one that pre-exists in the footer of the email templates) unsubscribe the recipient from that particular type of notification. User does not have to log-in to complete the unsubscribe. The logic for this process is in bp_email_unsubscribe_handler().

This ticket was mentioned in Slack in #buddypress by slaffik. View the logs.

17 months ago

#22 @r-a-y
17 months ago

There's been some discussion about this feature recently in Slack:

To summarize:

  • GMail (web client) will only show the "Unsubscribe" link for reputable senders. The exact algorithm for when the link is visible is not quite known. But if you're using a well-known email provider such as SparkPost, SendGrid, etc. that signs emails with DKIM, this should make things easier. Some more info can be found here.
  • and Apple iOS Mail 10 does not support HTTP URLs for the List-Unsubscribe header (which is what we are using), so the "Unsubscribe" link will not show up in these clients.
  • The Thunderbird email client supports this via an addon -
Last edited 17 months ago by r-a-y (previous) (diff)
Note: See TracTickets for help on using tickets.