Introduction
mailables is a developer-centric utility for sending asynchronous mails.
Requirements
Python 3.7+
Installation
$ pip install mailablesUsage
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 byFileTransport. -
aiosmtpdlib- required bySMTPTransport.
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) == 1NullTransport
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())
