twilio-sendgrid-suppressions
GitHub管理SendGrid邮件屏蔽记录，包括硬/软退信、拦截、垃圾邮件报告及取消订阅。涵盖API操作示例、ASM分组管理及自动清理设置，用于调试投递问题或构建退订流程。
Trigger Scenarios
Install
npx skills add fanfan-de/anybox --skill twilio-sendgrid-suppressions -g -y
SKILL.md
Frontmatter
{
"name": "twilio-sendgrid-suppressions",
"description": "Manage SendGrid email suppressions: bounces, blocks, spam reports, invalid emails, global unsubscribes, and ASM suppression groups. Covers when and how to remove suppressions, reputation impact, and category-based unsubscribe management. Use when debugging SendGrid delivery issues or building unsubscribe flows. Requires a SendGrid API key (SG.-prefix) — not applicable to the Twilio Email API (comms.twilio.com)."
}
Overview
Suppressions prevent SendGrid from sending to addresses that have bounced, reported spam, or unsubscribed. They protect your sender reputation but can also block legitimate re-sends if not managed correctly.
Suppression Types
| Type | Endpoint | What triggers it | Auto-added? |
|---|---|---|---|
| Hard Bounces | /v3/suppression/bounces |
Permanent delivery failure (invalid mailbox, domain doesn't exist) | Yes |
| Soft Bounces | No management API — automatic retry only | Temporary failure (mailbox full, server down) — SendGrid auto-retries before suppressing | Yes, after repeated failures |
| Blocks | /v3/suppression/blocks |
Temporary rejection by receiving server (reputation, policy, content) | Yes |
| Spam Reports | /v3/suppression/spam_reports |
Recipient marks email as spam | Yes |
| Invalid Emails | /v3/suppression/invalid_emails |
Malformed email address | Yes |
| Global Unsubscribes | /v3/suppression/unsubscribes |
Recipient unsubscribes from all email | Yes |
| Group Unsubscribes (ASM) | /v3/asm/groups/{id}/suppressions |
Recipient unsubscribes from a category | Yes |
Hard vs Soft bounces: Hard bounces (permanent) immediately suppress the address. Soft bounces (temporary) trigger retries — SendGrid will retry delivery before eventually suppressing if the issue persists.
Managing Suppressions
List bounces (Python)
import os, requests
headers = {"Authorization": f"Bearer {os.environ['SENDGRID_API_KEY']}"}
response = requests.get("https://api.sendgrid.com/v3/suppression/bounces", headers=headers)
for bounce in response.json():
print(f"{bounce['email']}: {bounce.get('reason', 'unknown')}")
Remove a bounce (Python)
requests.delete(f"https://api.sendgrid.com/v3/suppression/bounces/{email}", headers=headers)
Caution: Deleting suppression records (especially spam reports) allows re-sending to addresses that previously complained. Always confirm with the user before removal and document the business reason.
ASM Suppression Groups
Use suppression groups for category-based unsubscribes (e.g., "Marketing", "Transactional", "Product Updates"). Recipients can unsubscribe from one category without being suppressed from all email.
Create a group:
requests.post("https://api.sendgrid.com/v3/asm/groups",
headers={**headers, "Content-Type": "application/json"},
json={"name": "Marketing Emails", "description": "Promotional offers and updates"})
Send with a suppression group:
Include asm.group_id in your Mail Send request. Recipients see a "manage preferences" link instead of a global unsubscribe.
Auto-Purge (Bounce & Block Cleanup)
Configure automatic purge schedules in Console > Settings > Mail Settings > Purge Bounces & Blocks:
- Soft Bounces: Auto-purge after N days (1–3,650 days)
- Hard Bounces: Auto-purge after N days (1–3,650 days)
Caution: Enabling auto-purge without a business reason allows re-sending to previously bounced addresses, which damages sender reputation. Do not use as a workaround to force delivery.
Address Allow List
Console > Settings > Mail Settings > Address Allow List allows specific email addresses or domains to bypass all suppressions. Useful for internal testing addresses.
Use with extreme caution — never allowlist domains you don't control (e.g., gmail.com), and never use to bypass spam report suppressions.
CANNOT
- Suppressions are global by default — A bounce or spam report on ANY email suppresses the address from ALL future sends. Use ASM groups to scope unsubscribes.
- Removing a suppression does not fix the underlying issue — Deleting a bounce record lets you retry, but the mailbox is likely still invalid. Re-sending to hard bounces damages sender reputation.
- Cannot prevent spam report suppressions — When a recipient marks you as spam, the suppression is automatic and cannot be overridden.
- Cannot bulk-remove suppressions by domain — Must remove individually by email address via API.
Next Steps
- Send email:
twilio-sendgrid-email-send - Delivery tracking:
twilio-sendgrid-webhooks - Account setup:
twilio-sendgrid-account-setup
Version History
- 08dc189 Current 2026-07-05 19:10
