Python EmailMessage 怎样同时发送纯文本和 HTML

如果一封邮件只写 HTML，遇到禁用富文本的客户端时，读者可能只能看到空白或一段难以阅读的源码。Python 的 EmailMessage 更稳妥的做法是保留两个正文版本：先用 set_content() 放纯文本，再用 add_alternative() 放 HTML。邮件客户端会根据自身能力选择合适的那一份。

官方文档：https://docs.python.org/3/library/email.message.html

这篇只讨论消息对象怎样组装和检查，不展开 SMTP 连接、认证或第三方邮件服务配置。

为什么要同时保留纯文本和 HTML

纯文本是最稳妥的兜底内容，适合命令行客户端、无障碍阅读器和禁用 HTML 的环境；HTML 则负责链接、层次和简单排版。两者不是先后发送的两封邮件，而是同一封邮件里的两个可选正文部件。

在 MIME 结构中，这两个部件通常放在 multipart/alternative 容器下。邮件客户端会优先选择自己支持的表示形式，因此调用顺序也很重要：先建立纯文本基线，再追加 HTML 版本。

最小写法：set_content 加 add_alternative

下面的代码只创建消息对象，不连接邮件服务器。set_content() 写入纯文本后，add_alternative() 追加 HTML 正文；第二个参数的 subtype="html" 用来声明这一部件的媒体类型。

from email.message import EmailMessage

message = EmailMessage()
message["Subject"] = "订单处理结果"
message["From"] = "robot@example.com"
message["To"] = "reader@example.com"

# 先放纯文本版本，保证不支持 HTML 的客户端也能阅读。
message.set_content("订单已经处理完成，请登录系统查看详情。")

# 再追加富文本版本；EmailMessage 会按需要建立 alternative 容器。
message.add_alternative(
    """
      
        
订单已经处理完成。
        
查看订单详情
      
    """,
    subtype="html",
)

# 序列化前检查消息顶层是否已经成为可选正文容器。
assert message.get_content_type() == "multipart/alternative"

这里的 HTML 只展示固定内容。若页面片段来自用户输入，应先按 HTML 语境进行转义或使用受控模板，避免把不可信字符串直接拼进邮件正文。

调用顺序决定正文结构

很多“HTML 版本没有生效”的问题，不是 subtype 写错，而是把两个方法的职责混在了一起。set_content() 负责设置当前消息的基础内容；add_alternative() 才是追加另一种正文表示。

如果只调用一次 set_content()，得到的是普通文本消息；调用 set_content() 后再调用 add_alternative()，才会形成 multipart/alternative。不要在追加 HTML 后再次用 set_content() 覆盖顶层消息，否则会破坏已经建立的正文选择结构。

发送前怎样检查两份正文

生成消息对象后，可以用 get_content_type()、iter_parts() 和部件头部做一次轻量检查。这个检查不需要连接 SMTP，适合放在队列入列前或单元测试里。

from email.policy import SMTP

# 遍历顶层正文部件，确认 plain 与 html 都已经挂载。
parts = list(message.iter_parts())
content_types = [part.get_content_type() for part in parts]
assert content_types == ["text/plain", "text/html"]

# 使用 SMTP 策略序列化，得到后续投递组件可以接收的邮件字节。
raw_message = message.as_bytes(policy=SMTP)
print(message.get_content_type())
print(content_types)
print(len(raw_message))

如果只看到一个 text/plain，通常说明没有执行 add_alternative()，或者在追加之后又重新设置了顶层内容。生产代码可以把部件类型检查封装成断言或测试，而不是依赖肉眼查看长串 MIME 文本。

三个容易踩到的边界

HTML 不是附件

add_alternative(..., subtype="html") 表示 HTML 正文版本，不是下载附件。真正的附件应使用 add_attachment()，并且它属于另一层 MIME 关系，不能拿附件方法替代正文方法。

纯文本应当独立可读

不要把 HTML 标签直接塞进纯文本版本，也不要只写“请使用支持 HTML 的客户端查看”。纯文本应包含同等的核心信息；例如 HTML 里有一个详情链接时，纯文本里也应保留完整地址或明确的访问提示。

动态数据要先经过正确的转义

订单号、昵称等动态值可能同时出现在纯文本和 HTML 中，但两种语境的转义规则不同。纯文本版本可以使用普通字符串格式化；HTML 版本则应使用 HTML 转义或安全模板生成，不能因为邮件是内部消息就默认输入可信。

速查：什么时候用哪一个方法

相关问题

只发 HTML 可以吗？ 可以，但会失去纯文本客户端和部分辅助工具的兼容性；事务通知通常更适合同时提供两种正文。

为什么要先 set_content 再 add_alternative？ 先设置基础正文可以建立清晰的纯文本兜底，再追加 HTML 选择项，结构也更容易检查。

怎样确认 HTML 已经挂载？ 检查顶层类型是否为 multipart/alternative，再检查部件类型是否包含 text/plain 和 text/html。