API¶

Anything documented here is part of the public API that Email-Simplified provides, unless otherwise indicated. Anything not documented here is considered internal or private and may change at any time.

Handlers¶

email_simplified.get_handler_class(name)¶

Get a EmailHandler implementation by name.

First looks up if the name is in the email_simplified.handler entry point namespace, and loads the referenced class if it is. Libraries providing handler implementations should register a handler’s name so that it’s automatically available when installed.

If an entry point is not found, attempts to treat the name as an import path in the form module.submodule:handler_class. This is useful for users writing their own handler locally where adding an entry point may not be possible. May also be passed an actual handler class, in which case it’s returned directly.

Parameters:: name (str | type[EmailHandler]) – The registered entry point name, import path, or handler class to load and return.
Return type:: type[EmailHandler]

class email_simplified.SMTPEmailHandler(*, host=None, port=None, use_tls=None, use_starttls=False, tls_context=None, timeout=None, username=None, password=None, default_from=None, recipients_per_message=None)¶

Email handler that sends with SMTP using Python’s built-in smtplib. All arguments are optional, smtplib.SMTP uses default values if something is not given.

Parameters:

host (str | None) – Host to connect to.
port (int | None) – Port to connect to.
use_tls (bool | None) – The connection should be established with TLS. Default is True if port is 465.
use_starttls (bool) – The connection should be upgraded to TLS after establishing a plain connection first. You should prefer use_tls instead if your SMTP server supports it.
tls_context (SSLContext | None) – An ssl.SSLContext to use when use_tls or use_starttls is enabled. Defaults to ssl.create_default_context(), which enables verifying any server cert trusted by the OS. You should only need to change this if the server uses a custom cert, or needs a client cert sent as well.
timeout (float | None) – Connection timeout. Default is no timeout.
username (str | None) – Username to log in with.
password (str | None) – Password to log in with.
default_from (str | None) – Default address to send from if the Sender or From header is not set on a message.
recipients_per_message (int | None) – If a message has more than this number of recipients, split the send calls to batches of this size. This is to support servers that have a limit configured. By default, no batching is done.

host¶: Host to connect to.

port¶: Port to connect to.

timeout¶: Connection timeout.

username¶: Username to log in with.

password¶: Password to log in with.

default_from¶: Default address to send from if the Sender or From header is not set on a message.

recipients_per_message¶: If a message has more than this number of recipients, split the low-level send calls to batches of this size. This is to support servers that have a limit configured. By default no batching is done.

use_tls¶: The connection should be established with TLS.

use_starttls: bool¶: The connection should be upgraded to TLS after establishing a plain connection first.

tls_context¶: An ssl.SSLContext to use when use_tls or use_starttls is enabled.

classmethod from_config(config)¶

Create a handler from a config dict. Config keys match the arguments to SMTPEmailHandler, and are all optional.

Parameters:: config (dict[str, Any])
Return type:: Self

connect()¶

Context manager that creates an smtplib.SMTP client, connects, logs in, then closes when exiting the block.

Return type:: Iterator[SMTP]

send(messages)¶

Send one or more email messages.

Messages should typically be Message. However, they may also be email.message.EmailMessage for cases where a non-standard MIME construction is needed. It is up to the handler to decide whether that is supported based on what their service is capable of.

Parameters:: messages (list[Message | EmailMessage]) – A list of messages to send.
Return type:: None

class email_simplified.TestEmailHandler¶

Email handler that appends messages to a list rather than sending them. Useful when testing.

outbox: list[Message | EmailMessage]¶: List of messages that have been sent with this handler.

classmethod from_config(config)¶

Create an instance of this handler using arguments from config as needed. This is useful for frameworks when paired with get_handler_class(), allowing the deployment to configure an arbitrary handler and its arguments.

Parameters:: config (dict[str, Any])
Return type:: Self

send(messages)¶

Send one or more email messages.

Parameters:: messages (list[Message | EmailMessage]) – A list of messages to send.
Return type:: None

async send_async(messages)¶

Send one or more email messages, as with send(), but in an async context.

Parameters:: messages (list[Message | EmailMessage])
Return type:: None

class email_simplified.handlers.EmailHandler¶

Interface for sending email messages. Subclasses will define how to send using a service, such as SMTP, an email provider’s API, etc.

send(messages)¶

Send one or more email messages.

Parameters:: messages (list[Message | EmailMessage]) – A list of messages to send.
Return type:: None

