Update to Twilio Developer Kit

{
  "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).",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 237
    }
  ],
  "skill_md_contents": "---\nname: twilio-sendgrid-suppressions\ndescription: >\n  Manage SendGrid email suppressions: bounces, blocks, spam reports,\n  invalid emails, global unsubscribes, and ASM suppression groups.\n  Covers when and how to remove suppressions, reputation impact, and\n  category-based unsubscribe management. Use when debugging SendGrid\n  delivery issues or building unsubscribe flows. Requires a SendGrid API\n  key (SG.-prefix) — not applicable to the Twilio Email API (comms.twilio.com).\n---\n\n## Overview\n\nSuppressions 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.\n\n---\n\n## Suppression Types\n\n| Type | Endpoint | What triggers it | Auto-added? |\n|------|----------|-----------------|-------------|\n| **Hard Bounces** | `/v3/suppression/bounces` | Permanent delivery failure (invalid mailbox, domain doesn't exist) | Yes |\n| **Soft Bounces** | No management API — automatic retry only | Temporary failure (mailbox full, server down) — SendGrid auto-retries before suppressing | Yes, after repeated failures |\n| **Blocks** | `/v3/suppression/blocks` | Temporary rejection by receiving server (reputation, policy, content) | Yes |\n| **Spam Reports** | `/v3/suppression/spam_reports` | Recipient marks email as spam | Yes |\n| **Invalid Emails** | `/v3/suppression/invalid_emails` | Malformed email address | Yes |\n| **Global Unsubscribes** | `/v3/suppression/unsubscribes` | Recipient unsubscribes from all email | Yes |\n| **Group Unsubscribes (ASM)** | `/v3/asm/groups/{id}/suppressions` | Recipient unsubscribes from a category | Yes |\n\n**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.\n\n---\n\n## Managing Suppressions\n\n**List bounces (Python)**\n```python\nimport os, requests\n\nheaders = {\"Authorization\": f\"Bearer {os.environ['SENDGRID_API_KEY']}\"}\nresponse = requests.get(\"https://api.sendgrid.com/v3/suppression/bounces\", headers=headers)\nfor bounce in response.json():\n    print(f\"{bounce['email']}: {bounce.get('reason', 'unknown')}\")\n```\n\n**Remove a bounce (Python)**\n```python\nrequests.delete(f\"https://api.sendgrid.com/v3/suppression/bounces/{email}\", headers=headers)\n```\n\n> **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.\n\n---\n\n## ASM Suppression Groups\n\nUse suppression groups for category-based unsubscribes (e.g., \"Marketing\", \"Transactional\", \"Product Updates\"). Recipients can unsubscribe from one category without being suppressed from all email.\n\n**Create a group:**\n```python\nrequests.post(\"https://api.sendgrid.com/v3/asm/groups\",\n    headers={**headers, \"Content-Type\": \"application/json\"},\n    json={\"name\": \"Marketing Emails\", \"description\": \"Promotional offers and updates\"})\n```\n\n**Send with a suppression group:**\nInclude `asm.group_id` in your Mail Send request. Recipients see a \"manage preferences\" link instead of a global unsubscribe.\n\n---\n\n## Auto-Purge (Bounce & Block Cleanup)\n\nConfigure automatic purge schedules in Console > Settings > Mail Settings > Purge Bounces & Blocks:\n\n- **Soft Bounces:** Auto-purge after N days (1–3,650 days)\n- **Hard Bounces:** Auto-purge after N days (1–3,650 days)\n\n**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.\n\n---\n\n## Address Allow List\n\nConsole > Settings > Mail Settings > Address Allow List allows specific email addresses or domains to bypass all suppressions. Useful for internal testing addresses.\n\n**Use with extreme caution** — never allowlist domains you don't control (e.g., `gmail.com`), and never use to bypass spam report suppressions.\n\n---\n\n## CANNOT\n\n- **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.\n- **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.\n- **Cannot prevent spam report suppressions** — When a recipient marks you as spam, the suppression is automatic and cannot be overridden.\n- **Cannot bulk-remove suppressions by domain** — Must remove individually by email address via API.\n\n---\n\n## Next Steps\n\n- **Send email:** `twilio-sendgrid-email-send`\n- **Delivery tracking:** `twilio-sendgrid-webhooks`\n- **Account setup:** `twilio-sendgrid-account-setup`\n"
}