mailgun-go/v5是go生态中唯一推荐用于生产环境的mailgun官方sdk，必须正确配置us/eu端点、验证发件人域名、提供text/plain备用正文、使用validatewebhook验证签名，任一环节错配将导致静默失效。
mailgun-go 是目前 Go 生态中对接 Mailgun 最稳定、维护最勤的官方支持库，它不是“可选方案”，而是**唯一推荐用于生产环境的 Mailgun 官方 SDK**。其他手写 HTTP 请求或封装 net/http 的方式，会遗漏签名验证、重试逻辑、事件解析、EU 端点适配等关键细节，上线后容易在退信率、Webhook 验证失败、超时阻塞等问题上翻车。
用 mailgun-go/v5 初始化客户端必须设对 APIBase
Mailgun 分 US 和 EU 两个数据中心，域名和 API 地址不互通。如果你的域名注册在 EU 区域（比如 mg.yourcompany.eu），但没显式调用 mg.SetAPIBase(mailgun.APIBaseEU)，所有请求都会 401 或 404。
- US 域名（默认）：
https://api.mailgun.net/v3 - EU 域名（必须手动设置）：
https://api.eu.mailgun.net/v3 - 检查方式：登录 Mailgun 控制台 → Domains → 查看 “Domain Name” 后缀，带
.eu就必须设APIBaseEU - 错误现象：
401 Unauthorized或404 Not Found，且private-api-key确认无误
NewMessage 构造时发件人地址必须属于已验证域名
Mailgun 强制要求 from 地址的域名必须是你在控制台已验证并启用的发送域名（如 mg.yourcompany.com），不能是 Gmail、QQ 邮箱等第三方地址 —— 即使你填了也发不出去，且不会报错，只会静默失败或进垃圾箱。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 合法格式：
"no-reply@mg.yourcompany.com"（域名必须与yourdomain参数一致） - 非法格式：
"admin@gmail.com"、"service@yourcompany.com"（后者未在 Mailgun 后台添加并验证） - 调试技巧：用
mg.GetDomain拉取当前域名状态，确认state == "active"且smtp_login非空 - 注意：测试模式下允许发给邮箱白名单用户，但生产环境必须走完整域名验证流程
发 HTML 邮件别只调 SetBody，要用 AddAlternative 和 AddAttachment
mailgun-go 的 Message 对象默认只支持纯文本正文。要发 HTML 邮件，必须同时提供 text/plain 备用版本，否则 Outlook、Apple Mail 等客户端可能显示空白或原始 HTML 标签。
- 正确做法：先
message.SetBody("text/plain", "纯文本内容")，再message.AddAlternative("text/html", "<h1>HTML 内容</h1>") - 附件必须用
message.AddAttachment("/path/to/file.pdf")，不能靠拼 MIME 手动构造 - 模板变量替换：用
message.AddVariable("name", "Alice")+ 控制台创建的模板 ID，而非硬编码到 HTML 字符串里 - 常见坑：忘记
SetBody直接只调AddAlternative→ 邮件被拒收（Mailgun 要求至少一个text/plain版本）
Webhook 签名验证必须用 ValidateWebhook，别自己拼 HMAC
Mailgun Webhook 的 X-Mailgun-Signature 是 base64 编码的 JSON，含 timestamp 和 token，签名密钥是你在 Webhook 设置页生成的 Webhook Signing Key。自己用 hmac.New 手算很容易因时间戳偏移、JSON 序列化顺序、换行符处理出错而验证失败。
- 必须用
mailgun.ValidateWebhook(signingKey, timestamp, token, signature) - 注意：
timestamp是秒级整数，不是毫秒；签名验证失败返回false，不 panic，需手动 return error - 真实陷阱：本地开发时系统时间不准，导致 timestamp 差几秒 → 验证失败；建议加 ±30 秒容差（
time.Now().Unix()对比） - 别把
signing key写死在代码里，应从环境变量读取（os.Getenv("MAILGUN_WEBHOOK_KEY")）
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
