API

The compose() Function

eletter.compose(*, to: Iterable[str | Address | Group], from_: str | Address | Group | Iterable[str | Address | Group] | None = None, subject: str | None = None, text: str | None = None, html: str | None = None, cc: Iterable[str | Address | Group] | None = None, bcc: Iterable[str | Address | Group] | None = None, reply_to: str | Address | Group | Iterable[str | Address | Group] | None = None, sender: str | Address | None = None, date: datetime | None = None, headers: Mapping[str, str | Iterable[str]] | None = None, attachments: Iterable[Attachment] | None = None) → EmailMessage

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

All parameters other than to and at least one of text and html are optional.

Changed in version 0.2.0: from_ and reply_to may now be passed lists of addresses.

Changed in version 0.4.0: from_ may now be None or omitted.

Changed in version 0.4.0: All arguments are now keyword-only.

Changed in version 0.5.0: subject may now be None or omitted.

Parameters:

• subject (str) – The e-mail’s Subject line

• to (iterable of addresses) – The e-mail’s To line

• from_ (address or iterable of addresses) – The e-mail’s From line. Note that this argument is spelled with an underscore, as “from” is a keyword in Python.

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

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

• cc (iterable of addresses) – The e-mail’s CC line

• bcc (iterable of addresses) – The e-mail’s BCC line

• reply_to (address or iterable of addresses) – The e-mail’s Reply-To line

• sender (address) – The e-mail’s Sender line. The address must be a string or Address, not a Group.

• date (datetime) – The e-mail’s Date line

• attachments (iterable of attachments) – A collection of attachments to append to the e-mail

• headers (mapping) – 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. If you wish to set an otherwise-unsupported address header like Resent-From to a list of addresses, use the format_addresses() function to first convert the addresses to a string.

Return type:

email.message.EmailMessage

Raises:

ValueError – if neither text nor html is set

Addresses

Addresses in eletter can be specified in three ways:

• As an "address@domain.com" string giving just a bare e-mail address

• As an eletter.Address("Display Name", "address@domain.com") instance pairing a person’s name with an e-mail address

• As an eletter.Group("Group Name", iterable_of_addresses) instance specifying a group of addresses (strings or Address instances)

Note

eletter.Address and eletter.Group are actually just subclasses of Address and Group from email.headerregistry with slightly more convenient constructors. You can also use the standard library types directly, if you want to.

class eletter.Address(display_name: str, address: str)

A combination of a person’s name and their e-mail address

class eletter.Group(display_name: str, addresses: Iterable[str | Address])

Added in version 0.2.0.

An e-mail address group

MailItem Classes

class eletter.MailItem

Added in version 0.3.0.

Base class for all eletter message components

compose(*, to: Iterable[str | Address | Group], from_: str | Address | Group | Iterable[str | Address | Group] | None = None, subject: str | None = None, cc: Iterable[str | Address | Group] | None = None, bcc: Iterable[str | Address | Group] | None = None, reply_to: str | Address | Group | Iterable[str | Address | Group] | None = None, sender: str | Address | None = None, date: datetime | None = None, headers: Mapping[str, str | Iterable[str]] | None = None) → EmailMessage

Convert the MailItem into an EmailMessage with the item’s contents as the payload and with the given subject, From address, To addresses, and optional other headers.

All parameters other than to are optional.

Changed in version 0.4.0: from_ may now be None or omitted.

Changed in version 0.4.0: All arguments are now keyword-only.

Changed in version 0.5.0: subject may now be None or omitted.

Parameters:

• subject (str) – The e-mail’s Subject line

• to (iterable of addresses) – The e-mail’s To line

• from_ (address or iterable of addresses) – The e-mail’s From line. Note that this argument is spelled with an underscore, as “from” is a keyword in Python.

• cc (iterable of addresses) – The e-mail’s CC line

• bcc (iterable of addresses) – The e-mail’s BCC line

• reply_to (address or iterable of addresses) – The e-mail’s Reply-To line

• sender (address) – The e-mail’s Sender line. The address must be a string or Address, not a Group.

• date (datetime) – The e-mail’s Date line

