List-Unsubscribe

List-Unsubscribe is a small piece of text that can be inserted in the header section of your email. The List-Unsubscribe header will insert an “unsubscribe” button, or link, next to the From address at the top of your email. A recipient can click this link to notify you that they would like to unsubscribe from your emails.

{
  "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
  "List-Unsubscribe": "<mailto:unsubscribeexampexample@example.com>, <https://www.unsubscribe.example.com/>"
}

SendGrid’s Subscription Tracking

If you enable SendGrid’s subscription tracking feature, SendGrid will automatically insert the List-Unsubscribe header in all of your text and HTML emails— placing an HTTPS unsubscribe link in all of your emails. Additionally, SendGrid will insert a List-Unsubscribe-Post header with List-Unsubscribe=One-Click.

You can also place the substitution tag [unsubscribe] anywhere in the body of your email to specify the exact location where you want the unsubscribe link to appear. You may customize this tag and the message inserted during the substitution. For more information, see our subscription tracking documentation.

It is possible to use the List-Unsubscribe header even if you do not want to use subscription tracking. This is useful for users who want to provide their recipients an easy way to unsubscribe from their emails without relying on SendGrid’s tracking features. Continue reading below for an explanation of the both headers, and how you can use it when sending email via SendGrid.

How does the List-Unsubscribe header work?

The List-Unsubscribe header provides two methods of unsubscribing users: an email unsubscribe, and a web unsubscribe. Both of these methods should be used to comply with various inbox providers.

Web Unsubscribe: https

The https portion of the List-Unsubscribe header allows you to specify a URL that will receive a POST whenever someone clicks the unsubscribe link in your email. Inboxes such as Gmail and Yahoo! require a valid https unsubscribe link in the headers of marketing emails.

Email Unsubscribe: mailto

The mailto portion of the List-Unsubscribe header allows you to specify an email address that will receive the unsubscribe request. In other words, when a recipient clicks the “unsubscribe” link in your email, the recipient’s mail client will send an email to this address.

It is your responsibility to receive and process these generated emails.

How does the List-Unsubscribe-Post header work?

Inboxes such as Gmail and Yahoo! require all marketing email to contain a List-Unsubscribe-Post header with the value List-Unsubscribe=One-Click. This header communicates that the unsubscribe method is one click via a POST request. Additionally, anti spam software may issue GET requests to links in emails. To prevent accidental unsubscribes, add an additional step so that the GET request to that link does not unsubscribe someone. As an example, you could make the GET request to the link present a landing page to the user containing a link or button to confirm the unsubscribe. A POST request to this link, such as that generated through the one click unsubscribe in the email header, should result in an unsubscribe.

Which method should I use?

You must include both the mailto and https portions of the List-Unsubscribe header, since different inboxes either only support mailto (iOS, for example) or require https (Gmail and Yahoo!).

Not honoring your recipients’ unsubscribe requests could not only harm your sender reputation, but could also violate legislation laid out in CAN-SPAM, CASL, and other legislation. For more information about deliverability best practices and compliance, please visit our Deliverability Overview.

Examples

Using List-Unsubscribe with v3 Mail Send

{
  "personalizations": [
    {
      "to": [
        {
          "email": "example@example.com"
        }
      ],
      "subject": "Your subject line here"
    }
  ],
  "from": {
    "email": "example@example.com"
  },
  "content": [
    {
      "type": "text/plain",
      "value": "Hello, World!"
    }
  ],
  "headers": {
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
    "List-Unsubscribe": "<mailto:unsubscribeexampexample@example.com>, <https://www.unsubscribe.example.com>"
  }
}

Using List-Unsubscribe with v2 Mail Send

api_user=your_sendgrid_username&
api_key=your_sendgrid_password&
to=destination@example.com&
toname=Destination&
subject=Example_Subject&
text=testingtextbody&
from=info@domain.com&
"headers": {"List-Unsubscribe-Post": "List-Unsubscribe=One-Click", "List-Unsubscribe": "<mailto:unsubscribeexampexample@example.com>, <https://www.unsubscribe.example.com>"}

List-Unsubscribe with SMTP

{
  "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
  "List-Unsubscribe": "<mailto:unsubscribeexampexample@example.com>, <https://www.unsubscribe.example.com/>"
}