Skip to main content
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.
1

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

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

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