• headers (mapping) – 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. If you wish to set an otherwise-unsupported address header like Resent-From to a list of addresses, use the format_addresses() function to first convert the addresses to a string.

Return type:

email.message.EmailMessage

Attachments

class eletter.Attachment

Base class for the attachment classes

class eletter.BytesAttachment(content: bytes, filename: str | None, *, content_id: str | None = None, content_type: str = NOTHING, inline: bool = False)

A binary e-mail attachment. content_type defaults to "application/octet-stream".

content: bytes

The body of the attachment

content_id: str | None

Added in version 0.3.0.

Content-ID header value for the item

content_type: str

The Content-Type of the attachment

filename: str | None

The filename of the attachment

Changed in version 0.5.0: filename can now be None.

classmethod from_file(path: bytes | str | PathLike[bytes] | PathLike[str], content_type: str | None = None, inline: bool = False, content_id: str | None = None) → BytesAttachment

Added in version 0.2.0.

Construct a BytesAttachment from the contents of the file at path. The filename of the attachment will be set to the basename of path. If content_type is None, the Content-Type is guessed based on path’s file extension.

Changed in version 0.3.0: inline and content_id arguments added

inline: bool

Whether the attachment should be displayed inline in clients

class eletter.EmailAttachment(content: EmailMessage, filename: str | None, *, content_id: str | None = None, inline: bool = False)

Added in version 0.2.0.

A message/rfc822 e-mail attachment

content: EmailMessage

The body of the attachment

content_id: str | None

Added in version 0.3.0.

Content-ID header value for the item

filename: str | None

The filename of the attachment

Changed in version 0.5.0: filename can now be None.

classmethod from_file(path: bytes | str | PathLike[bytes] | PathLike[str], inline: bool = False, content_id: str | None = None) → EmailAttachment

Construct an EmailAttachment from the contents of the file at path. The filename of the attachment will be set to the basename of path.

inline: bool

Whether the attachment should be displayed inline in clients

class eletter.TextAttachment(content: str, filename: str | None, *, content_id: str | None = None, content_type: str = NOTHING, inline: bool = False)

A textual e-mail attachment. content_type defaults to "text/plain" and must have a maintype of text.

content: str

The body of the attachment

content_id: str | None

Added in version 0.3.0.

Content-ID header value for the item

content_type: str

The Content-Type of the attachment

filename: str | None

The filename of the attachment

Changed in version 0.5.0: filename can now be None.

classmethod from_file(path: bytes | str | PathLike[bytes] | PathLike[str], content_type: str | None = None, encoding: str | None = None, errors: str | None = None, inline: bool = False, content_id: str | None = None) → TextAttachment

Added in version 0.2.0.

Construct a TextAttachment from the contents of the file at path. The filename of the attachment will be set to the basename of path. If content_type is None, the Content-Type is guessed based on path’s file extension. encoding and errors are used when opening the file and have no relation to the Content-Type.

Changed in version 0.3.0: inline and content_id arguments added

inline: bool

Whether the attachment should be displayed inline in clients

Body Classes

class eletter.HTMLBody(content: str, *, content_id: str | None = None)

Added in version 0.3.0.

A text/html e-mail body

content: str

The HTML source of the body

content_id: str | None

Added in version 0.3.0.

Content-ID header value for the item

class eletter.TextBody(content: str, *, content_id: str | None = None)

Added in version 0.3.0.

A text/plain e-mail body

content: str

The plain text body

content_id: str | None

Added in version 0.3.0.

Content-ID header value for the item

Multipart Classes

class eletter.Multipart

Added in version 0.3.0.

Base class for all multipart classes. All such classes are mutable sequences of MailItems supporting the usual methods (construction from an iterable, subscription, append(), pop(), etc.).

class eletter.Alternative(content: Iterable[MailItem] = NOTHING, *, content_id: str | None = None)

Added in version 0.3.0.

A multipart/alternative e-mail payload. E-mails clients will display the resulting payload by choosing whichever part they support best.

An Alternative instance can be created by combining two or more MailItems with the | operator:

