python-emails

Build, transform, and send emails in Python with a high-level API.

python-emails helps you compose HTML and plain-text messages, attach files, embed inline images, render templates, apply HTML transformations, sign with DKIM, and send through SMTP without hand-building MIME trees.

Why python-emails

A concise API over email and smtplib
HTML and plain-text messages in one object
File attachments and inline images
CSS inlining, image embedding, and HTML cleanup
Jinja2, Mako, and string template support
DKIM signing
Loaders for URLs, HTML files, directories, ZIP archives, and RFC 822 messages
SMTP sending with SSL/TLS support
Async sending via aiosmtplib

Quick Example

import emails

message = emails.html(
    subject="Your receipt",
    html="<p>Hello!</p><p>Your payment was received.</p>",
    mail_from=("Billing", "[email protected]"),
)
message.attach(filename="receipt.pdf", data=open("receipt.pdf", "rb"))

response = message.send(
    to="[email protected]",
    smtp={
        "host": "smtp.example.com",
        "port": 587,
        "tls": True,
        "user": "[email protected]",
        "password": "app-password",
    },
)
assert response.status_code == 250

Installation

Install the lightweight core:

pip install emails

Install HTML transformation features such as CSS inlining, image embedding, and loading from URLs or files:

pip install "emails[html]"

Install Jinja2 template support for the JinjaTemplate class:

pip install "emails[jinja]"

Install async SMTP sending support for send_async():

pip install "emails[async]"

Common Tasks

Build and send your first message:

Quickstart

Configure installation extras:

Install guide

Inline CSS, embed images, and customize HTML processing:

Advanced Usage

Learn the full public API:

API Reference

Troubleshoot common scenarios:

FAQ

Explore alternatives and related projects:

Links

What You Get

Message composition for HTML, plain text, headers, CC/BCC, and Reply-To
Attachments, inline images, and MIME generation
Template rendering in html, text, and subject
HTML transformations through message.transform()
SMTP delivery through config dicts or reusable backend objects
Django integration via DjangoMessage
Flask integration via flask-emails

When To Use It

Use python-emails when you need more than a minimal plain-text SMTP call: HTML emails, attachments, inline images, template rendering, DKIM, message loading from external sources, or a cleaner API than hand-written email.mime code.

If you only need to send a very small plain-text message and want zero dependencies, the standard library may be enough.

Documentation

Project Status

python-emails is production/stable software and currently supports Python 3.10 through 3.14.

Contributing

Issues and pull requests are welcome.

License

Apache 2.0. See LICENSE.

emails