直接使用官方 sendgrid/sendgrid-go 库，避免手动封装；批量发送需用 SetPersonalizations 而非循环调 Send；模板变量须扁平化；开发启用 SandboxMode；失败需依赖 Webhook 而非轮询。
SendGrid API v3 的 Go 客户端怎么选
直接用官方 sendgrid/sendgrid-go 库，别自己封装 HTTP 请求。它已支持 v3 API，且对 mail.SendRequestBody 结构体做了合理抽象，能避免手动拼 JSON 或处理鉴权头的常见错误。
注意：v2 API 已停用，如果看到旧教程里用 sendgrid.SendEmail 或依赖 github.com/sendgrid/sendgrid-go/sendgrid（非主包路径），说明库过时，发信会返回 404 Not Found 或 401 Unauthorized。
- 安装命令是：
go get github.com/sendgrid/sendgrid-go - 环境变量存 API Key，别硬编码：
SENDGRID_API_KEY - 初始化客户端只需一行：
sg := sendgrid.NewSendClient(os.Getenv("SENDGRID_API_KEY"))
群发周报邮件必须用「批量发送」而非循环单发
用 sg.Send() 单次调用发多封邮件，不是 for 循环里反复调 sg.Send()。后者会触发 SendGrid 的速率限制（默认 10 req/sec），且每封邮件都走独立 HTTP 请求，延迟高、失败率上升。
关键点在于构造一个含多个 mail.Addressee 的 mail.Email，并启用 mail.SetPersonalizations —— 这才是 SendGrid 批量投递的正确路径。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 每个收件人需独立
personalization实例，用于定制subject、substitutions（如姓名、本周数据） -
mail.SetFrom只设一次，mail.SetContent也只设一次（HTML/文本模板复用） - 别漏掉
mail.SetMailSettings中的mail.SetSandBoxMode，开发时务必开启，否则真实邮箱收不到测试邮件
周报模板里如何安全插入动态数据
SendGrid 的模板功能（Template ID）适合固定结构的周报，但要注意：它不支持任意 Go 模板语法，只认 Handlebars 风格的 {{variable}}，且变量必须扁平化传入 personalization.DynamicTemplateData。
常见翻车点是嵌套 map 或 struct 直接塞进去——SendGrid 会静默忽略深层字段。例如 map[string]interface{}{"user": map[string]string{"name": "Alice"}}，模板里写 {{user.name}} 不生效，必须展平为 map[string]interface{}{"user_name": "Alice"}。
- 建议在生成
DynamicTemplateData前，用json.Marshal+json.Unmarshal强制转成扁平 map，避免指针或嵌套结构残留 - 敏感字段（如用户 ID）别放进模板变量，应在后端生成时完成脱敏，再传给 SendGrid
- 测试时用
mail.SetTemplateID后，先在 SendGrid 后台「Templates」里预览渲染效果，别等发出去才发现变量没替换
定时任务与失败重试怎么和 SendGrid 配合
Go 里用 time.Ticker 做周度触发不靠谱：进程重启后状态丢失，且无法跨实例协调。应该把发送逻辑绑定到外部调度器（如 cron job 或 Kubernetes CronJob），Go 程序只负责“执行一次发送”。
SendGrid 返回 202 Accepted 并不代表邮件已送达，只是入队成功。真正失败可能发生在几秒后（如收件箱满、域名拒收），这时 SendGrid 会发 webhook 或写入「Activity Feed」。所以你的周报服务必须：
- 记录每次调用的
request_id（响应 Header 中的X-Request-ID），用于后续查日志 - 配置 SendGrid 的「Event Webhook」，监听
delivered、dropped、bounced事件，而不是轮询 API - 对
dropped类型失败，检查是否因收件人邮箱格式错误或域名不存在——这类错误不会重试，得从上游名单清洗源头解决
真正麻烦的是模板渲染失败或收件人列表超限（SendGrid 单请求最多 1000 个收件人），这种错误会在响应 Body 里带具体提示，比如 "recipient count exceeds limit"，得提前分批切片再发。
