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