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
相关产品推荐
相关产品推荐

