AGENT SKILL

twilio-sendgrid-suppressions

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).

License 许可
MIT
最近更新
2026-07-19
Stars
★ 1
Forks
1

01 前言 Front Matter

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).

02 资源文件 1

03 SKILL.md 正文

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

04 同仓库更多 Skills

zfifteen
zfifteen/skills-catalog

Zotero

Use Zotero Desktop from Codex to enable/probe the local API, search a local Zotero library, list items/collections/tags, export BibTeX, insert citation keys into LaTeX or Markdown drafts, read indexed full text when requested, and import BibTeX/RIS records into Zotero through the connector server. Use when the user mentions Zotero, citations, references.bib, BibTeX export, local Zotero API, localhost:23119, or adding citations from a Zotero library.

★ 1
zfifteen
zfifteen/skills-catalog

zoom-apps-sdk

Use when using Apps SDK.

★ 1
zfifteen
zfifteen/skills-catalog

youtube

Obtain accurate, timestamped YouTube video transcripts (preferring manual captions over auto-generated) as the primary deliverable, then derive summaries, key claims, or notes from that transcript. Use when the user provides a YouTube URL (or video ID) and wants the transcript, a faithful summary, key claims with attribution, timestamped notes, or "what does this video actually say". The skill is transcript-first: never substitute metadata, title, description, or search snippets for the spoken content. Triggers: "youtube transcript", "get the transcript of this video", "summarize this youtube video", "what did they say in https://youtube.com/...", "key claims from this talk".

★ 1
zfifteen
zfifteen/skills-catalog

yeet

Publish local changes to GitHub by confirming scope, committing intentionally, pushing the branch, and opening a draft PR through the GitHub app from this plugin, with `gh` used only as a fallback where connector coverage is insufficient.

★ 1
zfifteen
zfifteen/skills-catalog

x-post-creator

Create X-ready post threads and co-located story packages from the active conversation or referenced project material. Use when the user says turn this into an X-post, /x-post, make this into an X thread, or wants plain-language social posts with supporting images saved to docs/x-posts/[story-name]/.

★ 1
zfifteen
zfifteen/skills-catalog

x-api

Search, read, and write X posts through the local X API MCP server (the same backend used by the Codex x-api skill). Use for searching X/x.com, reading threads and replies, creating lists, staging/publishing posts for @alltheputs, finding high-visibility reply targets for research outreach, ingesting public context, or any request that mentions /x-api or "search X".

★ 1