Python发送邮件附件无法被Mailspring/Thunderbird识别排查

Gmail、Outlook对不符合MIME RFC规范的邮件做了大量容错处理，Thunderbird、Mailspring则执行严格的MIME解析规则，你的代码存在4个典型错误，会导致严格客户端无法识别附件：

• 根MIME容器类型错误：这是90%同类问题的诱因。如果邮件同时包含正文和附件，根节点必须使用multipart/mixed类型，禁止使用multipart/alternative作为根节点，也不能用MIMEText初始化根对象后直接挂载附件。multipart/alternative的设计语义是“所有子节点为同一内容的不同展示版本，客户端仅需选择最高优先级的版本渲染”，严格遵循RFC的客户端会直接忽略该容器下不属于正文版本的附件部分，只有做了容错的客户端会强行把非正文节点识别为附件。
• 传输编码声明不规范：手动构造MIME部件时未显式指定Content-Transfer-Encoding，部分场景下库自动生成的编码声明不符合RFC要求，严格客户端无法解码附件内容时会直接判定该MIME部件无效。
• 文件名参数未做合规编码：直接将原始文件名传入Content-Disposition头，当文件名包含非ASCII字符、空格、特殊符号时，会触发邮件头解析失败，导致附件无法被识别。
• 原始邮件生成方式错误：使用as_string()生成最终邮件内容时，库会默认以文本编码处理所有内容，很容易破坏二进制附件的内容或MIME分隔边界。

1. 按照规范搭建MIME层级
   • 根节点固定使用MIMEMultipart('mixed')作为容器
   • 如果需要同时支持纯文本、HTML两种格式的正文，在根节点下新增一个multipart/alternative类型的子容器，将两个版本的正文挂载到该子容器下，再将子容器挂载到根节点
   • 所有附件必须直接挂载到根multipart/mixed节点下，禁止挂载到正文子容器中
   • 如果仅需要纯文本正文，直接将MIMEText类型的正文部件挂载到根节点即可
2. 为附件显式指定Content-Transfer-Encoding: base64头，文件名使用Header类做UTF-8编码，兼容非ASCII字符和特殊符号
3. 最终生成原始邮件时使用as_bytes()方法代替as_string()，避免文本转码导致的内容损坏

修复后的参考代码：

from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText
from email.mime.application import MIMEApplication
from email.mime.image import MIMEImage
from email.header import Header
import magic

# 初始化根容器，固定为mixed类型
msg = MIMEMultipart('mixed')

# 可选：添加多版本正文
alt_container = MIMEMultipart('alternative')
# 纯文本正文
text_part = MIMEText("你的邮件正文内容", "plain", "utf-8")
alt_container.attach(text_part)
# HTML正文（不需要可以删掉）
html_part = MIMEText("<p>你的HTML邮件正文</p>", "html", "utf-8")
alt_container.attach(html_part)
# 正文容器挂载到根节点
msg.attach(alt_container)

# 处理附件
for filename, data in attached_data.items():
    mime_type = magic.from_buffer(data, mime=True)
    major_type, minor_type = mime_type.split("/", 1)

    if major_type == "application":
        attachment = MIMEApplication(data, minor_type)
    elif major_type == "image":
        attachment = MIMEImage(data, minor_type)
    else:
        attachment = MIMEApplication(data)

    # 显式指定传输编码
    attachment["Content-Transfer-Encoding"] = "base64"
    # 编码文件名，兼容中文和特殊字符
    encoded_filename = Header(filename, "utf-8").encode()
    attachment.add_header(
        "Content-Disposition",
        "attachment",
        filename=encoded_filename
    )
    # 附件直接挂载到根节点
    msg.attach(attachment)

# 生成二进制格式的原始邮件，避免转码错误
raw_message = msg.as_bytes()

修复后不需要实际发送邮件，直接将生成的邮件内容保存为.eml文件导入Thunderbird，能正常看到附件就说明MIME结构符合规范。

内容的提问来源于stack exchange，提问作者Dustin Oprea