You need to enable JavaScript to run this app. Python版Gmail API发送邮件时To头设utf-8编码触发无效To头报错
优惠活动
大模型
产品
解决方案
定价
更多

Python版Gmail API发送邮件时To头设utf-8编码触发无效To头报错

Gmail API Python 邮件发送 To 头编码校验异常

现象说明

  • 参考官方流程完成Gmail API授权、构建MIME格式邮件发送时,异常触发逻辑与To头的编码设置直接相关:
    • 不指定编码直接用Header("example@example.com")初始化To头,邮件可正常发送
    • 为To头显式传入utf-8编码参数,即写法为Header("example@example.com", 'utf-8'),会直接抛出Invalid To header错误
    • 对From、Subject头使用完全相同的显式utf-8编码写法,不会触发同类校验错误
  • 最小可复现代码:
from email.mime.multipart import MIMEMultipart
from email.header import Header
import base64

mime = MIMEMultipart()
mime['To'] = Header("example@example.com") # 无编码参数时可正常运行
# mime['To'] = Header("example@example.com", 'utf-8') # 显式指定utf-8时报错
mime['From'] = "me"
mime['Subject'] = "Hello World"
output = {'raw': base64.urlsafe_b64encode(mime.as_string().encode()).decode()}
service.users().messages().send(userId='me', body=output).execute()

异常根因

email.header.Header类在指定编码参数时,会将传入的整个字符串按RFC2047标准封装为可传输的编码块,形式类似=?utf-8?b?ZXhhbXBsZUBleGFtcGxlLmNvbQ==?=。
Gmail API对To头的校验逻辑要求必须能从头内容中解析出真实的纯ASCII格式邮箱地址——当整个邮箱地址被完全封装为编码块、缺失符合格式的纯邮箱片段时,校验器会判定该头为无效地址。
这一校验逻辑和邮件其他头(如Subject)的校验规则存在差异:Subject头允许全内容编码,不需要从内容中提取结构化信息,因此不会触发同类校验错误。

正确实现方式

  • 纯ASCII邮箱地址场景下,直接将邮箱字符串赋值给To头即可,不需要额外套Header类做编码
  • 存在非ASCII收件人显示名的业务场景下,仅对非ASCII的显示名部分做编码处理,保持邮箱地址为纯ASCII格式,符合RFC标准的邮件头拼接规则:
# 正确处理含非ASCII显示名的To头
to_display_part = Header("收件人姓名", "utf-8").encode()
mime['To'] = f"{to_display_part} <recipient@example.com>"

内容的提问来源于stack exchange,提问作者RyArazi

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.08 20:06:01