SendGrid API Key 必须启用 Mail Send 权限，否则 POST /mail/send 返回 403；go-sendgrid v4 的 Send 不支持 context 取消，需封装超时 HTTP 请求；模板须用 dynamic_template_data 传参而非拼接 HTML；Webhook 验签需同时校验 sg-signature 和 sg-timestamp。
SendGrid API Key 权限配置必须启用 Mail Send
很多团队在首次集成时发现 POST /mail/send 返回 403 Forbidden，根本原因不是密钥无效，而是 API Key 权限没开全。SendGrid 控制台创建的 Key 默认只含「Account Access」，必须手动勾选「Mail Send」权限并保存——这个操作不可逆，改完需生成新 Key。
验证方式很简单：用 curl 测试基础发送
curl -X POST https://api.sendgrid.com/v3/mail/send \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"personalizations": [{"to": [{"email": "test@example.com"}]}],
"from": {"email": "no-reply@yourdomain.com"},
"subject": "Test",
"content": [{"type": "text/plain", "value": "ok"}]
}'
如果返回 202 Accepted，说明权限和网络通路都没问题；若仍是 403，别折腾代码，直接回控制台检查 Key 权限。
go-sendgrid v4 的 sendgrid.Send 不支持上下文取消
SendGrid 官方 Go SDK（github.com/sendgrid/sendgrid-go）v4 的 sendgrid.Send 方法是阻塞式调用，没有 context.Context 参数，无法响应超时或服务端主动取消。在订单确认、支付回调等强一致性场景下，这会导致 goroutine 卡住或重试逻辑失控。
立即学习“go语言免费学习笔记（深入）”；
推荐做法是封装一层带超时的调用：
- 用
http.Client自建请求，显式传入context.WithTimeout - 将
sendgrid.Client的APIKey和BaseURL提取出来复用，避免每次新建 client - 对
429 Too Many Requests做指数退避，SendGrid 免费层每秒仅限 15 次请求
关键点：不要直接用 sg.Send()，哪怕它看着最“标准”。自己构造 http.Request 更可控。
在 Golang 中使用 samber/hot 进行内存缓存，支持 LRU、LFU、TinyLFU、W‑TinyLFU、S3FIFO、ARC、TwoQueue、SIEVE、FIFO 等淘汰算法，提供 TTL、缓存加载器及分片功能。
模板 ID（template_id）必须用动态内容，不能拼接 HTML 字符串
交易类通知（如支付成功、发货提醒、退款确认）需要差异化字段，但很多人图省事，在代码里用 fmt.Sprintf 拼 HTML 邮件体。这会导致两个硬伤：一是违反 SendGrid 模板审核机制（上线前模板需人工审核），二是无法做 A/B 测试或后续文案灰度。
正确路径是：
- 在 SendGrid 后台创建模板，启用「Dynamic Templates」，拿到
template_id（形如d-1a2b3c4d5e6f7g8h9i0j...） - 发送时用
dynamic_template_data字段传结构体，字段名必须和模板中{{.FieldName}}完全一致 - Go 中建议定义专用 struct，比如
type PaymentSuccessData struct { OrderID string; Amount float64 }，再 JSON 序列化进 payload
注意：template_id 是字符串，不是数字 ID；模板里所有变量必须预定义，运行时多传字段会被静默忽略。
Webhook 回调验签必须校验 sg-signature 头和时间戳
SendGrid 的事件 Webhook（如邮件送达、退信、打开）默认不带身份校验，攻击者可伪造 POST /webhook 请求触发业务侧状态机异常。官方要求必须验证 sg-signature 和 sg-timestamp 头。
Go 实现要点：
-
sg-timestamp是 Unix 秒级时间戳，需与当前时间差 ≤ 15 分钟，否则拒绝 -
sg-signature是 HMAC-SHA256 签名，密钥是你在 Webhook 设置页配的「Signing Key」，原文是timestamp + body（原始字节，非 JSON 格式化后） - SDK
sendgrid-go不提供验签工具函数，得自己写hmac.New+hex.DecodeString
漏掉时间戳校验等于白做签名——重放攻击只需要抓一次合法请求就能反复提交。
