Modern email handling in python.

m = emails.Message(html=T("<html><p>Build passed: {{ project_name }} <img src='cid:icon.png'> ..."),
                   text=T("Build passed: {{ project_name }} ..."),
                   subject=T("Passed: {{ project_name }}#{{ build_id }}"),
                   mail_from=("CI", ""))
m.attach(filename="icon.png", content_disposition="inline", data=open("icon.png", "rb"))
response = m.send(render={"project_name": "user/project1", "build_id": 121},
                  smtp={"host":"", "port": 25})

if response.status_code not in [250, ]:
    # message is not sent, retry later

See the same code, without Emails.

Emails code is not much simpler than the same code in django, but it is still more elegant, can be used in django environment and has html transformation methods (see HTML Transformer section).


  • HTML-email message abstraction
  • Method to transform html body:
    • css inlining (using peterbe’s premailer)
    • image inlining
  • DKIM signature
  • Message loaders
  • Send directly or via django email backend


Create message:

import emails
message = emails.html(html=open('letter.html'),
                      subject='Friday party',
                      mail_from=('Company Team', ''))

Attach files or inline images:

message.attach(data=open('event.ics', 'rb'), filename='Event.ics')
message.attach(data=open('image.png', 'rb'), filename='image.png',

Use templates:

from emails.template import JinjaTemplate as T

message = emails.html(subject=T('Payment Receipt No.{{ billno }}'),
                      html=T('<p>Dear {{ name }}! This is a receipt...'),
                      mail_from=('ABC', ''))

message.send(to=('John Brown', ''),
             render={'name': 'John Brown', 'billno': '141051906163'})

Add DKIM signature:

message.dkim(key=open('my.key'), domain='', selector='newsletter')

Generate email.message or rfc822 string:

m = message.as_message()
s = message.as_string()

Send and get response from smtp server:

r = message.send(to=('John Brown', ''),
                 render={'name': 'John'},
                 smtp={'host':'', 'port': 465, 'ssl': True, 'user': 'john', 'password': '***'})
assert r.status_code == 250


DjangoMessage helper sends via django configured email backend:

from emails.django import DjangoMessage as Message
message = Message(...)
message.send(mail_to=('John Brown', ''),
             context={'name': 'John'})


For flask integration take a look at flask-emails

HTML transformer

Message HTML body usually should be modified before sent.

Base transformations, such as css inlining can be made by Message.transform method:

>>> message = emails.Message(html="<style>h1{color:red}</style><h1>Hello world!</h1>")
>>> message.transform()
>>> message.html
u'<html><head></head><body><h1 style="color:red">Hello world!</h1></body></html>'

Message.transform can take some arguments with speaken names css_inline, remove_unsafe_tags, make_links_absolute, set_content_type_meta, update_stylesheet, images_inline.

More specific transformation can be made via transformer property.

Example of custom link transformations:

>>> message = emails.Message(html="<img src='promo.png'>")
>>> message.transformer.apply_to_images(func=lambda src, **kw: 'http://mycompany.tld/images/'+src)
>>> message.html
u'<html><body><img src="http://mycompany.tld/images/promo.png"></body></html>'

Example of customized making images inline:

>>> message = emails.Message(html="<img src='promo.png'>")
>>> message.attach(filename='promo.png', data=open('promo.png', 'rb'))
>>> message.attachments['promo.png'].is_inline = True
>>> message.transformer.synchronize_inline_images()
>>> message.html
u'<html><body><img src="cid:promo.png"></body></html>'


python-emails ships with couple of loaders.

Load message from url:

import emails.loader
message = emails.loader.from_url(url="")

Load from zipfile or directory:

message = emails.loader.from_zipfile(open('', 'rb'))
message = emails.loader.from_directory('/home/user/design_pack')

Zipfile and directory loaders require at least one html file (with “html” extension).

Load message from .eml file (experimental):

message = emails.loader.from_rfc822(open('message.eml').read())


Install from pypi:

$ [sudo] pip install emails

Install on Ubuntu from PPA:

$ [sudo] add-apt-repository ppa:lavrme/python-emails-ppa
$ [sudo] apt-get update
$ [sudo] apt-get install python-emails


  • Documentation
  • Increase test coverage
  • Feature: load message from rfc2822
  • Feature: export message to directory or zipfile
  • Distribution: deb package (debianization example)
  • Distribution: rpm package
  • Other: Flask extension
  • Feature: ESP integration - Amazon SES, SendGrid, …

How to Help

Library is under development and contributions are welcome.

  1. Open an issue to start a discussion around a bug or a feature.
  2. Fork the repository on GitHub and start making your changes to a new branch.
  3. Write a test which shows that the bug was fixed.
  4. Send a pull request. Make sure to add yourself to AUTHORS.

See also

There are plenty other python email-around libraries that may fit your needs: