Python SDK

This guide shows how to install and use the official usesend Python SDK.

Installation

Install from PyPI:

pip install usesend

Initialize

from usesend import UseSend, types


# Option A: pass values directly (helpful in scripts/tests)
client = UseSend("us_xxx")

# Option B: custom base URL (self-hosted)
client = UseSend("us_xxx", url="https://your-domain.example")

Send an email

EmailCreate is a TypedDict for editor hints; at runtime you pass a regular dict. The client accepts from or from_ (it normalizes from_ to from).

from usesend import UseSend, types

client = UseSend("us_xxx")

payload: types.EmailCreate = {
    "to": "[email protected]",
    "from": "[email protected]",
    "subject": "Welcome",
    "html": "<strong>Hello!</strong>",
    "headers": {"X-Campaign": "welcome"},
}

data, err = client.emails.send(payload)
print(data or err)

useSend forwards your custom headers to SES. Only the X-Usesend-Email-ID and References headers are managed automatically. Attachments and scheduling:

from datetime import datetime, timedelta

payload: types.EmailCreate = {
    "to": ["[email protected]", "[email protected]"],
    "from": "[email protected]",
    "subject": "Report",
    "text": "See attached.",
    "attachments": [
        {"filename": "report.txt", "content": "SGVsbG8gd29ybGQ="},  # base64
    ],
    "scheduledAt": datetime.utcnow() + timedelta(minutes=10),
}
data, err = client.emails.create(payload)

Batch send

items: list[types.EmailBatchItem] = [
    {"to": "[email protected]", "from": "[email protected]", "subject": "A", "html": "<p>A</p>"},
    {"to": "[email protected]", "from": "[email protected]", "subject": "B", "html": "<p>B</p>"},
]
data, err = client.emails.batch(items)

Retrieve and manage emails

Get an email:

email, err = client.emails.get("email_123")

Update schedule time:

from datetime import datetime, timedelta

update: types.EmailUpdate = {"scheduledAt": datetime.utcnow() + timedelta(hours=1)}
data, err = client.emails.update("email_123", update)

Cancel a scheduled email:

data, err = client.emails.cancel("email_123")

Contacts

All contact operations require a contact book ID (book_id). Create a contact:

create: types.ContactCreate = {
    "email": "[email protected]",
    "firstName": "Jane",
    "properties": {"plan": "pro"},
}
data, err = client.contacts.create("book_123", create)

Get a contact:

contact, err = client.contacts.get("book_123", "contact_456")

Update a contact:

update: types.ContactUpdate = {"subscribed": False}
data, err = client.contacts.update("book_123", "contact_456", update)

Upsert a contact:

upsert: types.ContactUpsert = {
    "email": "[email protected]",
    "firstName": "Jane",
}
data, err = client.contacts.upsert("book_123", "contact_456", upsert)

Delete a contact:

data, err = client.contacts.delete(book_id="book_123", contact_id="contact_456")

Error handling

By default the client raises UseSendHTTPError for non-2xx responses. To handle errors as return values, pass raise_on_error=False.

from usesend import UseSend, UseSendHTTPError

# Raises exceptions on errors (default)
client = UseSend("us_xxx")
try:
    data, _ = client.emails.get("email_123")
except UseSendHTTPError as e:
    print("request failed:", e)

# Returns (None, error) instead of raising
client = UseSend("us_xxx", raise_on_error=False)
data, err = client.emails.get("email_123")
if err:
    print("error:", err)

Getting Started

Self Hosting

Guides

Installation

Initialize

Send an email

Batch send

Retrieve and manage emails

Contacts

Error handling

​Installation

​Initialize

​Send an email

​Batch send

​Retrieve and manage emails

​Contacts

​Error handling

Installation

Initialize

Send an email

Batch send

Retrieve and manage emails

Contacts

Error handling