Message

A message holds the content, addressing, subject, custom headers, and attachments a caller builds, as one frozen value.

Usage

Source

Message(
    *,
    html=None,
    markdown=None,
    text=None,
    text_renderer=None,
)

It compares and hashes by content. Every builder method returns a new message and leaves the receiver unchanged.

A method named for a field replaces that field, so .to("a").to("b") addresses b alone. .attach() and .embed() append instead. Nothing removes a field, so each address method takes at least one address. See ADR-0002.

A builder method’s value is an attribute with the method’s name plus a trailing underscore, because the plain name is the method. See ADR-0007.

Parameters

html: str | None = None

The HTML. Epistole moves each data: image in an <img src> into an inline image and rewrites the src to cid:. It then derives the plain text from the result with html_to_text, unless the caller supplies text or text_renderer. See ADR-0003.

markdown: str | None = None

The Markdown source. Epistole renders the HTML from it on markdown-it-py’s commonmark preset and sends the source as the plain text, unless the caller supplies text.

text: str | None = None

The plain text. Epistole sends it verbatim and derives nothing from html. It may be "" when the subject holds the whole message.

text_renderer: Callable[[str], str] | None = None
Derives the plain text from the rewritten html in place of html_to_text. It runs once, at construction. The message does not keep it, so equality compares content alone. An exception it raises propagates unchanged.

Attributes

to_, cc_, bcc_, reply_to_

The addresses the builder method of the same name set.

subject_: str | None

The subject .subject() set, or None.

headers_: Mapping[str, str]

The custom headers .headers() set, as a read-only mapping in the caller’s order. It is empty until .headers() sets it, and it never holds a header Epistole writes.

html: str | None

The HTML the caller supplied or Epistole rendered from markdown, or None on a text-only message. The rewrite has replaced each data: image in it with a cid: reference.

text: str

The plain text. It is the Markdown source for markdown=. It is "" for text="", and also for HTML that holds no text, such as a lone image with no alt text.

attachments: tuple[Attachment, …]

What .attach() added, in call order.

inline_images: tuple[Attachment, …]
The inline images the data: rewrite made come first, one per distinct media type and bytes. What .embed() added follows, in call order.

Raises

TypeError

When both html and markdown are supplied, when no content is supplied, or when text_renderer accompanies text or markdown. When html, markdown, or text is not a str, or when text_renderer returns something other than a str.

ValueError

When html, markdown, or text holds a surrogate, or when text_renderer returns text that holds one. When the payload of a data: image does not decode. See ADR-0003 and ADR-0008.

ImportError
When markdown is supplied and epistole[markdown] is not installed.

Methods

Name Description
to() Return a copy with the to addresses set, replacing any earlier .to().
cc() Return a copy with the cc addresses set, replacing any earlier .cc().
bcc() Return a copy with the bcc addresses set, replacing any earlier .bcc().
reply_to() Return a copy with the reply-to addresses set, replacing any earlier .reply_to().
subject() Return a copy with the subject set, replacing any earlier subject.
headers() Return a copy with the custom headers set, replacing any earlier .headers().
attach() Return a copy with source appended as an attachment.
embed() Return a copy with source appended as an inline image, which the HTML names as cid: plus its content id.

to()

Return a copy with the to addresses set, replacing any earlier .to().

Usage

Source

to(address, /, *more)

cc()

Return a copy with the cc addresses set, replacing any earlier .cc().

Usage

Source

cc(address, /, *more)

bcc()

Return a copy with the bcc addresses set, replacing any earlier .bcc().

Usage

Source

bcc(address, /, *more)

reply_to()

Return a copy with the reply-to addresses set, replacing any earlier .reply_to().

Usage

Source

reply_to(address, /, *more)

subject()

Return a copy with the subject set, replacing any earlier subject.

Usage

Source

subject(subject)
Raises
TypeError

When subject is not a str.

ValueError
When subject holds a line break or a surrogate. See ADR-0016.

headers()

Return a copy with the custom headers set, replacing any earlier .headers().

Usage

Source

headers(mapping)

It copies mapping at the call and keeps its order. See ADR-0016.

Raises
TypeError

When a name or a value is not a str.

ValueError
When mapping is empty, or when two names differ only in case. When a name holds a space, a colon, or a character outside printable ASCII. When a name is Resent-Bcc or a name Epistole writes. When a value holds a line break or a surrogate.

attach()

Return a copy with source appended as an attachment.

Usage

Source

attach(source, /, *, filename=None, content_type=None)
Parameters
source: Path | bytes | BinaryIO

The bytes, or a Path or binary file object to read them from. Epistole reads it at call time. A Path supplies its own filename. A file object is read from its current position and left open.

filename: str | None = None

The name the recipient sees. Bytes and a file object need one, because Epistole never reads a file object’s .name.

content_type: str | None = None
A bare media type such as application/pdf. It defaults to the type filename implies. It falls back to application/octet-stream when the filename implies no type, a compressed file, or a message/* or multipart/* type. Epistole never inspects the bytes.
Raises
TypeError

When source is a str, a bytearray, a memoryview, or a text-mode file, or when the caller passes a source other than a Path without filename. When filename or content_type is not a str. See ADR-0018.

ValueError
When the filename holds a line break or a surrogate, or when content_type is not a bare type/subtype, such as one with parameters or a name over 127 characters. When content_type is a message/* or multipart/* type. See ADR-0018.

embed()

Return a copy with source appended as an inline image, which the HTML names as cid: plus its content id.

Usage

Source

embed(source, /, *, filename=None, cid=None, content_type=None)
Parameters
source: Path | bytes | BinaryIO

The image, read now, as for .attach().

filename: str | None = None

The name the recipient sees. It defaults to a Path source’s own name, or else to cid.

cid: str | None = None

The content id. It defaults to filename, so .embed(Path("logo.png")) matches <img src="cid:logo.png">.

content_type: str | None = None
As for .attach(), and it must be image/*.
Raises
TypeError

As for .attach(), or when the caller passes a source other than a Path with neither filename nor cid. When cid is not a str.

ValueError
When the filename or the content id holds a line break, when the content id is not ASCII, when the content type is not image/*, or when the message already holds an inline image under the same content id, including one the data: rewrite made. When the filename or the content id holds a surrogate. See ADR-0018.