本文介绍如何使用 sendgrid rest api 批量获取 bounce（退信）、spam（垃圾邮件投诉）、invalid（无效邮箱）和 block（拦截）四类抑制数据，并通过脚本自动整理成邮件发送给指定收件人。
本文介绍如何使用 sendgrid rest api 批量获取 bounce（退信）、spam（垃圾邮件投诉）、invalid（无效邮箱）和 block（拦截）四类抑制数据，并通过脚本自动整理成邮件发送给指定收件人。
SendGrid 提供了完善的抑制列表（Suppressions）API，支持按类型独立查询：
- Bounces：因收件服务器拒绝（如邮箱已满、用户不存在）导致的硬/软退信；
- Blocks：因 IP 或域名被目标服务器主动拉黑而拒绝投递；
- Spam Reports：收件人点击“标记为垃圾邮件”触发的投诉记录；
-
Invalid Emails：格式错误或经验证无法解析的邮箱地址（如
user@或@domain.com）。
所有接口均基于 HTTPS 的 RESTful 设计，需在请求头中携带有效的 API Key（建议使用具有 suppressions.read 权限的专用 API Key）：
import requests
import json
from datetime import datetime
import smtplib
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart
# 配置 SendGrid API
SENDGRID_API_KEY = "SG.your_api_key_here"
BASE_URL = "https://api.sendgrid.com/v3"
# 获取各类抑制数据（示例：最近 30 天）
def fetch_suppressions(endpoint, limit=1000):
headers = {"Authorization": f"Bearer {SENDGRID_API_KEY}"}
params = {"limit": limit, "start_time": int((datetime.now() - timedelta(days=30)).timestamp())}
response = requests.get(f"{BASE_URL}{endpoint}", headers=headers, params=params)
response.raise_for_status()
return response.json()
bounces = fetch_suppressions("/suppression/bounces")
blocks = fetch_suppressions("/suppression/blocks")
spam_reports = fetch_suppressions("/suppression/spam_reports")
invalids = fetch_suppressions("/suppression/invalid_emails")
# 汇总为结构化报告
report_data = {
"Bounces": len(bounces),
"Blocks": len(blocks),
"Spam Reports": len(spam_reports),
"Invalid Emails": len(invalids),
"Generated At": datetime.now().isoformat()
}
# 生成 HTML 邮件正文
html_body = f"""
<h3>SendGrid 抑制列表日报（{report_data['Generated At'][:10]}）</h3>
<ul>
<li><strong>Bounces</strong>: {report_data['Bounces']} 个</li>
<li><strong>Blocks</strong>: {report_data['Blocks']} 个</li>
<li><strong>Spam Reports</strong>: {report_data['Spam Reports']} 个</li>
<li><strong>Invalid Emails</strong>: {report_data['Invalid Emails']} 个</li>
</ul>
<p><small>注：完整原始数据可调用对应 API 获取，详见 <a href='https://docs.sendgrid.com/api-reference'>SendGrid API 文档</a></small></p>
"""
# 发送邮件（以 Gmail SMTP 为例）
def send_report(to_emails, subject, html_content):
msg = MIMEMultipart("alternative")
msg["Subject"] = subject
msg["From"] = "alerts@yourdomain.com"
msg["To"] = ", ".join(to_emails)
part = MIMEText(html_content, "html")
msg.attach(part)
with smtplib.SMTP_SSL("smtp.gmail.com", 465) as server:
server.login("your_email@gmail.com", "your_app_password")
server.sendmail(msg["From"], to_emails, msg.as_string())
# 执行发送
send_report(
to_emails=["admin@company.com", "marketing@company.com"],
subject="[Alert] SendGrid 抑制数据日报",
html_content=html_body
)✅ 关键注意事项：
- 每类抑制 API 默认仅返回最近 30 天 数据（部分端点支持
start_time/end_time参数扩展）； - 高频调用需遵守 SendGrid 速率限制（通常为 10000 次/天）；
- 建议将脚本部署为定时任务（如 Linux
cron或云函数），每日凌晨执行； - 生产环境请使用环境变量管理敏感配置（API Key、SMTP 凭据），避免硬编码；
- 若需实时响应（如单封邮件触发即告警），推荐结合 Event Webhook + 签名验证方案，而非轮询 API。
通过该方案，你不仅能自动化监控邮件送达健康度，还能及时清理无效地址、规避投诉风险，显著提升发信信誉与转化效果。
