Skip to main content

A developer-centric utility for sending asynchronous mails.

Project description

Build Status Coverage Package version


mailables is a developer-centric utility for sending asynchronous mails.


Python 3.7+


$ pip install mailables


from mailables import Mailer, EmailMessage

message = EmailMessage(
    to='User Name <>',
    text_body='This is sent using mailables!',
    html_body='<b>This is sent using mailables!</b>'

mailer = Mailer('smtp://localhost:25')
await mailer.send(message)


Mailables does not have any hard dependencies, but the following are optional:

You can install all of these with pip install mailables[full].


In order to send email you need to configure transport and mailer. Mailer is a class with which you would work all time. Think it is a public interface to mailables. And transport is a concrete adapter which does actual sending.

from mailables import Mailer

mailer = Mailer('smtp://localhost:25')

When you need to fine-grained control on the transport configuration you may pass the transport instance instead of URL string:

from mailables import Mailer, SMTPTransport
mailer = Mailer(SMTPTransport(host='localhost', port=25))

This approach gives you full control on transport construction.

Note, that you are not limited to one mailer only, your application may have multiple mailers with different transports/settings.

Mail message

The mail message is represented by EmailMessage class.

from mailables import EmailMessage

message = EmailMessage(
    to=['root@localhost', 'admin@localhost'],
    subject='This is a test email',
    text_body='And this is a body',
    html_body='And HTML body <b>supported</b> as well',

Attaching files

from mailables import EmailMessage, Attachment

message = EmailMessage(
        Attachment(contents='CONTENTS', file_name='file.txt')        

# or alternatively using `attach` method:
message.attach(contents='CONTENTS', file_name='file.txt')

# or you can add attachment instance using `add_attachment` method:


Here is the list of included transports


Sends messages using SMTP protocol.

from mailables import SMTPTransport

transport = SMTPTransport(host='localhost', port=25, use_ssl=True)


File transport does not send email to anywhere. It dumps messages into mailbox directory in *.eml format.

from mailables import FileTransport

transport = FileTransport(directory='/tmp/mailbox')


Stores sent emails in a local variable.

from mailables import InMemoryTransport, EmailMessage

storage = []
transport = InMemoryTransport(storage=storage)

# example:
transport.send(EmailMessage(subject='Hey', to='root@localhost'))
assert len(storage) == 1


This transport does not send anything at all. Use it when you want to completely silence the mailer.

from mailables import NullTransport

transport = NullTransport()

Building custom transports

Extend mailables.transport.BaseTransport class and implement async def send(self, message: EmailMessage) method:

For example, we will create a simple transport class for writing mails to a stdout:

from mailables import BaseTransport, EmailMessage, Mailer

class ConsoleTransport(BaseTransport):
    async def send(self, message: EmailMessage):

mailer = Mailer(ConsoleTransport())

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mailables-0.0.2.tar.gz (10.0 kB view hashes)

Uploaded source

Built Distribution

mailables-0.0.2-py3-none-any.whl (9.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page