eletter 0.1.0

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_="me@here.qq",
    to=[eletter.Address("My Dear", "my.beloved@love.love")],
    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 "address@domain.com" strings or as eletter.Address("Display Name", "address@domain.com") 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.

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

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