用途:Mail Send API 只返回 202 Accepted(已排队),并不确认投递结果。要了解邮件后续状态,需使用 Event Webhooks。可在 SendGrid Console 的 Settings > Mail Settings > Event Notification 中启用。
事件类型:投递类包括 processed(已接受并将尝试投递)、deferred(临时失败将重试)、delivered(收件服务器已接受)、bounce(永久失败)、dropped(不再投递,如抑制、无效、垃圾邮件);互动类包括 open(基于像素,不可靠)、click、spamreport、unsubscribe、group_unsubscribe、group_resubscribe。
处理器实现:SendGrid 发送的是批量事件数组而非单个对象,处理器必须按数组解析。Python(Flask)与 Node.js(Express)示例见资料,均需返回 2xx 以确认接收。
多端点:自 2023 年 5 月起可配置多个 Event Webhook 端点,各自接收不同事件类型,例如投递事件送监控、互动事件送分析。每个端点有 Friendly Name 与 Webhook ID,数量取决于套餐。
认证:默认不启用。可选 Signed Event Webhook(ECDSA P-256,校验 X-Twilio-Email-Event-Webhook-Signature 与 X-Twilio-Email-Event-Webhook-Timestamp 头)或 OAuth 2.0。生产环境应启用签名验证以防伪造。
重试与去重:端点返回非 2xx 时,SendGrid 最多重试 24 小时;事件批量发送,单次 POST 可能含多条消息的数十个事件。可用 sg_event_id 作为唯一键去重,该值在重试间保持稳定。
限制:无法同步获得实时投递确认;默认无认证;open 追踪受 Apple Mail 隐私保护与预取影响而不准确,图片屏蔽客户端为零打开,不宜用于关键业务逻辑;企业安全扫描器与机器人会虚增互动指标,可按 User-Agent 与时间分析过滤。事件字段如 reason 来自外部邮件服务器,应视为不可信数据,勿直接放入 LLM 系统提示。
后续可参考:发送邮件 twilio-sendgrid-email-send、处理退信 twilio-sendgrid-suppressions、接收入站邮件 twilio-sendgrid-inbound-parse。