async send_async(messages)¶

Send one or more email messages, as with send(), but in an async context.

Parameters:: messages (list[Message | EmailMessage])
Return type:: None

classmethod from_config(config)¶

Parameters:: config (dict[str, Any])
Return type:: Self

Messages¶

class email_simplified.Message(*, subject=None, text=None, from_addr=None, reply_to=None, to=None, cc=None, bcc=None, attachments=None, html=None, inline_attachments=None)¶

A representation of the typical data found in an email message. Can be converted to and from an email.message.EmailMessage.

While unlikely, MIME messages can be constructed pretty much arbitrarily. This class only represents a “common”/”standard” message structure with text, HTML, download attachments, and inline attachments.

Addresses passed to the various arguments/attributes can be strings in the form user@domain or Name <user@domain>, or instances of email.headerregistry.Address. If the user part has non-ASCII characters, SMTP servers must support the SMTPUTF8 extension. The domain part will be encoded using IDNA.

Parameters:

subject (str | None) – The text in the subject line of the message.
text (str | None) – The plain text content.
from_addr (str | Address | None) – The address to show the message was sent from.
reply_to (str | Address | None) – Instruct users to reply to this address rather than from_addr.
to (list[str | Address] | None) – The primary recipients, visible and replied to by all other recipients.
cc (list[str | Address] | None) – The secondary recipients, visible and replied to by all other recipients.
bcc (list[str | Address] | None) – Hidden recipients. Not visible or replied to by any other recipients. When sending mass email, use this instead of to and cc to avoid “reply all email storms”.
attachments (list[Attachment] | None) – Downloadable files separate from the content.
html (str | None) – The HTML text content. text content should also be provided, but if it’s not then text is extracted from the HTML.
inline_attachments (list[Attachment] | None) – Files that can be linked and displayed inside HTML content. Only relevant when html content is provided.

subject: str | None¶: The text in the subject line of the message.

text: str | None¶: The plain text content.

html: str | None¶: The HTML text content. text content should also be provided, but if it’s not then text is extracted from the HTML.

attachments: list[Attachment]¶: Downloadable files separate from the content.

inline_attachments: list[Attachment]¶: Files that can be linked and displayed inside HTML content. Only relevant when html content is provided.

property from_addr: Address | None¶: The address to show the message was sent from.

property reply_to: Address | None¶: Instruct users to reply to this address rather than from_addr.

property to: AddressList¶: The primary recipients, visible and replied to by all other recipients.

property cc: AddressList¶: The secondary recipients, visible and replied to by all other recipients.

property bcc: AddressList¶: Hidden recipients. Not visible or replied to by any other recipients When sending mass email, use this instead of to and cc to avoid “reply all email storms”.

to_mime()¶

Convert this email_simplified.Message to an email.message.EmailMessage.

Return type:: EmailMessage

classmethod from_mime(message)¶

Convert an email.message.EmailMessage message to a email_simplified.Message.

MIME messages can potentially have arbitrary structures. This only supports converting from a “standard” structure where a message has text, html, inline attachment, and download attachment parts. Can be one of the following:

One text/plain part.
One multipart/alternative part containing one text/plain part then either:
- One text/html part.
- One multipart/related part containing one text/html part then one or more inline attachment parts.
One multipart/mixed part containing one of the above parts then one or more download attachment parts.

Parameters:: message (EmailMessage) – The MIME part message to convert.
Return type:: Self

class email_simplified.Attachment(data, *, filename=None, mimetype=None)¶

Structured representation of an email attachment.

Parameters:

data (str | bytes) – Text or bytes data to attach.
filename (str | None) – Filename to show for the attachment.
mimetype (str | None) – Mimetype describing the attached data. Defaults to guessing from filename if possible, or text/plain for text data or application/octet-stream for bytes data.

data¶: Text or bytes data to attach.

filename¶: Filename to show for the attachment.

mimetype: str¶: Mimetype describing the attached data. Defaults to guessing from filename if possible, or text/plain for text data or application/octet-stream for bytes data.

property cid: str¶: The id used to refer to the inline attachment in HTML. Generated on access if not set.

add_to_mime(message, *, inline=False)¶

Add this attachment to the given email.message.EmailMessage. When attaching inline, include the :attr:`cid, otherwise the filename.

Parameters:

message (EmailMessage) – The message to attach to.
inline (bool) – Attach inline for linking from HTML.

Return type:

None