# epistole

> Epistole is a single Python API for sending email, regardless of the backend.

## Docs

### API Reference

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

- [SMTPBackend](https://ozanozbeker.com/epistole/reference/SMTPBackend.html): An SMTP backend submits each message to an SMTP server through `smtplib`
- [GmailBackend](https://ozanozbeker.com/epistole/reference/GmailBackend.html): A Gmail backend sends each message through the Gmail API's `messages.send`, as the RFC 5322 message SMTP would write
- [GraphBackend](https://ozanozbeker.com/epistole/reference/GraphBackend.html): A Graph backend sends each message through Microsoft Graph, as JSON
- [ConsoleBackend](https://ozanozbeker.com/epistole/reference/ConsoleBackend.html): A console backend writes a rendering of each submission to a stream instead of sending it
- [MemoryBackend](https://ozanozbeker.com/epistole/reference/MemoryBackend.html): A memory backend records each submission instead of sending it

#### Credentials
> Each backend module exports its credentials.

- [smtp.Password](https://ozanozbeker.com/epistole/reference/smtp.Password.html)
- [smtp.OAuth](https://ozanozbeker.com/epistole/reference/smtp.OAuth.html)
- [gmail.ServiceAccount](https://ozanozbeker.com/epistole/reference/gmail.ServiceAccount.html)
- [gmail.AuthorizedUser](https://ozanozbeker.com/epistole/reference/gmail.AuthorizedUser.html)
- [graph.ClientSecret](https://ozanozbeker.com/epistole/reference/graph.ClientSecret.html)
- [graph.Certificate](https://ozanozbeker.com/epistole/reference/graph.Certificate.html)
- [graph.ManagedIdentity](https://ozanozbeker.com/epistole/reference/graph.ManagedIdentity.html)

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

- [Message](https://ozanozbeker.com/epistole/reference/Message.html): 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](https://ozanozbeker.com/epistole/reference/Address.html): An `Address` is a `str` that holds one address in its display-name form
- [Attachment](https://ozanozbeker.com/epistole/reference/Attachment.html): An attachment is bytes with a filename and a content type that a message carries
- [Refusal](https://ozanozbeker.com/epistole/reference/Refusal.html): A refusal records one recipient a mail service refused
- [SendResult](https://ozanozbeker.com/epistole/reference/SendResult.html): A send result records that a mail service accepted one submission
- [Submission](https://ozanozbeker.com/epistole/reference/Submission.html): A submission is one message passed to one transport once

#### Base classes and protocols
> What a third-party backend implements.

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

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

- [exceptions.EpistoleError](https://ozanozbeker.com/epistole/reference/exceptions.EpistoleError.html)
- [exceptions.RejectedError](https://ozanozbeker.com/epistole/reference/exceptions.RejectedError.html)
- [exceptions.SenderRefusedError](https://ozanozbeker.com/epistole/reference/exceptions.SenderRefusedError.html)
- [exceptions.RecipientsRefusedError](https://ozanozbeker.com/epistole/reference/exceptions.RecipientsRefusedError.html)
- [exceptions.AuthenticationError](https://ozanozbeker.com/epistole/reference/exceptions.AuthenticationError.html)
- [exceptions.ThrottledError](https://ozanozbeker.com/epistole/reference/exceptions.ThrottledError.html)
- [exceptions.TransportError](https://ozanozbeker.com/epistole/reference/exceptions.TransportError.html)
- [exceptions.ProviderError](https://ozanozbeker.com/epistole/reference/exceptions.ProviderError.html)

#### Functions

- [html_to_text](https://ozanozbeker.com/epistole/reference/html_to_text.html): Derive plain text from `html`