API reference

Component

class asphalt.mailer.component.MailerComponent(backend, resource_name='default', **mailer_args)

Bases: Component

Creates a Mailer resource.

Parameters:

backend (str) – entry point name of the mailer backend class
resource_name (str) – name of the mailer resource to be published
mailer_args (Any) – keyword arguments passed to the mailer backend class

async start(ctx)

Perform any necessary tasks to start the services provided by this component.

In this method, components typically use the context to:

add resources and/or resource factories to it (add_resource() and add_resource_factory())
request resources from it asynchronously (request_resource())

It is advisable for Components to first add all the resources they can to the context before requesting any from it. This will speed up the dependency resolution and prevent deadlocks.

Parameters:: ctx (Context) – the containing context for this component
Return type:: None

Interfaces

class asphalt.mailer.api.Mailer(message_defaults=None)

Bases: object

This is the abstract base class for all mailers.

Parameters:: message_defaults – default values for omitted keyword arguments of create_message()

classmethod add_attachment(msg, content, filename, mimetype=None)

Add binary data as an attachment to an EmailMessage.

The default value for the mimetype argument is guessed from the file name. If guessing fails, application/octet-stream is used.

Parameters:

msg (EmailMessage) – the message
content (bytes) – the contents of the attachment
filename (str) – the displayed file name in the message
mimetype (str | None) – the MIME type indicating the type of the file

Return type:

None

async classmethod add_file_attachment(msg, path, filename=None, mimetype=None)

Read the contents of a file and add them as an attachment to the given message.

Reads the file contents and then passes the result as content to add_attachment() along with the rest of the arguments.

Parameters:

msg (EmailMessage) – the message
path (str | Path) – path to the file to attach
filename (str | None) – the displayed file name in the message
mimetype (str | None) – the MIME type indicating the type of the file

Return type:

None

create_and_deliver(**kwargs)

Build a new email message and deliver it.

This is a shortcut to calling create_message() and then passing the result to deliver().

Parameters:: kwargs – keyword arguments passed to create_message()

create_message(*, subject=None, sender=None, to=None, cc=None, bcc=None, charset=None, plain_body=None, html_body=None)

Create an EmailMessage using to be sent later using deliver().

Parameters:

subject (str | None) – subject line for the message
sender (str | Address | None) – sender address displayed in the message (the From: header)
to (AddressListType | None) – primary recipient(s) (displayed in the message)
cc (AddressListType | None) – secondary recipient(s) (displayed in the message)
bcc (AddressListType | None) – secondary recipient(s) (not displayed in the message)
charset (str | None) – character encoding of the message
plain_body (str | None) – plaintext body
html_body (str | None) – HTML body

Return type:

EmailMessage

abstract async deliver(messages)

Deliver the given message(s).

Parameters:: messages – the message or iterable of messages to deliver

async start()

Perform any necessary setup procedures.

This method is called by the component on initialization.

Return type:: None

Exceptions

exception asphalt.mailer.api.DeliveryError(error, message=None)

Bases: Exception

Raised when there’s an error with mail delivery.

Variables:

error – the error message
message – the email message related to the failure, if any

Utilities

asphalt.mailer.utils.get_recipients(message)

Return a list of email addresses of all the intended recipients of the given message.

This function is meant to be used by Mailer implementations.

Parameters:: message – the source email message

Mailer back-ends

class asphalt.mailer.mailers.smtp.SMTPMailer(*, host='localhost', port=None, tls=None, tls_context=None, username=None, password=None, timeout=10, message_defaults=None)

Bases: Mailer

A mailer that uses aiosmtplib to send mails.

The default port is chosen as follows:

587: if username and password have been defined and tls is True
25: in all other cases

Parameters:

host (str) – host name of the SMTP server
port (int | None) – override the default port (see above)
tls (bool | None) – whether to initiate TLS using STARTTLS once connected (defaults to True if username and password have been defined)
tls_context (str | SSLContext | None) – either an SSLContext instance or the resource name of one
username (str | None) – username to authenticate as
password (str | None) – password to authenticate with
timeout (float) – timeout (in seconds) for all network operations
message_defaults (dict[str, Any] | None) – default values for omitted keyword arguments of create_message()

async deliver(messages)

Deliver the given message(s).

Parameters:: messages – the message or iterable of messages to deliver

async start()

Perform any necessary setup procedures.

This method is called by the component on initialization.

Return type:: None

class asphalt.mailer.mailers.sendmail.SendmailMailer(*, path='/usr/sbin/sendmail', message_defaults=None)

Bases: Mailer

A mailer that sends mail by running the sendmail executable in a subprocess.

Parameters:

path (str | Path) – path to the sendmail executable
message_defaults (dict[str, Any] | None) – default values for omitted keyword arguments of create_message()

async deliver(messages)

Deliver the given message(s).

Parameters:: messages – the message or iterable of messages to deliver

class asphalt.mailer.mailers.mock.MockMailer(*, message_defaults=None)

Bases: Mailer

A mailer that does not send any messages but instead stores them in a member variable.

Parameters:: message_defaults – default values for omitted keyword arguments of create_message()
Variables:: messages – list of messages that would normally have been sent

async deliver(messages)

Deliver the given message(s).

Parameters:: messages – the message or iterable of messages to deliver