Sending HTML Emails and Attachments

diagram the shape of an HTML email with an attachment mermaid

  flowchart TD
  A["multipart/mixed"] --> B["multipart/alternative"]
  A --> C["text/csv -- data.csv"]
  B --> D["text/plain -- the fallback"]
  B --> E["text/html -- the rich version"]
  D -.->|"a text-only client shows this"| F["readable everywhere"]
  E -.->|"a normal client shows this"| G["the client picks the LAST part it can render"]
  C --> H["Content-Disposition: attachment"]

An email that has a plain-text fallback, an HTML body and a file is three nested containers, not one message with extras bolted on. multipart/alternative holds the two versions of the same content and lets the client choose; multipart/mixed wraps that together with the attachment. Building it in the wrong order is why an attachment sometimes replaces the body.

The tree, as actually produced

python

m = EmailMessage()
m.set_content("plain text fallback")
m.add_alternative("<h1>HTML version</h1>", subtype="html")
m.add_attachment(b"col1,col2\n1,2\n", maintype="text", subtype="csv", filename="data.csv")

gives:

text

multipart/mixed
  multipart/alternative
    text/plain
    text/html
  text/csv          data.csv

Two things follow from that structure.

Order inside multipart/alternative matters. The plain-text part comes first and the HTML second, because a client renders the last part it understands. Reversing them means every graphical client shows your plain-text fallback.

Always include the plain-text part. It is what a text-only reader, a screen reader and most spam filters actually look at — and set_content followed by add_alternative is the pair that produces it. Sending HTML alone is both less accessible and more likely to be filtered.

HTML email + attachment

smtp_html_attachment.py

import os
import smtplib
from email.message import EmailMessage
from pathlib import Path
 
 
def send_html_with_attachment(to: str, subject: str, html: str, attachment: Path):
    user = os.environ["SMTP_USER"]
    password = os.environ["SMTP_PASS"]
 
    msg = EmailMessage()
    msg["From"] = user
    msg["To"] = to
    msg["Subject"] = subject
 
    msg.set_content("Your email client does not support HTML.")
    msg.add_alternative(html, subtype="html")
 
    data = attachment.read_bytes()
    msg.add_attachment(
        data,
        maintype="application",
        subtype="octet-stream",
        filename=attachment.name,
    )
 
    with smtplib.SMTP("smtp.gmail.com", 587) as smtp:
        smtp.starttls()
        smtp.login(user, password)
        smtp.send_message(msg)
 
 
# send_html_with_attachment("to@example.com", "Report", "<h1>Hi</h1>", Path("report.pdf"))