Send HTML emails with Python

Dealing with HTML contents

Crafting the HTML email body requires creating two content versions: HTML and a plain text fallback. This fallback ensures that recipients using text-only email clients aren't left out.

text_version = "Hi, check out Real Python: http://www.realpython.com"  # Don't burn bridges — create a plain text version too!
message.attach(MIMEText(text_version, "plain"))


Setting the right email headers

Next, properly set the email headers - they're like the envelope of your email:

message.add_header('Content-Type', 'text/html')  # Your email client needs to know that this isn't just any email - it's an HTML email!


Attaching files and SMTP delivery

Who doesn't love attachments? Add them like so:

from email.mime.application import MIMEApplication

attachment = MIMEApplication(open('file.pdf', 'rb').read())  # Reading in binary, because PDFs aren't plain text.
attachment.add_header('Content-Disposition', 'attachment', filename='file.pdf')  # Attach the file with the original filename.
message.attach(attachment)  # Slap it onto the email.


Don't forget to validate your SMTP configurations and escape HTML special characters. Just like in a zombie apocalypse, security is key.

Ensuring SMTP transactions are handled properly

The SMTP connection allows for smooth mail delivery. You need to start it, use it, and then properly close it - kinda like a good Saturday night.

with smtplib.SMTP(host, port) as server:
    server.starttls()  # Secure the connection. Wrap it up, folks!
    server.login(username, password)  # Maybe the server will slide into your DMs after this. 🙃
    try:
        server.send_message(message)  # Try to send the email.
    finally:
        server.quit()  # Always quit... while you’re ahead? 🏃💨


Error handling isn't just about catching the error, it's also about letting your users know what went wrong. Not what they want, but what they need. Full transparency as service, please!

Going the Extra Mile

A few pointers when sending HTML emails:

Email Client Compatibility: Test your HTML and CSS on different email clients. Not every client is as forgiving as your mother.

Spam Filters: Watch out for spam filters. They hate fun stuff like large embedded images or multiple links. Tip: Keep your email size reasonable and make sure you have permission to reach out to the recipient.

Responsibility Matters: Use the with statement to manage connections, providing that neat closure you didn't get from your last relationship.

Additional Packages: Some packages like yagmail and py3dns can provide a simpler API experience. Sometimes working smarter results in less head-meet-desk situations.