text = TextBody("This is displayed on plain text clients.\n")
html = HTMLBody("<p>This is displayed on graphical clients.<p>\n")

alternative = text | html

Likewise, additional MailItems can be added to an Alternative instance with the |= operator:

# Same as above:
alternative = Alternative()
alternative |= TextBody("This is displayed on plain text clients.\n")
alternative |= HTMLBody("<p>This is displayed on graphical clients.<p>\n")

Using | to combine a MailItem with a str automatically converts the str to a TextBody:

# Same as above:

text = "This is displayed on plain text clients.\n"
html = HTMLBody("<p>This is displayed on graphical clients.<p>\n")

alternative = text | html

assert alternative.contents == [
    TextBody("This is displayed on plain text clients.\n"),
    HTMLBody("<p>This is displayed on graphical clients.<p>\n"),
]

When combining two Alternative instances with | or |=, the contents are “flattened”:

# Same as above:
txtalt = Alternative([
    TextBody("This is displayed on plain text clients.\n")
])
htmlalt = Alternative([
    HTMLBody("<p>This is displayed on graphical clients.<p>\n")
])
alternative = txtalt | htmlalt
assert alternative.contents == [
    TextBody("This is displayed on plain text clients.\n"),
    HTMLBody("<p>This is displayed on graphical clients.<p>\n"),
]

Changed in version 0.4.0: Using | to combine a MailItem with a str now automatically converts the str to a TextBody

content: list[MailItem]

The MailItems contained within the instance

content_id: str | None

Added in version 0.3.0.

Content-ID header value for the item

class eletter.Mixed(content: Iterable[MailItem] = NOTHING, *, content_id: str | None = None)

Added in version 0.3.0.

A multipart/mixed e-mail payload. E-mails clients will display the resulting payload one part after another, with attachments displayed inline if their inline attribute is set.

A Mixed instance can be created by combining two or more MailItems with the & operator:

text = TextBody("Look at the pretty kitty!\n")
image = BytesAttachment.from_file("snuffles.jpeg", inline=True)
sig = TextBody("Sincerely, Me\n")

mixed = text & image & sig

Likewise, additional MailItems can be added to a Mixed instance with the &= operator:

# Same as above:
mixed = Mixed()
mixed &= TextBody("Look at the pretty kitty!\n")
mixed &= BytesAttachment.from_file("snuffles.jpeg", inline=True)
mixed &= TextBody("Sincerely, Me\n")

Using & to combine a MailItem with a str automatically converts the str to a TextBody:

# Same as above:
image = BytesAttachment.from_file("snuffles.jpeg", inline=True)

mixed = "Look at the pretty kitty!\n" & image & "Sincerely, Me\n"

assert mixed.contents == [
    TextBody("Look at the pretty kitty!\n"),
    BytesAttachment.from_file("snuffles.jpeg", inline=True),
    TextBody("Sincerely, Me\n"),
]

When combining two Mixed instances with & or &=, the contents are “flattened”:

part1 = Mixed()
part1 &= TextBody("Look at the pretty kitty!\n")
part1 &= BytesAttachment.from_file("snuffles.jpeg", inline=True)

part2 = Mixed()
part2 &= TextBody("Now look at this dog.\n")
part2 &= BytesAttachment.from_file("rags.jpeg", inline=True)
part2 &= TextBody("Which one is cuter?\n")

mixed = part1 & part2

assert mixed.contents == [
    TextBody("Look at the pretty kitty!\n"),
    BytesAttachment.from_file("snuffles.jpeg", inline=True),
    TextBody("Now look at this dog.\n"),
    BytesAttachment.from_file("rags.jpeg", inline=True),
    TextBody("Which one is cuter?\n"),
]

Changed in version 0.4.0: Using & to combine a MailItem with a str now automatically converts the str to a TextBody

content: list[MailItem]

The MailItems contained within the instance

content_id: str | None

Added in version 0.3.0.

Content-ID header value for the item

class eletter.Related(content: Iterable[MailItem] = NOTHING, start: str | None = None, *, content_id: str | None = None)

Added in version 0.3.0.

