Python 3.15.2 的邮件生成器在无法准确扁平化含非 ASCII 邮箱地址的地址头时会报错；先检查地址头序列化策略，再核对发送服务器是否支持 SMTPUTF8，最后用受控收件箱确认邮件是否真实收到。这不代表所有非 ASCII 正文、显示名或国际化邮箱地址都会失败；判断要按字符出现的位置和测试链路分段进行。
适合正在升级或运行 Python 3.15.x、遇到地址头序列化异常的开发者；也适合要验收自家产品国际化邮件的 QA 工程师，以及维护 SMTP 发信链路的独立开发者。
最后更新于 2026 年 11 月 1 日，数据核实自 Python 3.15.2 发布页、Python 3.15 文档及 email、smtplib 官方文档。
Python 3.15 的报错边界：不是所有非 ASCII 邮件都失败
Python 3.15 的 What’s New 明确说明：如果邮件生成器无法准确扁平化地址头中的非 ASCII 邮箱地址，就会抛出错误。问题指向的是地址头里的邮箱地址部分，不应扩大解释成“邮件正文含中文就不能发”，也不能仅凭日志里看见非 ASCII 字符，就断定是哪一个字段触发了异常。〔Python 3.15 官方更新说明〕
另一个需要纳入排障的版本边界是：Python 3.15.2 于 2026 年 10 月 25 日发布，但该发布页没有把地址头行为描述为 3.15.2 特有的新变化。因此，应以当前环境的实际异常、地址类型和官方邮件策略说明来判断，不要把问题简单归因于 3.15.2 的补丁回归。〔Python 3.15.2 发布说明〕
先把三个结果拆开看：
- 生成失败：
EmailMessage转成字节或字符串时抛出异常，尚未进入 SMTP 发送。 - 发送端拒绝或报错：序列化通过，但协商 SMTP 扩展或提交信封时失败。
- 收件未验收：SMTP 服务器接受了提交，不等于受控收件箱里已经出现邮件。
这三类证据对应不同责任环节。若把它们合并成一个“发信失败”日志，常见后果是改错策略、重复重试，甚至把传输层问题误报成模板编码问题。
显示名有国际字符时，先把它和地址本身分开
收件人 <qa@example.test> 里的显示名和 qa@example.test 不是同一部分。显示名中的中文或带重音字符，通常可以按传统邮件头规则编码；但如果非 ASCII 字符位于邮箱的 local-part，例如 j小明@example.test，它就是地址本身的一部分，不能靠显示名编码来解决。
下面的用例把两种情况分开构造。它的目的仅是检查消息生成，不会连接 SMTP，也不能证明示例地址真实存在：
from email import policy
from email.headerregistry import Address
from email.message import EmailMessage
def make_message(address):
msg = EmailMessage(policy=policy.SMTP)
msg["From"] = "sender@example.test"
msg["To"] = address
msg["Subject"] = "mail header check"
msg.set_content("test body")
return msg
cases = {
"non_ascii_display_name": Address(
display_name="测试收件人",
username="qa",
domain="example.test",
),
"non_ascii_local_part": Address(
display_name="QA",
username="测试",
domain="example.test",
),
}
for name, address in cases.items():
try:
result = make_message(address).as_bytes()
print(name, "serialized", result.split(b"\r\n\r\n", 1)[0])
except Exception as exc:
print(name, type(exc).__name__, str(exc))
查看异常类型和生成后的头部字节，不要只检查整封邮件的控制台打印结果。 如果只有显示名含国际字符，重点看头部编码结果；若 username 或域名含非 ASCII 字符，则继续检查策略的 utf8 值和序列化异常。这个对照也能避免把正文里的中文误判为地址头问题。
国际化邮箱地址要单独验证地址解析与扁平化
EAI（电子邮件地址国际化）地址不能等同于“显示名使用 Unicode”。非 ASCII 字符可能位于域名，也可能位于 local-part；两者对兼容性和 ASCII 序列化的处理不同。标准策略 utf8=False 时，Python 会在 RFC 2047 不允许编码词的地址位置抛出 HeaderWriteError。官方文档特别指出，非 ASCII local-part 不能在 utf8=False 下使用；非 ASCII 域名可先转换为 IDNA 形式，或在需要时采用 UTF-8 头策略。〔Python 3.15 email.policy 文档〕
EmailPolicy.utf8 设为 True 时，头部按 RFC 6532 使用 UTF-8 编码；这不是对所有服务端的兼容保证。email.policy.SMTPUTF8 是 SMTP 策略的 UTF-8 版本，适合需要 UTF-8 头部序列化的情形，但是否可用于真实 SMTP 发送，还取决于发送链路对 SMTPUTF8 扩展的支持。〔RFC 6531：SMTPUTF8 扩展规范〕
因此，测试数据至少要标明字符的位置：
| 测试选项 | 非 ASCII 出现位置 | 生成阶段重点 | 适合用于证明什么 |
|---|---|---|---|
| A：ASCII 地址 + 国际显示名 | 显示名 | 检查生成的头部编码 | 显示名是否被正确序列化 |
| B：ASCII 地址 + 国际正文 | 正文 | 检查 MIME 正文编码 | 正文内容是否正确编码 |
| C：国际化域名地址 | 域名 | 检查 IDNA 或 UTF-8 策略 | 域名形式在当前策略下能否序列化 |
D：国际化 local-part |
地址本地部分 | 检查 utf8=True 与地址解析 |
本地部分能否按国际化路径生成并传输 |
表格中的“生成成功”只说明 Python 生成器产出了结果。它不代表 SMTP 中继、下一跳服务器或收件服务都能处理这类地址。一般临时收件地址也不能被默认当作支持国际化本地部分的验证器；测试目标地址必须是明确受控、可检查的收件端。
EmailMessage 序列化失败时先查哪些地方？
排查时先保留一个最小复现，不要一开始就改生产发信配置。对照 email.message.EmailMessage 官方说明，消息对象带有自己的策略，序列化会依策略生成消息字节；因此，异常可能在显式调用 as_bytes() 时出现，也可能直到发送方法执行序列化才暴露。〔Python 3.15 email.message 文档〕
按这个顺序定位：
- 记录运行环境与异常栈。 记录完整 Python 版本、触发的序列化方法、异常类名和堆栈。不要只记“含中文时失败”。
- 复制最小消息结构。 保留
From、To、Cc等地址头和触发字段，移除附件、模板引擎及无关业务逻辑。 - 标注字符所在位置。 分别验证显示名、域名、
local-part和正文；一次只改变一种输入。 - 检查消息策略。 确认消息是否使用预期的
EmailPolicy、utf8配置是否符合地址类型；不要把显示名可编码推断成地址也可用同一种编码。 - 在调用 SMTP 前单独序列化。 对最小消息运行
as_bytes()，保存生成的头部字节或异常。若这一步已经失败，就先处理生成策略，不必查服务器日志。 - 改动后重新跑原始用例。 留存 Python 补丁版本、输入地址类别、异常类型和序列化结果，避免只有开发机上的“现在好了”而没有可复核证据。
这个流程能把解析、生成与传输分开，降低调试成本。还可把异常类、消息策略和地址类别一起写入 QA 记录，避免多个测试场景都只留下同一条笼统失败信息。
SMTPUTF8 不受支持时，send_message 会怎样？
smtplib.SMTP.send_message 会从消息头提取发件人与收件地址，并序列化消息后调用发送逻辑。如果信封地址含非 ASCII 字符，而 SMTP 服务器没有通过 EHLO 广告 SMTPUTF8，文档规定会抛出 SMTPNotSupportedError；支持时，方法会用 utf8=True 的策略副本序列化，并附加 SMTPUTF8 与 BODY=8BITMIME 发送选项。〔Python 3.15 smtplib 文档〕
可以在获授权的测试服务器上检查服务器能力。不要将下面的能力查询结果单独当作送达证明：
import smtplib
with smtplib.SMTP("smtp.example.test", 587) as server:
server.ehlo()
print(server.esmtp_features)
print("SMTPUTF8:", server.has_extn("smtputf8"))
若服务器未广告 SMTPUTF8，不能假设客户端把地址“转成 UTF-8”后就能强行发送。SMTPUTF8 是服务器声明的传输扩展；相关标准要求客户端不得把需要该扩展的国际化邮件发给不支持它的服务器。
对照不同结果时，重点看失败位置和返回证据：
| 观察结果 | 证据落点 | 下一步 |
|---|---|---|
as_bytes() 抛出地址头异常 |
Python 邮件生成器 | 检查地址字符位置、解析结果及 utf8 策略 |
send_message 抛出 SMTPNotSupportedError |
SMTP 扩展协商 | 查 EHLO 广告与当前发信服务能力 |
| SMTP 返回接受状态 | SMTP 提交阶段 | 保存响应、收件人结果与关联标识，再查目标收件箱 |
| 受控收件箱没有对应邮件 | 端到端验收 | 查后续中继、退信、垃圾邮件分类或地址有效性 |
SMTP 服务器接受提交，表示它接受了当前传输请求，不代表测试邮箱已成功显示邮件，也不代表最终收件方已处理。SMTP.send_message 文档说明了扩展协商与异常边界；最终是否收件，仍需用目标收件箱或后续投递证据确认。
受控收件验收：把同一封测试邮件的证据串起来
测试自家产品或获授权环境时，应为同一次尝试关联输入地址、生成结果、SMTP 响应和收件端结果。不要把一次序列化成功与另一次 SMTP 成功拼成“已验证到达”。也不要把真实用户地址、验证码或敏感邮件内容直接写入公开日志；按团队的访问控制和数据留存要求保管必要证据。
建议记录以下信息：
- Python 完整版本，以及应用实际加载的邮件策略；
- 地址类型：ASCII、国际化域名、国际化
local-part，或仅显示名含国际字符； EmailMessage的序列化结果，或异常类与对应头字段；- SMTP 服务的
EHLO扩展结果、发送方法返回状态及被拒收的收件人信息； - 同一测试关联标识、受控收件箱中的邮件头与实际收件结果；
- 收件箱未出现邮件时，调查到哪一段链路为止，而非直接标记为“Python 已送达”。
不同证据能支持的结论范围并不相同。按“生成—提交—收件”分级记录，才能指出失败究竟来自格式策略、SMTP 能力还是后续投递。对团队内测试地址的隐私处理，也可结合 邮箱暴露风险自检 来决定哪些地址适合短期收件、哪些场景需要长期受控邮箱。
按地址类型选择下一步修复
- 只有显示名含非 ASCII 字符： 保留 ASCII 邮箱地址，检查地址头生成字节和显示名编码；不要因为显示名成功编码，就把结论推广到国际化地址。
- 域名含非 ASCII 字符： 判断项目需要的是 IDNA 转换后的 ASCII 域名形式，还是使用 UTF-8 地址头；之后分别复测序列化与真实服务端能力。
local-part含非 ASCII 字符： 在utf8=False时预期会触发地址头写入错误。确认产品是否确实要求支持此类地址，再用 UTF-8 策略和支持 SMTPUTF8 的获授权服务器测试。- SMTP 服务不支持 SMTPUTF8： 这是传输能力限制，不是把正文改成 UTF-8 就能解决。评估发信服务是否支持该扩展；若不能更换，就明确产品不支持的地址范围，并在注册或验收规则中如实处理。
- 发送端接受但收件箱没有邮件： 转入投递链路调查，关联发送服务日志、退信信息及受控收件端记录。不要把“没有抛异常”改写成“已送达”。
最终结论应限定到已验证的范围，例如：“Python 3.15.2 下，指定策略可序列化某类地址；指定 SMTP 服务声明支持 SMTPUTF8；受控收件箱已观察到对应测试邮件。”没有完成最后一项时，只能报告生成或提交结果，不能声称端到端兼容所有邮件系统。
若需要把测试地址与团队主邮箱分开，可在完成策略和 SMTP 能力检查后，将 MXTemp 的临时收件箱作为短期验收方案之一：本站页面说明其无需注册、可即开即用，适合短期注册或查看一次性邮件；它不承诺支持国际化地址，也不保证每封测试邮件送达。不要把它用于银行、支付、政务等重要账户、账户找回或需要长期收信的场景。准备开始短期测试时，可先查看 MXTemp 临时收件箱，并按当前页面实际显示的地址与服务条件操作。