Skills

A skill is a package of structured files that teaches an AI coding agent how to work with a specific tool or framework. The skill below was generated by Great Docs from this project’s documentation. Install it in your agent and it will be able to run commands, edit configuration, write content, and troubleshoot problems without step-by-step guidance from you.

Any agent — install with npx:

npx skills add https://ozanozbeker.com/epistole/

Codex / OpenCode

Tell the agent:
Fetch the skill file at https://ozanozbeker.com/epistole/skill.md and follow the instructions.

Manual — download the skill file:

curl -O https://ozanozbeker.com/epistole/skill.md

Or browse the SKILL.md file.

SKILL.md

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