Python发送邮件PDF附件在Outlook/Thunderbird不显示但Gmail正常的问题排查与修复求助

阿华AIGC实验室

2026-4-29

Fixing PDF Attachment Visibility in Thunderbird/Outlook with Python's EmailMessage

Hey there! Let's tackle your PDF attachment issue head-on. I've seen similar problems before, and the root cause usually boils down to how the MIME structure of your email is being built. Let's break this down into solutions, explanations, and learning resources.

Why This Happens

Your current code mixes the modern EmailMessage API with the older MIMEBase class, which can create an inconsistent MIME structure that strict clients like Thunderbird and Outlook refuse to parse correctly. Gmail is more lenient and automatically fixes these structural issues when you forward the email—which is why the attachment starts working after that.

When you use MIMEBase manually, you're bypassing some of the automatic structure management that EmailMessage provides. This leads to attachments not being properly encapsulated in the correct multipart/mixed section, which desktop clients require to recognize attachments.

The Fix: Use EmailMessage's Native Attachment Method

Instead of using MIMEBase and encoders, leverage EmailMessage's built-in add_attachment() method. This method handles all the MIME encoding, headers, and structure automatically, ensuring compatibility across all clients.

Here's your revised code:

from email.message import EmailMessage
import smtplib

msg = EmailMessage()
msg['Subject'] = subject
msg['From'] = "someaddress"
msg['To'] = user_email
msg.set_content('Certification')  # Plain text fallback for clients that don't support HTML
msg.add_alternative("""<!DOCTYPE html> <html> <body> Stuff... </body> </html> """, subtype='html')

filename = 'somefilename'
pdf_filename = 'certificate.pdf'
with open(filename, "rb") as attachment:
    # Use EmailMessage's native add_attachment to handle MIME structure correctly
    msg.add_attachment(
        attachment.read(),
        maintype='application',
        subtype='pdf',  # Explicitly specify PDF subtype instead of generic octet-stream
        filename=pdf_filename
    )

try:
    with smtplib.SMTP('someIP', port) as smtp:
        smtp.send_message(msg)
except Exception as e:
    print(f"Failed to send email: {e}")

Key improvements:

Removed MIMEBase and encoders entirely—add_attachment() handles base64 encoding automatically.
Specified subtype='pdf' instead of octet-stream, giving clients clear, explicit info about the attachment type.
Let EmailMessage manage the full MIME structure, eliminating manual errors.

Why This Works

EmailMessage is designed to handle MIME structures seamlessly:

When you add plain text, HTML, and attachments, it automatically creates a nested structure: an outer multipart/mixed layer (for attachments) containing a multipart/alternative section (for text vs HTML content).
This matches the exact structure that email clients expect, so there's no ambiguity about where attachments fit in the email hierarchy.

Your earlier attempt with msg.make_mixed() likely failed because it modified the structure after adding content, leading to conflicts. Using add_attachment() avoids this by letting EmailMessage handle structure from start to finish.

Learning Resources for Python Email Development

Since this is your second time working with email code, here are practical ways to deepen your understanding:

Python's Official Email Docs: The email module documentation has excellent examples for EmailMessage—start with the "Quickstart" and "Content Management" sections. It covers everything from basic text emails to complex multipart messages with attachments.
MIME Type Basics: Spend 10 minutes learning the difference between multipart/alternative (for different versions of the same content) and multipart/mixed (for content + attachments). This will help you debug structure issues in the future.
Inspect Raw Email Sources: In any email client, look for an option to view the "raw" or "source" of an email. Compare the raw source of your original email (with the broken attachment) to the Gmail-forwarded version. You'll see exactly how Gmail fixes the MIME structure, which is a great hands-on learning tool.
Test Across Clients: After making changes, send test emails to Thunderbird, Outlook, and Gmail to confirm compatibility. This helps catch client-specific quirks early.

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