API Reference

ADR-NNNN in a docstring names a file in docs/adr/, the decision records in the repo.

Backends

A backend holds the credential and the from address, and it sends or opens a connection.

SMTPBackend: An SMTP backend submits each message to an SMTP server through smtplib.
GmailBackend: A Gmail backend sends each message through the Gmail API’s messages.send, as the RFC 5322 message SMTP would write.
GraphBackend: A Graph backend sends each message through Microsoft Graph, as JSON.
ConsoleBackend: A console backend writes a rendering of each submission to a stream instead of sending it.
MemoryBackend: A memory backend records each submission instead of sending it.

Each backend module exports its credentials.

smtp.Password: A password is the username and password SMTPBackend authenticates with, through PLAIN, LOGIN or CRAM-MD5.
smtp.OAuth: An OAuth credential authenticates to SMTP with an access token instead of a password, through XOAUTH2.
gmail.ServiceAccount: A service account sends as subject through domain-wide delegation.
gmail.AuthorizedUser: An authorized user is a saved user consent.
graph.ClientSecret: A client secret authenticates an Entra app registration, which needs the Mail.Send application permission.
graph.Certificate: A certificate authenticates an Entra app registration with a certificate instead of a secret.
graph.ManagedIdentity: A managed identity is the identity Azure gives the resource the code runs on, so the caller stores no secret.

A message is an immutable value, and each builder method returns a copy.

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

What a send takes and returns.

Address: An Address is a str that holds one address in its display-name form.
Attachment: An attachment is bytes with a filename and a content type that a message carries.
Refusal: A refusal records one recipient a mail service refused.
SendResult: A send result records that a mail service accepted one submission.
Submission: A submission is one message passed to one transport once.

What a third-party backend implements.

Backend: A backend holds the configuration for sending through one mail service.
Connection: A connection is one live link a backend opened, for many sends until it closes for good.
Transport: A transport is the object a backend opens, and the only code that communicates with a mail service.
TokenCredential: A token credential returns an access token on demand, in the shape azure.core.credentials defines.
AccessToken: An access token is the value TokenCredential.get_token returns.

Every error Epistole raises for a failed send subclasses EpistoleError.

exceptions.EpistoleError: An EpistoleError reports an error reply from a mail service, or a network failure.
exceptions.RejectedError: The service rejected the message as invalid, or the message failed a backend pre-check.
exceptions.SenderRefusedError: The service refused to send as the backend’s from address.
exceptions.RecipientsRefusedError: The service refused every recipient, so nothing was submitted.
exceptions.AuthenticationError: The service rejected the credential, or the credential lacks a permission.
exceptions.ThrottledError: The service throttled the request.
exceptions.TransportError: The link to the service failed at connect, in TLS, by disconnect or by timeout.
exceptions.ProviderError: The service returned its own 5xx, or a reply that no mapping table matches.