> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lettr.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting Started
> Send transactional emails from Python with the type-safe lettr SDK, featuring sync and async clients, type hints, and typed error handling.
Send transactional emails from your Python applications using the official Lettr Python SDK. The SDK provides a type-safe, intuitive interface for the Lettr API with full async support and comprehensive error handling.
The `lettr` package gives you a Pythonic API client that works with any Python application — Django, Flask, FastAPI, or standalone scripts. It follows Python conventions and integrates seamlessly with your existing codebase.
Using Cursor? [Jump straight in using this prompt](https://cursor.com/link/prompt?text=Help%20me%20add%20a%20Lettr%20sending%20example%20for%20Python%20using%20the%20lettr%20package%2C%20or%20migrate%20my%20current%20Python%20sending%20solution%20to%20Lettr%20using%20these%20docs%3A%20https%3A%2F%2Fdocs.lettr.com%2Fquickstart%2Fpython%2Fquickstart)
## Why Use the Python SDK?
Rather than making raw HTTP requests, the SDK provides:
* **Type hints** — Full type annotations for IDE autocompletion and type checking
* **Sync and async** — Both synchronous and asynchronous API clients
* **Pythonic interface** — Snake\_case naming and Python conventions
* **Error handling** — Typed exceptions for different error scenarios
* **Minimal dependencies** — Only requires `httpx` for HTTP requests
If you prefer not to use the SDK, you can also send emails via [SMTP](/quickstart/smtp/introduction) or make direct [HTTP API](/api-reference/emails/send-email) calls.
## Prerequisites
Before you begin, make sure you have:
Create an API key in the Lettr dashboard
Add and verify your sending domain
You'll also need:
* **Python 3.8 or later** installed
* **pip** for package management
* A verified sending domain in your [Lettr dashboard](https://app.lettr.com/domains)
## Quick Setup
Get started in three quick steps: install, configure, and send.
```bash theme={null}
pip install lettr
```
The SDK requires Python 3.8+ and automatically installs `httpx` as a dependency. For async support, httpx's async features are included by default.
```python theme={null}
import lettr
client = lettr.Lettr("your-api-key")
# Verify the client is configured correctly
auth = client.auth_check()
print(f"Connected to Lettr (Team ID: {auth.team_id})")
```
Store your API key in environment variables, never hardcode it. API keys use the `lttr_` prefix followed by 64 hexadecimal characters.
```python theme={null}
response = client.emails.send(
from_email="sender@yourdomain.com",
to=["recipient@example.com"],
subject="Hello from Lettr",
html="Hello!
This is a test email.
",
)
print(f"Email sent! Request ID: {response.request_id}")
print(f"Accepted: {response.accepted}")
```
The response includes a `request_id` for tracking and the number of accepted recipients.
The sender domain must be verified in your [Lettr dashboard](https://app.lettr.com/domains) before you can send emails. Sending from an unverified domain returns a validation error.
## Configuration
### Environment Variables
Read your API key from an environment variable:
```python theme={null}
import os
import lettr
api_key = os.environ.get("LETTR_API_KEY")
if not api_key:
raise ValueError("LETTR_API_KEY environment variable is required")
client = lettr.Lettr(api_key)
```
### Using python-dotenv
Load environment variables from a `.env` file using `python-dotenv`:
```bash theme={null}
pip install python-dotenv
```
Create a `.env` file:
```env theme={null}
LETTR_API_KEY=lttr_your_api_key_here
```
Load it in your application:
```python theme={null}
from dotenv import load_dotenv
import os
import lettr
# Load .env file
load_dotenv()
client = lettr.Lettr(os.environ["LETTR_API_KEY"])
```
Add `.env` to your `.gitignore` file to prevent accidentally committing your API key to version control.
### Custom HTTP Client
Use a custom httpx client with custom timeouts:
```python theme={null}
import httpx
import lettr
http_client = httpx.Client(timeout=30.0)
client = lettr.Lettr("your-api-key", http_client=http_client)
```
### Async Client
Use the async client for non-blocking operations:
```python theme={null}
import asyncio
import lettr
async def main():
client = lettr.AsyncLettr("your-api-key")
response = await client.emails.send(
from_email="sender@yourdomain.com",
to=["recipient@example.com"],
subject="Hello",
html="Hello!
",
)
print(f"Email sent: {response.request_id}")
asyncio.run(main())
```
## Sending Emails
### Basic HTML Email
Send a simple HTML email:
```python theme={null}
response = client.emails.send(
from_email="notifications@yourdomain.com",
to=["user@example.com"],
subject="Welcome to our service",
html="Welcome!
Thanks for signing up.
",
)
print(f"Email sent successfully (Request ID: {response.request_id})")
```
### With Display Name
Add a friendly display name to the sender address:
```python theme={null}
response = client.emails.send(
from_email="notifications@yourdomain.com",
from_name="Acme Corp",
to=["user@example.com"],
subject="Welcome to Acme",
html="Hello!
",
)
```
### Plain Text Email
Send a plain text email without HTML:
```python theme={null}
response = client.emails.send(
from_email="notifications@yourdomain.com",
to=["user@example.com"],
subject="Plain text email",
text="This is a plain text email.\n\nIt has no HTML formatting.",
)
```
### Multipart Emails (HTML + Text)
Send both HTML and plain text versions for maximum compatibility:
```python theme={null}
response = client.emails.send(
from_email="notifications@yourdomain.com",
to=["user@example.com"],
subject="Multipart email",
html="Hello!
This is the HTML version.
",
text="Hello!\n\nThis is the plain text version.",
)
```
Providing both HTML and plain text ensures your emails are readable in all email clients, including text-only clients and accessibility tools.
## Explore the SDK
Beyond sending, the SDK manages every Lettr resource:
Manage Lettr templates and merge tags
Add, verify, and manage sending domains
Manage webhook endpoints for delivery and engagement events
Lists, contacts, topics, properties, and segments
List, send, and schedule campaigns
## What's Next
Multiple recipients, attachments, templates, error handling, and more
Use Lettr with Flask applications
Use Lettr with FastAPI applications
Complete API documentation