SendGrid one-click unsubscribe: headers, subscription tracking, and validation

SendGrid can add one-click unsubscribe to marketing email in two ways. Enable Subscription Tracking and SendGrid automatically adds List-Unsubscribe plus List-Unsubscribe-Post: List-Unsubscribe=One-Click; or supply the headers when sending through its API or SMTP path. Send a real test and inspect its raw headers. A valid pair does not guarantee that a mailbox provider will show its Unsubscribe control.

Who is affected?

This page is for an operator sending marketing or subscribed mail through Twilio SendGrid. It covers the header pair and SendGrid's documented ways to produce it. It does not configure a recipient mailbox, replace consent management, or cover SendGrid Domain Authentication. For the latter, use the separate guide to SPF and DKIM for SendGrid.

List-Unsubscribe is an email header. A mailbox may use it to offer an unsubscribe action near the sender. The visible link inside the message body is a different element. SendGrid says its list-unsubscribe header does not replace the standard unsubscribe functionality in the email body, and Subscription Tracking can place an [unsubscribe] substitution tag in that body. See the SendGrid List-Unsubscribe documentation for its feature behavior.

For the vendor-neutral protocol details, including endpoint handling and DKIM requirements, read our RFC 8058 one-click unsubscribe explainer. This SendGrid page stays focused on the configuration choice and the evidence to inspect.

What are the requirements?

SendGrid Subscription Tracking adds the pair

When Subscription Tracking is enabled, SendGrid documents that it inserts List-Unsubscribe with an HTTPS unsubscribe link and List-Unsubscribe-Post with List-Unsubscribe=One-Click into text and HTML email. The same source says that the body link can be positioned with the [unsubscribe] substitution tag. That is the simpler path when SendGrid's subscription-tracking behavior matches how your sending program manages opt-outs.

Manual headers remain a separate sending path

SendGrid also documents manual headers for v3 Mail Send, v2 Mail Send, and SMTP. This can be useful when you do not use Subscription Tracking, but it makes the owner of the endpoint and unsubscribe processing responsible for the full behavior. Its examples show both the post header and a List-Unsubscribe field with mailto: and HTTPS values. Do not copy the documentation's example address or URL into production. Use values and an endpoint that belong to your own unsubscribe workflow.

List-Unsubscribe: <https://unsubscribe.example.invalid/request/<recipient-token>>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The example is illustrative only. RFC 8058 says the List-Unsubscribe field MUST contain one HTTPS URI, MAY contain non-HTTP/S URIs such as mailto:, and the post field MUST contain the single value shown above. It also requires a valid DKIM signature that covers both fields. Read RFC 8058 section 3.1 and section 4 before implementing a self-managed endpoint.

A valid header pair does not control mailbox display

Twilio notes that developers may not see a one-click unsubscribe button even after implementing the headers correctly. Mailbox providers decide which messages show their control. Treat that as a presentation decision outside SendGrid's configuration. The reliable first check is the emitted header pair, followed by a safe, real opt-out test in a non-production recipient or test list.

Google's subscription guidelines say that bulk senders must support one-click unsubscribe for marketing and subscribed messages, and that unsubscribe requests should be processed within 48 hours. Those guidelines establish recipient-provider scope; they do not promise display for every individual message. For the complete Gmail and Yahoo context, use the bulk sender requirements checklist.

When does the requirement take effect?

RFC 8058 is an IETF Standards Track document published in January 2017. Its rules are stable protocol requirements, but a mailbox provider's sender policy and control-display logic can change. This SendGrid behavior and Google's subscription guidance were checked on July 29, 2026. Recheck the vendor and provider documentation when changing a campaign workflow or investigating a provider warning.

How do I implement the requirement?

1. Choose the configuration owner

Choose Subscription Tracking when SendGrid should insert the headers and handle the associated subscription-tracking workflow. Choose manual headers only when your application or another system owns the HTTPS endpoint and the opt-out process. This is an operational choice, not an RFC requirement to use a particular SendGrid feature.

2. Preserve the body unsubscribe route

Keep a visible unsubscribe route in the message body. If you use Subscription Tracking, SendGrid documents the [unsubscribe] substitution tag for controlling where its body link appears. If you supply manual headers, ensure your message template and consent workflow still provide the required body experience for the providers and jurisdictions relevant to you.

3. Send a test through the production-equivalent path

Send a test through the same SendGrid path used in production: the marketing workflow, API integration, or SMTP relay. A test from another application or a different SendGrid account can confirm only that other path. Do not test a live recipient's opt-out flow without authorization.

How do I validate compliance?

1. Inspect the raw delivered message

Open the raw source of the message and look for both headers. Confirm that List-Unsubscribe includes the expected HTTPS URI and that List-Unsubscribe-Post exactly contains List-Unsubscribe=One-Click. If you control DKIM signing, also confirm that the signature covers both header fields as RFC 8058 requires. A delivered-message header analyzer can help inspect authentication evidence, but raw header review remains necessary for the list-unsubscribe pair.

2. Match the result to the chosen SendGrid path

For Subscription Tracking, the header pair should be present on the text and HTML message SendGrid sends. For manual headers, compare the delivered values with the headers your API or SMTP code supplied. A mismatch points to the actual sending path or message construction, not to a generic DNS problem.

3. Test the endpoint without assuming mailbox UI behavior

Use a controlled test recipient or test list to verify that an opt-out reaches the appropriate suppression or subscription system. The header pair alone cannot prove that the endpoint processed a recipient. Conversely, an absent mailbox control does not, by itself, prove SendGrid omitted the headers because the mailbox provider controls that display.

Review the rest of your sender requirements

After confirming the headers, compare the same sending program against the Gmail and Yahoo sender-requirements checklist. That checklist covers the surrounding bulk-sender requirements. It cannot inspect private SendGrid headers, trigger the unsubscribe endpoint, or prove a provider's display decision.

Review the bulk sender requirements