---
name: epistole
description: >
  Epistole is a single Python API for sending email, regardless of the backend. Use when writing Python code that uses the epistole package.
license: MIT
compatibility: Requires Python >=3.13.
---

# Epistole

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

## Installation

```bash
pip install epistole
```

## API overview

### 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

### Credentials

Each backend module exports its credentials.

- `smtp.Password`
- `smtp.OAuth`
- `gmail.ServiceAccount`
- `gmail.AuthorizedUser`
- `graph.ClientSecret`
- `graph.Certificate`
- `graph.ManagedIdentity`

### Message

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

### Values

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

### Base classes and protocols

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

### Exceptions

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

- `exceptions.EpistoleError`
- `exceptions.RejectedError`
- `exceptions.SenderRefusedError`
- `exceptions.RecipientsRefusedError`
- `exceptions.AuthenticationError`
- `exceptions.ThrottledError`
- `exceptions.TransportError`
- `exceptions.ProviderError`

### Functions

- `html_to_text`: Derive plain text from `html`

## Resources

- [Full documentation](https://ozanozbeker.com/epistole/)
- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs
- [Source code](https://github.com/ozanozbeker/epistole)