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.
1{2"List-Unsubscribe-Post": "List-Unsubscribe=One-Click",3"List-Unsubscribe": "<mailto:unsubscribeexampexample@example.com>, <https://www.unsubscribe.example.com/>"4}
Danger
It is important to note that the list-unsubscribe header is not a complete replacement for the standard unsubscribe functionality that should be included in the body of your email. For more information on adding unsubscribe links to the body of your email, see our Unsubscribe Groups documentation.
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.
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.
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.
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.
Danger
Failure to honor your recipients' unsubscribe requests may do more than damage your sender reputation. To learn more about deliverability and compliance, see our 2019 Email Deliverability Guide.
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.
Warning
When testing the implementation of one-click unsubscribe, developers may not see a one click unsubscribe button even if it has been implemented correctly. Inbox providers are the ultimate deciders of which emails will display a one click unsubscribe button next to the From address of the email. Low sender reputations can occasionally cause the one click unsubscribe button to not be displayed.
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.
1{2"personalizations": [3{4"to": [5{6"email": "example@example.com"7}8],9"subject": "Your subject line here"10}11],12"from": {13"email": "example@example.com"14},15"content": [16{17"type": "text/plain",18"value": "Hello, World!"19}20],21"headers": {22"List-Unsubscribe-Post": "List-Unsubscribe=One-Click",23"List-Unsubscribe": "<mailto:unsubscribeexampexample@example.com>, <https://www.unsubscribe.example.com>"24}25}
1api_user=your_sendgrid_username&2api_key=your_sendgrid_password&3to=destination@example.com&4toname=Destination&5subject=Example_Subject&6text=testingtextbody&7from=info@domain.com&8"headers": {"List-Unsubscribe-Post": "List-Unsubscribe=One-Click", "List-Unsubscribe": "<mailto:unsubscribeexampexample@example.com>, <https://www.unsubscribe.example.com>"}
1{2"List-Unsubscribe-Post": "List-Unsubscribe=One-Click",3"List-Unsubscribe": "<mailto:unsubscribeexampexample@example.com>, <https://www.unsubscribe.example.com/>"4}