Terminal
Terminal/Skill
Explains how to read SendGrid Engagement Quality scores and their five metrics to monitor sender health and improve inbox placement.
By Twilio
Works with
npx skills add twilio/ai --skill twilio-sendgrid-engagement-qualitySendGrid Engagement Quality (SEQ) scores measure how "wanted" your email is by recipients. Higher scores (1-5 scale) correlate with better inbox placement. SEQ is a diagnostic tool — it tells you where your email program is healthy and where it needs improvement.
Key insight: SEQ scores are correlated with deliverability. A higher score means more emails land in inboxes, not spam folders.
Your account must meet ALL conditions to receive scores:
If not eligible, the score and metrics fields are omitted from API responses entirely.
All scores range from 1 (poor) to 5 (excellent).
| Metric | What it measures | How to improve |
|---|---|---|
| engagement_recency | Are you sending to an engaged audience? Based on how regularly messages are opened and clicked. | Remove inactive subscribers. Implement re-engagement campaigns before pruning. |
| open_rate | Degree to which your audience opens your messages. | Improve subject lines. Segment audiences by engagement level. |
| bounce_classification | Rejection by mailbox providers due to reputation or spam-like content. | Fix content triggering spam filters. Warm IPs properly. Monitor domain reputation. |
| bounce_rate | Are you sending to addresses that don't exist? Based on permanent bounces to invalid mailboxes. | Implement double opt-in. Clean lists quarterly. Use Email Validation API before sending. |
| spam_rate | Are recipients marking your email as spam? Based on recipients who open then report spam. | Only send to opted-in recipients. Make unsubscribe easy. Match content to expectations set at signup. |
Note: The overall score is NOT a simple average of the 5 metrics — the weighting formula is opaque. A single low metric (e.g., spam_rate = 1) can drag the overall score significantly.
GET /v3/engagementquality/scores
| Parameter | Required | Description |
|---|---|---|
from | Yes | Start date (YYYY-MM-DD, UTC) |
to | Yes | End date (YYYY-MM-DD, UTC) |
Python
import os, requests
headers = {"Authorization": f"Bearer {os.environ['SENDGRID_API_KEY']}"}
response = requests.get(
"https://api.sendgrid.com/v3/engagementquality/scores",
params={"from": "2026-04-01", "to": "2026-04-23"},
headers=headers
)
if response.status_code == 200:
for entry in response.json()["result"]:
print(f"Date: {entry['date']}, Score: {entry.get('score', 'N/A')}")
metrics = entry.get("metrics", {})
for metric, value in metrics.items():
print(f" {metric}: {value}")
elif response.status_code == 202:
print("Scores not yet calculated — try again later")
GET /v3/engagementquality/subusers/scores
| Parameter | Required | Description |
|---|---|---|
date | Yes | Date (YYYY-MM-DD, UTC) |
limit | No | Results per page (default 1000, max 1000) |
after_key | No | Pagination cursor |
Returns paginated results with _metadata.next_params.after_key for pagination.
200 OK — Scores available:
{
"result": [{
"user_id": "12345",
"username": "myaccount",
"date": "2026-04-22",
"score": 4,
"metrics": {
"engagement_recency": 4,
"open_rate": 5,
"bounce_classification": 3,
"bounce_rate": 4,
"spam_rate": 5
}
}]
}
202 Accepted — Scores are calculated asynchronously. Not yet available for the requested date. Retry later.
Score or metrics omitted — Account/subuser is not eligible (open tracking off or <1,000 sends in 30 days).
202 response means "not ready yet."twilio-sendgrid-suppressionstwilio-sendgrid-webhookstwilio-sendgrid-account-setup