eletter 0.1.0

Simple e-mail composition

GitHub | PyPI | Issues

eletter provides a basic function for constructing an email.message.EmailMessage instance without having to touch the needlessly complicated EmailMessage class itself. E-mails with text bodies and/or HTML bodies plus attachments are supported. Support for more complex e-mails is planned for later.

Installation

eletter requires Python 3.6 or higher. Just use pip for Python 3 (You have pip, right?) to install eletter and its dependencies:

python3 -m pip install eletter

Example

import eletter

TEXT = (
    "Oh my beloved!\n"
    "\n"
    "Wilt thou dine with me on the morrow?\n"
    "\n"
    "We're having hot pockets.\n"
    "\n"
    "Love, Me\n"
)

HTML = (
    "<p>Oh my beloved!</p>\n"
    "<p>Wilt thou dine with me on the morrow?</p>\n"
    "<p>We're having <strong>hot pockets</strong>.<p>\n"
    "<p><em>Love</em>, Me</p>\n"
)

with open("hot-pocket.png", "rb") as fp:
    picture = eletter.BytesAttachment(
        content=fp.read(),
        filename="enticement.png",
        content_type="image/png",
    )

msg = eletter.compose(
    subject="Meet Me",
    from_="[e-mail]",
    to=[eletter.Address("My Dear", "[e-mail]")],
    text=TEXT,
    html=HTML,
    attachments=[picture],
)

# Now you can send `msg` like any other EmailMessage, say, by using
# outgoing <https://github/jwodder/outgoing>.

API

eletter.compose(
    subject: str,
    from_: Union[str, Address],
    to: Iterable[Union[str, Address]],
    text: Optional[str] = None,
    html: Optional[str] = None,
    cc: Optional[Iterable[Union[str, Address]]] = None,
    bcc: Optional[Iterable[Union[str, Address]]] = None,
    reply_to: Optional[Union[str, Address]] = None,
    sender: Optional[Union[str, Address]] = None,
    date: Optional[datetime.datetime] = None,
    attachments: Optional[Iterable[Attachment]] = None,
    headers: Optional[Mapping[str, Union[str, Iterable[str]]]] = None,
) -> email.message.EmailMessage

Construct an EmailMessage instance from a subject, “From:” address, “To:” value, and a plain text and/or HTML body, optionally accompanied by attachments and other headers.

Addresses are specified as either "[e-mail]" strings or as eletter.Address("Display Name", "[e-mail]") objects.

Arguments:

subjectstring (required)

The e-mail’s “Subject:” line

from_address (required)

The e-mail’s “From:” line. Note that this argument is spelled with an underscore, as “from” is a keyword in Python.

toiterable of addresses (required)

The e-mail’s “To:” line

textstring

The contents of a text/plain body for the e-mail. At least one of text and html must be specified.

htmlstring

The contents of a text/html body for the e-mail. At least one of text and html must be specified.

cciterable of addresses (optional)

The e-mail’s “CC:” line

bcciterable of addresses (optional)

The e-mail’s “BCC:” line

reply_toaddress (optional)

The e-mail’s “Reply-To:” line

senderaddress (optional)

The e-mail’s “Sender:” line

datedatetime (optional)

The e-mail’s “Date:” line

attachmentsiterable of attachments (optional)

A collection of attachments (see below) to append to the e-mail

headersmapping from header names to strings or iterables of strings (optional)

A collection of additional headers to add to the e-mail. A header value may be either a single string or an iterable of strings to add multiple headers with the same name.

Attachment Objects

eletter has two concrete attachment classes, TextAttachment and BytesAttachment:

eletter.BytesAttachment(
    content: bytes,
    filename: str,
    content_type: str = "application/octet-stream",
    inline: bool = False,
)

Representation of a binary attachment.

eletter.TextAttachment(
    content: str,
    filename: str,
    content_type: str = "text/plain",
    inline: bool = False,
)

Representation of a text attachment. The content type must have a maintype of “text”.