Overview
In 2024, Google started rolling out their new email sender requirements to protect their users from spam. SendGrid created a blog article here to address the requirements and explain them in more detail. As part of the requirements, List-unsubscribe and List-Unsubscribe-Post headers are needed to be included in sent emails--which includes messages sent via SendGrid.
List-Unsubscribe and List-Unsubscribe-Post headers are either added automatically by SendGrid or must be manually added when sending, depending on how email is sent with the account:
What You Need To Know
When SendGrid automatically adds the headers
If you enable SendGrid’s subscription tracking option (found via "settings > tracking > subscription tracking"), SendGrid will automatically add an unsubscribe option to the bottom of every message sent via SMTP or web API (v2 or v3). Additionally, this will automatically satisfy new requirements previously mentioned as SendGrid will also (with this subscription tracking option being enabled) insert the List-Unsubscribe and List-Unsubscribe-Post headers. With this setting not enabled, the list headers will need to be enabled yourself (see below).
If sending with Marketing Campaigns (as opposed to SMTP or web API), SendGrid will also try to include the headers as well. This always happens when using Marketing Campaigns. However, the only exception with Marketing Campaigns and the included headers is if, specifically, global or group unsubscribes are not used--and instead custom unsubscribe links are used (this is uncommon). See below for this exception.
When you need to add the headers
If you are sending via SMTP or web API (v2 or v3), you may need to include instructions to add list unsubscribe headers to your mail sending. Particularly, this is applicable if you do not have subscription tracking ("settings > tracking > subscription tracking") enabled on your account or mail send payloads.
We have help documentation on how add headers to mail send for SMTP and web API here.
While uncommon, if you send with Marketing Campaigns and also use the "custom unsubscribe link" option (this means you are not defining unsubscribes to be global or group unsubscribes but managing them on your own), the headers are still included in the mail send. However, your team will also be responsible for specifically managing complaint information as it routes via the "list-unsubscribe" header value.
Example Payload with Headers for Web API
Here is an example of how the list headers look:
{
"List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
"List-Unsubscribe": "<mailto:unsubscribeexampexample@example.com>, <https://www.unsubscribe.example.com/>"
}Both the 'List-Unsubscribe-Post' and 'List-Unsubscribe' headers can be included in your SendGrid outbound emails using the API. This is done by setting these headers within the Personalizations. Specifically, they are defined within the headers object of the mail send API call. Please refer to the JSON payload shared below and also the corresponding signature :
{
"personalizations": [{
"to": [{
"email": "sendgridtesting@gmail.com",
"name": "SG"
}],
"headers": {
"List-Unsubscribe": "<mailto:unsubscribeexampexample@example.com>, <http://www.unsubscribe.example.com/>",
"List-Unsubscribe-Post": "<mailto:unsubscribeexampexample@example.com>, <http://www.unsubscribe.example.com/>"
}
}],
"from": {
"email": "whatever@xyz.co.in",
"name": "hello World"
},
"subject": "Test document",
"content": [{
"type": "text/plain",
"value": "Hello World"
}]
}
Here is a screenshot when viewing the resulting message that comes from the above payload after it is executed and generates an email to an inbox:
While the new requirements indicate a simple one-click unsubscribe feature to be compulsory, it is not specifically stated that this has to be achieved via a 'list-unsubscribe' header. However, this header is an industry standard mechanism to streamline the unsubscribe process and aligns well with the notion of a 'one-click unsubscribe' feature. This approach leverages the convenience and user-friendly nature of a one-click unsubscribe process, thereby enhancing the recipient's experience. It also serves as an effective practice to maintain a healthy sender reputation.