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

Install it from PyPI, or browse its source on GitHub:

[lettr-python
on GitHub (opens in a new tab)](https://github.com/lettr-com/lettr-python)

`pip install lettr`

Using an AI coding agent? Give it this prompt to get started:

```text wrap expandable theme={null}
Set up email sending with Lettr in this Python project, using the official `lettr` SDK.

Read this guide first: https://docs.lettr.com/quickstart/python/quickstart.md

1. Check how this project sends email today. If it already uses a provider, migrate that code to Lettr. If it doesn't send email yet, add one small, working example.
2. Install the SDK with `pip install lettr`.
3. Read the API key from the `LETTR_API_KEY` environment variable. Never hard-code it or commit it.
4. Send from an address on a domain that is verified in Lettr.
5. When you're done, summarize what you changed and tell me how to send a test email.
```

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

> [!NOTE]
>
> If you prefer not to use the SDK, you can also send emails via [SMTP](https://docs.lettr.com/quickstart/smtp/introduction.md) or make direct [HTTP API](https://docs.lettr.com/api-reference/emails/send-email.md) calls.

## Prerequisites

Before you begin, make sure you have:

> [card] [API Key](https://app.lettr.com/api-keys)
>
> Create an API key in the Lettr dashboard

> [card] [Verified Domain](https://docs.lettr.com/learn/domains/sending-domains.md)
>
> 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.

**1. Install the SDK**

```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.

**2. Create a client**

```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})")
```

> [!TIP]
>
> Store your API key in environment variables, never hardcode it. API keys use the `lttr_` prefix followed by 64 hexadecimal characters.

**3. Send your first email**

```python theme={null}
response = client.emails.send(
    from_email="sender@yourdomain.com",
    to=["recipient@example.com"],
    subject="Hello from Lettr",
    html="<h1>Hello!</h1><p>This is a test email.</p>",
)

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.

> [!WARNING]
>
> 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"])
```

> [!TIP]
>
> Add `.env` to your `.gitignore` file to prevent accidentally committing your API key to version control.

### Timeouts and base URL

The client takes keyword-only `timeout` (seconds, default 30) and `base_url` arguments:

```python theme={null}
import lettr

client = lettr.Lettr("your-api-key", timeout=10.0)
```

It is also a context manager, which closes the underlying connection pool on exit:

```python theme={null}
with lettr.Lettr("your-api-key") as client:
    client.emails.send(...)
```

### Calling the client from async code

The SDK is **synchronous**. To use it from an async application without blocking the
event loop, run the call in a worker thread with `asyncio.to_thread`:

```python theme={null}
import asyncio
import lettr

client = lettr.Lettr("your-api-key")

async def main():
    response = await asyncio.to_thread(
        client.emails.send,
        from_email="sender@yourdomain.com",
        to=["recipient@example.com"],
        subject="Hello",
        html="<p>Hello!</p>",
    )

    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="<h1>Welcome!</h1><p>Thanks for signing up.</p>",
)

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="<h1>Hello!</h1>",
)
```

### 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="<h1>Hello!</h1><p>This is the HTML version.</p>",
    text="Hello!\n\nThis is the plain text version.",
)
```

> [!TIP]
>
> 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:

> [card] [Templates](https://docs.lettr.com/quickstart/python/templates.md)
>
> Manage Lettr templates and merge tags

> [card] [Domains](https://docs.lettr.com/quickstart/python/domains.md)
>
> Add, verify, and manage sending domains

> [card] [Webhooks](https://docs.lettr.com/quickstart/python/webhooks.md)
>
> Manage webhook endpoints for delivery and engagement events

> [card] [Audience](https://docs.lettr.com/quickstart/python/audience.md)
>
> Lists, contacts, topics, properties, and segments

> [card] [Campaigns](https://docs.lettr.com/quickstart/python/campaigns.md)
>
> List, send, and schedule campaigns

## What's Next

> [card] [Advanced Features](https://docs.lettr.com/quickstart/python/advanced.md)
>
> Multiple recipients, attachments, templates, error handling, and more

> [card] [Flask Integration](https://docs.lettr.com/quickstart/python/send-with-flask.md)
>
> Use Lettr with Flask applications

> [card] [FastAPI Integration](https://docs.lettr.com/quickstart/python/send-with-fastapi.md)
>
> Use Lettr with FastAPI applications

> [card] [API Reference](https://docs.lettr.com/api-reference/introduction.md)
>
> Complete API documentation


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.