# SendGrid one-click unsubscribe: headers, subscription tracking, and validation > Configure or verify SendGrid one-click unsubscribe with Subscription Tracking or custom headers, then inspect a delivered message. 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. ## Quick takeaways - [SendGrid Subscription Tracking](https://www.twilio.com/docs/sendgrid/ui/sending-email/list-unsubscribe) automatically inserts the HTTPS `List-Unsubscribe` header and the one-click post header into text and HTML mail. - SendGrid also documents manual `List-Unsubscribe` and `List-Unsubscribe-Post` headers for Mail Send and SMTP. - A visible unsubscribe link in the message body remains separate from the headers. - [RFC 8058](https://www.rfc-editor.org/rfc/rfc8058.html) requires an HTTPS URI, the exact post value, and valid DKIM coverage for its one-click mechanism. - Raw delivered headers prove what the sending path emitted. They do not prove that a mailbox will render its own control or that an opt-out endpoint processed a recipient. ## 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](/learning/how-do-i-set-up-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](https://www.twilio.com/docs/sendgrid/ui/sending-email/list-unsubscribe) for its feature behavior. For the vendor-neutral protocol details, including endpoint handling and DKIM requirements, read [our RFC 8058 one-click unsubscribe explainer](/learning/one-click-unsubscribe). 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. ```text List-Unsubscribe: > 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](https://www.rfc-editor.org/rfc/rfc8058.html) before implementing a self-managed endpoint. ![Flow from SendGrid Subscription Tracking or manual headers to raw delivered-header inspection, with mailbox display provider-controlled.](/images/editorial/sendgrid-one-click-unsubscribe/sendgrid-one-click-unsubscribe-decision-flow.svg "1200x820") *Source: Original Palisade decision flow based on [Twilio SendGrid's List-Unsubscribe documentation](https://www.twilio.com/docs/sendgrid/ui/sending-email/list-unsubscribe) and [RFC 8058](https://www.rfc-editor.org/rfc/rfc8058.html). It distinguishes configuration and evidence boundaries; it is not a SendGrid or mailbox interface. [Open the full-size diagram](/images/editorial/sendgrid-one-click-unsubscribe/sendgrid-one-click-unsubscribe-decision-flow.svg).* ### 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](https://support.google.com/mail/answer/15263077) 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](/learning/google-is-making-email-sender-requirements-stricter-starting-nov-2025). ## 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](/tools/email-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](/learning/google-is-making-email-sender-requirements-stricter-starting-nov-2025). 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](/learning/google-is-making-email-sender-requirements-stricter-starting-nov-2025) ## Sources and further reading - [Twilio SendGrid: List-Unsubscribe](https://www.twilio.com/docs/sendgrid/ui/sending-email/list-unsubscribe) - [RFC 8058: Signaling One-Click Functionality for List Email Headers](https://www.rfc-editor.org/rfc/rfc8058.html) - [Google: Email subscription guidelines](https://support.google.com/mail/answer/15263077) ## Frequently asked questions ### Does SendGrid Subscription Tracking add one-click unsubscribe headers? Yes. SendGrid documents that Subscription Tracking inserts both `List-Unsubscribe` with an HTTPS link and `List-Unsubscribe-Post: List-Unsubscribe=One-Click` into text and HTML email. ### Can I use custom headers instead of Subscription Tracking? Yes. SendGrid documents List-Unsubscribe headers for its Mail Send and SMTP paths. You must operate the endpoint and process the resulting opt-out requests correctly. ### Does a List-Unsubscribe header replace the visible unsubscribe link? No. SendGrid says its list-unsubscribe header does not replace standard unsubscribe functionality in the message body. Keep the body experience separate from the header mechanism. ### Why is the Gmail Unsubscribe control missing from my test? Mailbox providers decide whether to display their controls. Check the raw message for both headers before treating a missing control as a SendGrid configuration failure. ### Must the one-click endpoint accept a POST request? Yes. RFC 8058 defines the one-click action as an HTTPS POST to the HTTPS URI in `List-Unsubscribe`; it prohibits cookies, HTTP authorization, and HTTPS redirects for that POST flow.