SendGrid Suppression Groups: Manage Unsubscribes & Email Preferences

In this tutorial, you will learn about SendGrid Suppression Groups: Manage Unsubscribes & Email Preferences. We cover key concepts, practical examples, and best practices to help you master this topic.

SendGrid suppression groups let users manage their email preferences — opting out of specific email types (alerts, newsletters, promotions) while keeping others active.

What You'll Learn

How to create suppression groups, add unsubscribe links to emails, check suppression status before sending, programmatically manage suppressions, and comply with email regulations.

Why It Matters

Sending to unsubscribed users violates CAN-SPAM and damages sender reputation. DodaTech uses suppression groups so users can unsubscribe from marketing emails while keeping security alerts active.

Real-World Use

A user unsubscribes from "weekly promotions" but stays subscribed to "security alerts." The app checks suppression status before sending and respects the user's preference.

flowchart LR
    A["User Clicks\nUnsubscribe"] --> B["SendGrid\nSuppression Group"]
    B --> C["Group: alerts\nOpted OUT"]
    B --> D["Group: reports\nOpted IN"]
    C --> E["SendGrid Blocks\nAlert Emails"]
    D --> F["SendGrid Allows\nReport Emails"]
    style B fill:#dbeafe,stroke:#2563eb
    style E fill:#fecaca,stroke:#dc2626
    style F fill:#bbf7d0,stroke:#16a34a

Creating Suppression Groups

from sendgrid import SendGridAPIClient
import os

sg = SendGridAPIClient(os.environ["SENDGRID_API_KEY"])

def create_suppression_group(name, description):
    data = {
        "name": name,
        "description": description,
        "is_default": False
    }
    response = sg.client.asm.groups.post(request_body=data)
    group = response.to_dict()
    print(f"Created group: {group['name']} (ID: {group['id']})")
    return group

# Create groups for different email types
alerts = create_suppression_group("Security Alerts", "Critical security notifications about your account")
reports = create_suppression_group("Weekly Reports", "Weekly security scan summaries")
promotions = create_suppression_group("Promotions", "Product updates and special offers")
newsletter = create_suppression_group("Newsletter", "Monthly security tips and industry news")

# Expected output:
# Created group: Security Alerts (ID: 1)
# Created group: Weekly Reports (ID: 2)
# Created group: Promotions (ID: 3)

Sending with Suppression Group

from sendgrid.helpers.mail import Mail, Asm, GroupId, GroupsToDisplay

def send_with_unsubscribe(to_email, subject, body, group_id):
    message = Mail(
        from_email="noreply@dodatech.com",
        to_emails=to_email,
        subject=subject,
        html_content=body
    )

    # Attach suppression group
    message.asm = Asm(
        GroupId(group_id),
        GroupsToDisplay([group_id])
    )

    response = sg.send(message)
    print(f"Email with unsubscribe group: {response.status_code}")

# User will see "Unsubscribe from Security Alerts" in the email footer
send_with_unsubscribe(
    "alice@example.com",
    "Critical Security Alert",
    "<h1>Alert</h1><p>Threat detected on your device.</p>",
    group_id=1  # Security Alerts
)

Checking Suppression Status

def can_send_to_user(email, group_id):
    # Check if email is suppressed for this group
    params = {"recipient_emails": [email]}
    response = sg.client.asm.groups._(group_id).suppressions.get(query_params=params)
    suppressions = response.to_dict()

    if len(suppressions.get("recipient_emails", [])) > 0:
        print(f"User {email} is suppressed from group {group_id}")
        return False
    else:
        print(f"User {email} can receive group {group_id}")
        return True

# Before sending, check permission
if can_send_to_user("alice@example.com", 2):  # Weekly Reports
    send_with_unsubscribe("alice@example.com", "Your Weekly Report", "<h1>Report</h1>", 2)
# Expected output:
# User alice@example.com can receive group 2
# Email with unsubscribe group: 202

Managing Suppressions Programmatically

def add_suppression(email, group_id):
    data = {"recipient_emails": [email]}
    response = sg.client.asm.groups._(group_id).suppressions.post(request_body=data)
    print(f"Added {email} to group {group_id} suppress: {response.status_code}")

def remove_suppression(email, group_id):
    response = sg.client.asm.groups._(group_id).suppressions._(email).delete()
    print(f"Removed {email} from group {group_id}: {response.status_code}")

def list_all_suppressions(group_id):
    response = sg.client.asm.groups._(group_id).suppressions.get()
    print(f"Suppressions for group {group_id}:")
    for item in response.to_dict():
        print(f"  {item['email']} (created: {item['created']})")

# List all users who unsubscribed from alerts
list_all_suppressions(1)
# Expected output: Suppressions for group 1:
#                  alice@example.com (created: 2026-06-27)
#                  bob@example.com (created: 2026-06-25)

Common Mistakes

1. Not Using Suppression Groups

Sending without suppression groups means users can only globally unsubscribe. This blocks all email types instead of just the unwanted ones.

2. Checking Suppression After Sending

Always check suppression status before making the API call. Suppressed emails still count toward your send quota if the API accepts them.

3. Confusing Global vs Group Unsubscribes

Global unsubscribes block all email. Group unsubscribes block specific types. Use both: global for opt-out, groups for preference management.

4. Not Displaying Unsubscribe Links

CAN-SPAM requires a visible unsubscribe link in every commercial email. SendGrid adds it automatically when you use suppression groups.

5. Ignoring Suppression in Webhook Processing

When processing Event Webhooks, check for group_unsubscribe events to update your internal preference database.

Practice Questions

1. What is the difference between global and group suppression?
2. How do you add an unsubscribe link to an email?
3. How do you check a user's suppression status before sending?
4. How do suppression groups help with Compliance?

Answers:

1. Global suppression blocks all email from your account. Group suppression blocks specific email types, letting users choose which emails they receive.
2. Set the asm property on the Mail object with the group ID. SendGrid automatically adds the unsubscribe footer.
3. Use the Suppressions API GET /asm/groups/{group_id}/suppressions with the recipient email to check if they're suppressed.
4. Suppression groups provide granular unsubscribe options, satisfying CAN-SPAM requirements while preserving the ability to send critical transactional emails.

Challenge: Build a preference management system: create suppression groups for alerts, reports, and promotions, implement a preference page where users toggle each group, check suppression before sending each email type, and log group unsubscribe events from webhooks.

FAQ

Mini Project

Build an email preference system: create 4 suppression groups (alerts, reports, promotions, newsletter), implement a preference center API, send each email type with the correct ASM group, check suppression before sending, and sync webhook events with your database.

What's Next

Bounces & Blocks — handle undeliverable emails and protect sender reputation.