A multipart/related e-mail payload. E-mail clients will display the part indicated by the start parameter, or the first part if start is not set. This part may refer to other parts (e.g., images or CSS stylesheets) by their Content-ID headers, which can be generated using email.utils.make_msgid.

Note

Content-ID headers begin & end with angle brackets (<...>), which need to be stripped off before including the ID in the starting part.

A Related instance can be created by combining two or more MailItems with the ^ operator:

from email.utils import make_msgid

img_cid = make_msgid()

html = HTMLBody(
    "<p>Look at the pretty kitty!</p>"
    f'<img src="cid:{img_cid[1:-1]}"/>"
    "<p>Isn't he <em>darling</em>?</p>"
)

image = BytesAttachment.from_file("snuffles.jpeg", content_id=img_cid)

related = html ^ image

Likewise, additional MailItems can be added to a Related instance with the ^= operator:

# Same as above:

img_cid = make_msgid()

related = Related()

related ^= HTMLBody(
    "<p>Look at the pretty kitty!</p>"
    f'<img src="cid:{img_cid[1:-1]}"/>"
    "<p>Isn't he <em>darling</em>?</p>"
)

related ^= BytesAttachment.from_file("snuffles.jpeg", content_id=img_cid)

Using ^ to combine a MailItem with a str automatically converts the str to a TextBody, though this is generally not all that useful, as you’ll usually want to create Related instances from HTMLBodys instead.

When combining two Related instances with ^ or ^=, the contents are “flattened”:

# Same as above:

img_cid = make_msgid()

htmlrel = Related([
    HTMLBody(
        "<p>Look at the pretty kitty!</p>"
        f'<img src="cid:{img_cid[1:-1]}"/>"
        "<p>Isn't he <em>darling</em>?</p>"
    )
])

imgrel = Related([
    BytesAttachment.from_file("snuffles.jpeg", content_id=img_cid)
])

related = htmlrel ^ imgrel

assert related.contents == [
    HTMLBody(
        "<p>Look at the pretty kitty!</p>"
        f'<img src="cid:{img_cid[1:-1]}"/>"
        "<p>Isn't he <em>darling</em>?</p>"
    ),
    BytesAttachment.from_file("snuffles.jpeg", content_id=img_cid),
]

Changed in version 0.4.0: Using ^ to combine a MailItem with a str now automatically converts the str to a TextBody

content: list[MailItem]

The MailItems contained within the instance

content_id: str | None

Added in version 0.3.0.

Content-ID header value for the item

get_root() → MailItem

Added in version 0.5.0.

Retrieves the root part, i.e., the part whose content_id equals start, or the first part if start is not set.

Raises:

ValueError – if the instance is empty or no part has a content_id equaling start

start: str | None

The Content-ID of the part to display (defaults to the first part)

Decomposition

eletter.decompose(msg: EmailMessage) → Eletter

Added in version 0.5.0.

Decompose an EmailMessage into an Eletter instance containing a MailItem and a collection of headers. Only structures that can be represented by eletter classes are supported.

