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.

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 Python 3

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