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 := "
Hello World
"
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）验证结构是否合法。若结构正确却仍显示异常，可检查：

• 收件方邮箱客户端是否禁用 HTML 渲染；
• HTML 内容是否含非法标签或未闭合结构（如 hello 缺 ）；
• 是否误将 HTML 字符串进行了二次 HTML 实体转义（如 zuojiankuohaophpcnbyoujiankuohaophpcn → 显示为源码）。

总之，Gmail API 并非“实验性”或“不稳定”，而是遵循严格邮件标准的设计。掌握 multipart/alternative 的正确构造方式，即可稳定、可靠地发送富格式邮件。