SendGrid (now Twilio SendGrid) is a developer-first transactional and marketing email platform organizing unsubscribes through the Advanced Suppression Manager (ASM) with Groups and Global suppression tiers. The unsubscribe mechanism uses <%asm_group_unsubscribe_url%> for group-level opt-out or <%asm_global_unsubscribe_url%> for account-wide opt-out. SendGrid emits RFC 8058 headers automatically for authenticated domains. This guide covers the substitution tags, the ASM Group model, and how to verify the setup end to end.
SendGrid unsubscribe link
| Tag syntax | <%asm_group_unsubscribe_url%> |
| Alternative | <%asm_global_unsubscribe_url%> |
| Placement | Auto in Marketing Campaigns, manual asm.group_id for API |
| Scope | Per ASM Group with Global Unsubscribe override |
| Config path | Marketing > Suppressions > Unsubscribe Groups |
| RFC 8058 one-click | Yes, automatic for authenticated domains with ASM group configured |
How to add the unsubscribe tag in SendGrid
Place the merge tag exactly as shown below in the email template. SendGrid replaces it at send time with a signed URL scoped to the recipient and campaign.
<%asm_group_unsubscribe_url%>For custom HTML templates, wrap the tag in an anchor to render a proper hyperlink in the delivered email:
<a href="<%asm_group_unsubscribe_url%>">Unsubscribe from this list</a>Auto in Marketing Campaigns, manual asm.group_id for API
Yes, automatic for authenticated domains with ASM group configured The recipient's mailbox provider (Gmail, Yahoo) uses the List-Unsubscribe-Post header to expose the native one-click button on the message. Requires domain authentication with DKIM and DMARC.
SendGrid transactional API sends without an ASM group in the payload bypass suppression entirely, intended for password resets and order confirmations. Sending bulk marketing content without an ASM group violates SendGrid policy and risks account review. Always include the asm object with group_id in marketing sends via the API.
Testing your SendGrid unsubscribe link
- Send a test message to a controlled Gmail address you own via the SendGrid campaign preview action
- Click the footer unsubscribe link and confirm the opt-out on the landing page
- Check the subscriber or contact record: the status should be Unsubscribed within seconds
- Verify the RFC 8058 headers in Gmail: open the message, click three dots, then Show original. Look for
List-UnsubscribeandList-Unsubscribe-Post: List-Unsubscribe=One-Click
Want the full 222-platform reference?
See the pillar guide with the compliance landscape, the RFC 8058 deep dive, and the unsubscribe tag for every ESP: How to add an unsubscribe link: the complete 2026 guide →
How to add the SendGrid unsubscribe link (step by step)
SendGrid Marketing Campaigns templates include a default unsubscribe footer, but transactional sends via the API require explicit group configuration through the ASM payload.
- Create a Suppression Group in Marketing > Suppressions > Unsubscribe Groups. Assign a name and description that will show on the SendGrid preference center.
- Note the Group ID (integer) returned after creation. This is passed to the API for transactional sends.
- In the campaign or template, insert the substitution tag
<%asm_group_unsubscribe_url%>for group-level opt-out. - Wrap in an anchor:
<a href="<%asm_group_unsubscribe_url%>">Unsubscribe</a>. For account-wide opt-out use<%asm_global_unsubscribe_url%>instead. - For transactional API sends, include the ASM payload:
"asm": {"group_id": 12345, "groups_to_display": [12345, 67890]}. - Send a test to a seed address and verify the rendered link routes to the SendGrid preference center showing the correct group.
Advanced Suppression Manager Groups
The ASM Groups model separates unsubscribes by content category: a subscriber can opt out of Promotional emails while remaining subscribed to Weekly Digest and Account Notifications. Each group has a numeric ID passed via the asm.group_id field in the API. The groups_to_display array controls which groups appear on the preference center: subscribers see checkboxes for each and can granularly opt in or out. Global Unsubscribe is a separate flag that suppresses all sends regardless of group.
RFC 8058 one-click headers
SendGrid added RFC 8058 one-click unsubscribe automatically in 2024. The List-Unsubscribe and List-Unsubscribe-Post headers are injected on marketing sends from domains completed under Sender Authentication (SPF and DKIM verified). For transactional API sends, the ASM group in the payload triggers automatic header injection when the sending domain is authenticated. Domains without Sender Authentication fall back to shared sendgrid.net infrastructure and may not qualify for one-click.
Transactional vs marketing suppression
SendGrid distinguishes marketing suppression (managed by ASM Groups and Global Unsubscribes) from transactional bounce and complaint suppression. A subscriber unsubscribed from a Promotional group can still receive Account Notifications from a separate group, and transactional messages sent without any ASM group are exempt entirely. This design lets developers keep password resets and receipts flowing while honoring marketing opt-outs. Sending bulk marketing content without an ASM group is a policy violation and risks account review.
Frequently Asked Questions
What is the SendGrid unsubscribe tag?
Use <%asm_group_unsubscribe_url%> for group-level opt-out and <%asm_global_unsubscribe_url%> for account-wide opt-out. These are substitution tags that SendGrid replaces at send time with a signed URL unique per recipient and group combination.
What is the difference between group and global unsubscribe?
Group unsubscribe removes the recipient from a specific ASM Group (like Promotional or Newsletter), preserving subscription to other groups. Global unsubscribe suppresses the address across every group in the account. Global is the safer default for single-brand senders that do not need category-level opt-out.
Does SendGrid support one-click unsubscribe for Gmail and Yahoo?
Yes, automatically for domains with Sender Authentication completed. SendGrid injects List-Unsubscribe and List-Unsubscribe-Post headers on every marketing send with an ASM group configured, satisfying the Google and Yahoo bulk-sender requirements.
How do I set the ASM group in a transactional API call?
Include the ASM object in the message payload: "asm": {"group_id": 12345, "groups_to_display": [12345, 67890]}. The group_id triggers unsubscribe suppression check and the groups_to_display array populates the preference center checkboxes.
Can transactional messages bypass ASM suppression?
Yes, by omitting the ASM object from the payload. Sends without any ASM group bypass suppression entirely, intended for password resets, order confirmations, and other essential transactional messages. Do not use this pattern for marketing content, as SendGrid policy requires marketing sends to honor unsubscribes.
About the Author
Alaa · LinkedIn
Email infrastructure specialist with 8+ years of hands-on experience in SMTP, deliverability, and email verification. I’ve configured and troubleshot mail systems across Postfix, Exchange, and cloud relays, managed IP reputation and warmup campaigns, and built verification pipelines processing millions of addresses. My work spans DNS authentication (SPF, DKIM, DMARC, BIMI), bounce handling, blocklist monitoring, and compliance frameworks including CAN-SPAM and GDPR. I write every article on SMTPedia to give email professionals, developers, and marketers the accurate, RFC-grounded reference they need.
About SMTPedia
SMTPedia is an independent email industry reference covering SMTP, IMAP, POP3, email deliverability, marketing platforms, DNS authentication, and email verification. Every article is researched from official provider documentation, IETF RFCs, and industry best practices. Settings and configurations are verified quarterly.
We are cited as a source by ChatGPT, Microsoft Copilot, and thousands of email professionals worldwide. Learn more about our editorial process.
