Getting Started

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

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 or make direct HTTP API calls.

Prerequisites

Before you begin, make sure you have:

API Key

Create an API key in the Lettr dashboard

Verified Domain

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

Quick Setup

Get started in three quick steps: install, configure, and send.

Install the SDK

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.

Create a client

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.

Send your first email

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.

The sender domain must be verified in your Lettr dashboard 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:

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:

pip install python-dotenv

Create a .env file:

LETTR_API_KEY=lttr_your_api_key_here

Load it in your application:

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:

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:

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

    print(f"Email sent: {response.request_id}")

asyncio.run(main())

Sending Emails

Basic HTML Email

Send a simple HTML email:

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:

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:

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:

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.",
)

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:

Templates

Manage Lettr templates and merge tags

Domains

Add, verify, and manage sending domains

Webhooks

Manage webhook endpoints for delivery and engagement events

Audience

Lists, contacts, topics, properties, and segments

Campaigns

List, send, and schedule campaigns

What’s Next

Advanced Features

Multiple recipients, attachments, templates, error handling, and more

Flask Integration

Use Lettr with Flask applications

FastAPI Integration

Use Lettr with FastAPI applications

API Reference

Complete API documentation

​Why Use the Python SDK?

​Prerequisites

API Key

Verified Domain

​Quick Setup

​Configuration

​Environment Variables

​Using python-dotenv

​Custom HTTP Client

​Async Client

​Sending Emails

​Basic HTML Email

​With Display Name

​Plain Text Email

​Multipart Emails (HTML + Text)

​Explore the SDK

Templates

Domains

Webhooks

Audience

Campaigns

​What’s Next

Advanced Features

Flask Integration

FastAPI Integration

API Reference

Why Use the Python SDK?

Prerequisites

Quick Setup

Configuration

Environment Variables

Using python-dotenv

Custom HTTP Client

Async Client

Sending Emails

Basic HTML Email

With Display Name

Plain Text Email

Multipart Emails (HTML + Text)

Explore the SDK

What’s Next