Introduction

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

Requirements

Python 3.7+

Installation

$ pip install mailables

Usage

from mailables import Mailer, EmailMessage

message = EmailMessage(
    to='User Name <user@example.com>',
    from_address='sender@example.com',
    subject='Hey',
    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)

Dependencies

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

• aiofiles - required by FileTransport.
• aiosmtpdlib - required by SMTPTransport.

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

Configuration

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'],
    from_address='user@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(
    attachments=[
        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:
message.add_attachment(Attachment('contents'))

Attaching files

Note, that reading files is blocking process and is harmful in asynchronous environment. You may want to use libraries like aiofiles to read files without blocking the thread.

from mailables import EmailMessage

with open('/path/to/file.txt') as f:
    message = EmailMessage()
    message.attach(f.read())

Transports

Here is the list of included transports

SMTPTransport

Sends messages using SMTP protocol.

from mailables import SMTPTransport

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

FileTransport

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')

InMemoryTransport

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

NullTransport

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):
        print(str(message))


mailer = Mailer(ConsoleTransport())