Skip to main content

A developer-centric utility for sending asynchronous mails.

Project description

Build Status Coverage Package version


Introduction

mailables is a developer-centric utility 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:

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

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

Project details


Download files

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

Files for mailables, version 0.0.2
Filename, size File type Python version Upload date Hashes
Filename, size mailables-0.0.2-py3-none-any.whl (9.5 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size mailables-0.0.2.tar.gz (10.0 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page