All message parts that are not text/plain, text/html, multipart/*, or message/* are treated as attachments. Attachments without filenames or an explicit “attachment” Content-Disposition are treated as inline.

Any information specific to how the message is encoded is discarded (namely, “charset” parameters on text/* parts, Content-Transfer-Encoding headers, and MIME-Version headers).

Headers on message sub-parts that do not have representations on MailItems are discarded (namely, everything other than Content-Type, Content-Disposition, and Content-ID).

Raises:

• TypeError – if any sub-part of msg is not an EmailMessage instance

• DecompositionError – if msg contains a part with an unrepresentable Content-Type

eletter.decompose_simple(msg: EmailMessage, unmix: bool = False) → SimpleEletter

Added in version 0.5.0.

Decompose an EmailMessage into a SimpleEletter instance consisting of a text body and/or HTML body, some number of attachments, and a collection of headers. The EmailMessage is first decomposed with decompose() and then simplified by calling Eletter.simplify().

By default, a multipart/mixed message can only be simplified if all of the attachments come after all of the message bodies; set unmix to True to separate the attachments from the bodies regardless of what order they come in.

Raises:

• TypeError – if any sub-part of msg is not an EmailMessage instance

• DecompositionError – if msg contains a part with an unrepresentable Content-Type

• SimplificationError – if msg cannot be simplified

class eletter.Eletter

Added in version 0.5.0.

A decomposed e-mail message

content: MailItem

The message’s body

subject: str | None

The message’s subject line, if any

from_: list[Address | Group]

The message’s From addresses

to: list[Address | Group]

The message’s To addresses

cc: list[Address | Group]

The message’s CC addresses

bcc: list[Address | Group]

The message’s BCC addresses

reply_to: list[Address | Group]

The message’s Reply-To addresses

sender: Address | None

The message’s Sender address, if any

date: datetime | None

The message’s Date header, if set

headers: dict[str, list[str]]

Any additional headers on the message. The header names are lowercase.

compose() → EmailMessage

Convert the Eletter back into an EmailMessage

simplify(unmix: bool = False) → SimpleEletter

Simplify the Eletter into a SimpleEletter, breaking down Eletter.content into a text body, HTML body, and a list of attachments.

By default, a multipart/mixed message can only be simplified if all of the attachments come after all of the message bodies; set unmix to True to separate the attachments from the bodies regardless of what order they come in.

Raises:

SimplificationError – if msg cannot be simplified

class eletter.SimpleEletter

Added in version 0.5.0.

A decomposed simple e-mail message, consisting of a text body and/or HTML body plus some number of attachments and headers

text: str | None

The message’s text body, if any

html: str | None

The message’s HTML body, if any

attachments: list[Attachment]

Attachments on the message

subject: str | None

The message’s subject line, if any

from_: list[Address | Group]

The message’s From addresses

to: list[Address | Group]

The message’s To addresses

cc: list[Address | Group]

The message’s CC addresses

bcc: list[Address | Group]

The message’s BCC addresses

reply_to: list[Address | Group]

The message’s Reply-To addresses

sender: Address | None

The message’s Sender address, if any

date: datetime | None

The message’s Date header, if set

headers: dict[str, list[str]]

Any additional headers on the message. The header names are lowercase.

compose() → EmailMessage

Convert the SimpleEletter back into an EmailMessage

Exceptions

exception eletter.Error

Bases: Exception

Added in version 0.5.0.

The superclass of all custom exceptions raised by eletter

exception eletter.DecompositionError

Bases: Error, ValueError

Added in version 0.5.0.

Raised when eletter is asked to decompose an EmailMessage with an unrepresentable Content-Type

exception eletter.SimplificationError

Bases: Error, ValueError

Added in version 0.5.0.

Raised when eletter is asked to simplify a message that cannot be simplified

exception eletter.MixedContentError

Bases: SimplificationError

Added in version 0.5.0.

Subclass of SimplificationError raised when a multipart/mixed is encountered in which one or more attachments precede a message body part; such messages can be forced to be simplified by setting the unmix argument of simplify() or decompose_simple() to True.

Utility Functions

eletter.assemble_content_type(maintype: str, subtype: str, **params: str) → str

Added in version 0.2.0.

Construct a Content-Type string from a maintype, subtype, and some number of parameters

Raises:

ValueError – if f"{maintype}/{subtype}" is an invalid Content-Type

eletter.format_addresses(addresses: Iterable[str | Address | Group], encode: bool = False) → str

Convert an iterable of e-mail address strings (of the form “foo@example.com”, without angle brackets or a display name), Address objects, and/or Group objects into a formatted string. If encode is False (the default), non-ASCII characters are left as-is. If it is True, non-ASCII display names are converted into RFC 2047 encoded words, and non-ASCII domain names are encoded using Punycode.

eletter.reply_quote(s: str, prefix: str = '> ') → str

Added in version 0.2.0.

Quote a text following the de facto standard for replying to an e-mail; that is, prefix each line of the text with "> " (or a custom prefix), and if a line already starts with the prefix, omit any trailing whitespace from the newly-added prefix (so "> already quoted" becomes ">> already quoted").

If the resulting string does not end with a newline, one is added. The empty string is treated as a single line.