gmail api 并非强制将 html 邮件转为纯文本，而是自动将其封装为 `multipart/alternative`，并智能添加纯文本备选部分；若邮件显示为纯文本，通常因原始 mime 结构不规范或缺失必要头字段所致。
在使用 Gmail API 发送 HTML 邮件时，一个常见误解是：手动设置 Content-Type: text/html 就能确保收件端渲染为 HTML。实际上，Gmail API 服务端会对传入的原始邮件（raw 字段）进行深度解析与标准化重构——它不会原样转发你构造的头部，而是基于 RFC 5322 / RFC 2046 规范，自动补全、校验并重写 MIME 结构。这正是你观察到“有时出现 multipart/alternative”“Content-Type 被修改”“HTML 变成纯文本”的根本原因。
✅ 正确做法：提供完整、合规的 multipart MIME 消息
Gmail API 期望且推荐你发送符合标准的 multipart/alternative 格式原始邮件（而非单部分 text/html）。即使你只提供 HTML 内容，API 也可能尝试自动生成纯文本版本（效果常不佳），导致渲染异常。因此，最佳实践是主动构造双格式消息体：
// 构造标准 multipart/alternative 邮件（Go 示例）
boundary := "boundary_" + strconv.FormatInt(time.Now().UnixNano(), 36)
htmlBody := "<html><body><h1>Hello <b>World</b></h1></body></html>"
textBody := "Hello World" // 纯文本备选（建议简洁、语义等价）
msg := fmt.Sprintf(
"From: %s\r\n"+
"To: %s\r\n"+
"Subject: %s\r\n"+
"MIME-Version: 1.0\r\n"+
"Content-Type: multipart/alternative; boundary=\"%s\"\r\n\r\n"+
"--%s\r\n"+
"Content-Type: text/plain; charset=utf-8\r\n\r\n"+
"%s\r\n\r\n"+
"--%s\r\n"+
"Content-Type: text/html; charset=utf-8\r\n\r\n"+
"%s\r\n\r\n"+
"--%s--",
"sender@example.com",
"recipient@example.com",
"HTML Email Test",
boundary,
boundary, textBody,
boundary, htmlBody,
boundary,
)
raw := base64.URLEncoding.EncodeToString([]byte(msg))
gmsg := gmail.Message{Raw: raw}
_, err := gmailService.Users.Messages.Send("me", &gmsg).Do()⚠️ 关键注意事项
- 不要仅设 Content-Type: text/html：单部分 HTML 邮件易被 API 降级处理或触发安全策略，导致纯文本显示；
- 必须包含 MIME-Version: 1.0：缺失此头可能导致解析失败；
- 行尾必须为 \r\n（CRLF），不可用 \n；
- raw 字段需 Base64 URL-safe 编码（如 base64.URLEncoding），且无换行/空格；
- Subject 建议 UTF-8 编码：若含非 ASCII 字符，应使用 RFC 2047 编码（如 =?UTF-8?B?...?=）；
- 避免手动设置 Content-Transfer-Encoding：除非你精确控制编码逻辑，否则交由 API 自动处理更可靠（如使用 quoted-printable 或 base64 时需严格匹配内容）。
? 调试技巧
发送前，打印完整构造的 msg 字符串（解码后），用 MIME Validator 或本地邮件客户端（如 Thunderbird）验证结构是否合法。若结构正确却仍显示异常，可检查：
实现 Markdown↔ HTML 互转，支持导出 PDF，用于用户请求的文档格式转换。
- 收件方邮箱客户端是否禁用 HTML 渲染；
- HTML 内容是否含非法标签或未闭合结构（如 hello 缺 ）；
- 是否误将 HTML 字符串进行了二次 HTML 实体转义（如 <b> → 显示为源码）。
总之，Gmail API 并非“实验性”或“不稳定”，而是遵循严格邮件标准的设计。掌握 multipart/alternative 的正确构造方式，即可稳定、可靠地发送富格式邮件。
立即学习“前端免费学习笔记（深入）”；
