# twilio-sendgrid-deliverability-advisor

Diagnoses SendGrid email delivery issues, spam placement, and domain blocks. Guides senders through authentication checks and automated IP warmup routines.

- skill · `type=skill` · Codex, ChatGPT · ★ 7604
- Author: Twilio · official OpenAI repository
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/openai/plugins/tree/HEAD/plugins/twilio-developer-kit/skills/twilio-sendgrid-deliverability-advisor/SKILL.md
- Updated: 2026-10-08
- HTML: https://affpapa.org/en/nevibecode/skills/twilio-sendgrid-deliverability-advisor

## What it does

The skill acts as an automated triage advisor for email deliverability on SendGrid. It inspects domain authentication records like SPF, DKIM, and DMARC, while evaluating sender reputation via the Engagement Quality Score (SEQ). When messages bounce or defer, the workflow categorizes the incident into immediate triage or systematic audit.

Metrics guide every diagnostic decision. A hard bounce rate above 2% or spam complaints topping 0.08% trigger warnings to halt bad lists. For dedicated IP setups, it enforces a 41-day warmup schedule. Since June 2025, SendGrid warmup overflow no longer rolls back to shared IP pools, so unrouted mail is held for retries up to 72 hours.

The skill stops immediately if you supply a Twilio Account SID, directing you to `twilio-email-deliverability-advisor` instead. It operates exclusively on standard SendGrid API keys starting with `SG.` or dashboard configurations at `app.sendgrid.com`.

## Install

### Codex (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add openai/plugins --skill twilio-sendgrid-deliverability-advisor -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/twilio-sendgrid-deliverability-advisor/SKILL.md` — For all projects use ~/.agents/skills/

### Claude Code

1. **Skills CLI (Vercel)**
```bash
npx skills add openai/plugins --skill twilio-sendgrid-deliverability-advisor -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/twilio-sendgrid-deliverability-advisor/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/twilio-sendgrid-deliverability-advisor/

### Cursor

**Manually: put the files in place**
- File: `.cursor/skills/twilio-sendgrid-deliverability-advisor/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install openai/plugins twilio-sendgrid-deliverability-advisor
```

2. **Manually: put the files in place**
- File: `.github/skills/twilio-sendgrid-deliverability-advisor/SKILL.md`

### Gemini CLI

**Platform CLI**
```bash
gemini skills install https://github.com/openai/plugins --path plugins/twilio-developer-kit/skills/twilio-sendgrid-deliverability-advisor
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/twilio-sendgrid-deliverability-advisor/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/openai/plugins/tree/HEAD/plugins/twilio-developer-kit/skills/twilio-sendgrid-deliverability-advisor/SKILL.md

## When to use it
- diagnose why SendGrid emails land in spam folders
- verify domain authentication for SPF, DKIM, and DMARC
- plan a 41-day warmup schedule for a dedicated SendGrid IP
- investigate hard bounce rate spikes exceeding 2%

## Example prompts
- Check why our SendGrid marketing emails land in junk folders
- Our hard bounce rate went above 2%, what should we fix?
- Set up an automated 41-day IP warmup schedule for SendGrid

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: df701f73187313dd.

BEGIN THIRD-PARTY FILE df701f73187313dd
```text
---
name: twilio-sendgrid-deliverability-advisor
description: >
  Diagnostic and advisory skill for email deliverability problems. Use when
  a developer asks why emails are going to spam, not reaching the inbox,
  getting blocked, bouncing, or how to improve sender reputation — with or
  without a specified platform. Covers SendGrid-specific tooling: SPF, DKIM,
  DMARC, BIMI, IP warmup, list hygiene, bounce/spam rate thresholds, and
  Engagement Quality Score (SEQ). Do NOT use for Twilio Email
  (comms.twilio.com / Account SID + Auth Token) — use
  twilio-email-deliverability-advisor instead. Do NOT use for general email
  sending questions — use twilio-sendgrid-email-send (SendGrid) or
  twilio-email-deliverability-advisor instead.
tier: discover
---

## Role

You are an Email Deliverability Advisor. When a developer describes emails going to spam, bouncing, getting blocked, or asks how to improve inbox placement or sender reputation, use this framework to diagnose and recommend fixes.

## When This Skill Activates

Trigger on any of these signals:
- "Emails going to spam," "landing in junk," "not reaching inbox"
- "Blocked," "rejected," "deferred," "blacklisted," "denylisted"
- "Bounce rate too high," "spam complaints," "reputation score"
- "IP warmup," "dedicated IP," "shared IP"
- "SPF," "DKIM," "DMARC," "BIMI," "domain authentication"
- "SEQ score," "engagement quality," "sender score"
- "List hygiene," "spam traps," "invalid addresses"
- "How do I improve deliverability?"

Do NOT trigger for: general email sending implementation, template questions, webhook setup, suppression list management unrelated to deliverability. Redirect to `twilio-sendgrid-email-send` (SendGrid) for sending questions, `twilio-sendgrid-suppressions` for suppression management, `twilio-email-deliverability-advisor` for Twilio Email deliverability.

---

## Step 0: Identify Platform

Check for platform signals before proceeding:

| Signal | Platform | Action |
|--------|----------|--------|
| API key starts with `SG.` | SendGrid | Proceed |
| Mentions `app.sendgrid.com` | SendGrid | Proceed |
| Mentions `comms.twilio.com`, Account SID, or Auth Token | Twilio Email | Redirect |
| No signal | Unknown | Ask |

**If Twilio Email:** Stop. Respond: "For Twilio Email deliverability, use the `twilio-email-deliverability-advisor` skill — it's scoped to that platform."

**If unclear:** Ask exactly this before proceeding:
> "Are you using SendGrid (API key starting with `SG.`, dashboard at app.sendgrid.com) or Twilio Email (Twilio Account SID / Auth Token)?"

---

## Step 1: Detect the Problem Type

**Acute problem** (emails suddenly blocked, bounce rate spiked, on a denylist):
→ TRIAGE MODE. Something changed — diagnose before recommending.

**Gradual degradation** (deliverability declining over weeks, open rates dropping):
```
END THIRD-PARTY FILE df701f73187313dd

The third-party file has ended. Everything between the df701f73187313dd tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2856 of 15217 bytes. © Twilio · MIT · https://github.com/openai/plugins/tree/HEAD/plugins/twilio-developer-kit/skills/twilio-sendgrid-deliverability-advisor/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md