# API Reference


`ADR-NNNN` in a docstring names a file in [`docs/adr/`](https://github.com/ozanozbeker/epistole/tree/main/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](SMTPBackend.md#epistole.SMTPBackend)  
An SMTP backend submits each message to an SMTP server through `smtplib`.

[GmailBackend](GmailBackend.md#epistole.GmailBackend)  
A Gmail backend sends each message through the Gmail API's `messages.send`, as the RFC 5322 message SMTP would write.

[GraphBackend](GraphBackend.md#epistole.GraphBackend)  
A Graph backend sends each message through Microsoft Graph, as JSON.

[ConsoleBackend](ConsoleBackend.md#epistole.ConsoleBackend)  
A console backend writes a rendering of each submission to a stream instead of sending it.

[MemoryBackend](MemoryBackend.md#epistole.MemoryBackend)  
A memory backend records each submission instead of sending it.


## Credentials


Each backend module exports its credentials.


[smtp.Password](smtp.Password.md#epistole.smtp.Password)  
A password is the username and password `SMTPBackend` authenticates with, through PLAIN, LOGIN or CRAM-MD5.

[smtp.OAuth](smtp.OAuth.md#epistole.smtp.OAuth)  
An OAuth credential authenticates to SMTP with an access token instead of a password, through XOAUTH2.

[gmail.ServiceAccount](gmail.ServiceAccount.md#epistole.gmail.ServiceAccount)  
A service account sends as `subject` through domain-wide delegation.

[gmail.AuthorizedUser](gmail.AuthorizedUser.md#epistole.gmail.AuthorizedUser)  
An authorized user is a saved user consent.

[graph.ClientSecret](graph.ClientSecret.md#epistole.graph.ClientSecret)  
A client secret authenticates an Entra app registration, which needs the `Mail.Send` application permission.

[graph.Certificate](graph.Certificate.md#epistole.graph.Certificate)  
A certificate authenticates an Entra app registration with a certificate instead of a secret.

[graph.ManagedIdentity](graph.ManagedIdentity.md#epistole.graph.ManagedIdentity)  
A managed identity is the identity Azure gives the resource the code runs on, so the caller stores no secret.


## Message


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


[Message](Message.md#epistole.Message)  
A message holds the content, addressing, subject, custom headers, and attachments a caller builds, as one frozen value.


## Values


What a send takes and returns.


[Address](Address.md#epistole.Address)  
An `Address` is a `str` that holds one address in its display-name form.

[Attachment](Attachment.md#epistole.Attachment)  
An attachment is bytes with a filename and a content type that a message carries.

[Refusal](Refusal.md#epistole.Refusal)  
A refusal records one recipient a mail service refused.

[SendResult](SendResult.md#epistole.SendResult)  
A send result records that a mail service accepted one submission.

[Submission](Submission.md#epistole.Submission)  
A submission is one message passed to one transport once.


## Base classes and protocols


What a third-party backend implements.


[Backend](Backend.md#epistole.Backend)  
A backend holds the configuration for sending through one mail service.

[Connection](Connection.md#epistole.Connection)  
A connection is one live link a backend opened, for many sends until it closes for good.

[Transport](Transport.md#epistole.Transport)  
A transport is the object a backend opens, and the only code that communicates with a mail service.

[TokenCredential](TokenCredential.md#epistole.TokenCredential)  
A token credential returns an access token on demand, in the shape `azure.core.credentials` defines.

[AccessToken](AccessToken.md#epistole.AccessToken)  
An access token is the value `TokenCredential.get_token` returns.


## Exceptions


Every error Epistole raises for a failed send subclasses `EpistoleError`.


[exceptions.EpistoleError](exceptions.EpistoleError.md#epistole.exceptions.EpistoleError)  
An `EpistoleError` reports an error reply from a mail service, or a network failure.

[exceptions.RejectedError](exceptions.RejectedError.md#epistole.exceptions.RejectedError)  
The service rejected the message as invalid, or the message failed a backend pre-check.

[exceptions.SenderRefusedError](exceptions.SenderRefusedError.md#epistole.exceptions.SenderRefusedError)  
The service refused to send as the backend's from address.

[exceptions.RecipientsRefusedError](exceptions.RecipientsRefusedError.md#epistole.exceptions.RecipientsRefusedError)  
The service refused every recipient, so nothing was submitted.

[exceptions.AuthenticationError](exceptions.AuthenticationError.md#epistole.exceptions.AuthenticationError)  
The service rejected the credential, or the credential lacks a permission.

[exceptions.ThrottledError](exceptions.ThrottledError.md#epistole.exceptions.ThrottledError)  
The service throttled the request.

[exceptions.TransportError](exceptions.TransportError.md#epistole.exceptions.TransportError)  
The link to the service failed at connect, in TLS, by disconnect or by timeout.

[exceptions.ProviderError](exceptions.ProviderError.md#epistole.exceptions.ProviderError)  
The service returned its own `5xx`, or a reply that no mapping table matches.


## Functions


[html_to_text()](html_to_text.md#epistole.html_to_text)  
Derive plain text from `html`.