X Openai Twilio Sendgrid Suppressions 40288ef

---
name: x-openai-twilio-sendgrid-suppressions-40288ef
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).'
---

### 导出副本边界与技能别名

迁移、安装、修复和经验回写只作用于当前加载的目标宿主技能副本。原 Codex 技能/MCP、下载的源码和 `original-skills` 均为来源材料，不因执行本副本而写入；只有用户另行明确要求配置 Codex 产品本身时，才按该产品流程处理指定目标。脚本需要安装目录或状态目录时，显式提供目标路径；不得从 `CODEX_HOME` 隐式推断写入位置。

跨技能名称可能沿用源库别名。先查 [技能别名表](../../skill-aliases.json)，优先选择同来源、同插件的条目，再使用其 `id` 调用或读取对应入口；不得假定旧 `$skill`、`superpowers:skill` 名称在新宿主直接注册。不能确定目标时先核对，不替换真实产品命令或 Shell 环境变量。

## 跨宿主使用约定

本副本供支持 Agent Skills 的客户端使用。先检查当前宿主实际提供的工具、权限和已连接服务，再执行正文工作流。原文中的宿主工具标识是能力参考；只有实际发现该工具时才可调用，其他宿主应使用经核验的等价 MCP、CLI 或 API。没有等价能力的步骤必须报告不可用，不能虚构调用或完成状态。

技能资源以本技能目录为基准；输出写入当前项目中用户指定的位置。通过技能名称或自然语言触发，具体快捷命令由宿主决定。涉及真实产品、模型 API、协议字段和官方网址的名称保持原意。授权、审批、隐私和工具范围限制在迁移后仍然有效；不得为兼容而扩大权限。具体依赖与迁移说明见同目录 `PORTABILITY.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)**
```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)**
```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:**
```python
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`