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

​
Installation

Install from PyPI: 
pip install weesend

​
Initialize

from weesend import WeeSend, types


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

# Option B: custom base URL (self-hosted)
client = WeeSend("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 weesend import WeeSend, types

client = WeeSend("us_xxx")

payload: types.EmailCreate = {
    "to": "user@example.com",
    "from": "no-reply@yourdomain.com",
    "subject": "Welcome",
    "html": "<strong>Hello!</strong>",
    "headers": {"X-Campaign": "welcome"},
}

data, err = client.emails.send(payload)
print(data or err)
weeSend forwards your custom headers to SES. Only the X-Weesend-Email-ID and References headers are managed automatically. Attachments and scheduling: 
from datetime import datetime, timedelta

payload: types.EmailCreate = {
    "to": ["user1@example.com", "user2@example.com"],
    "from": "no-reply@yourdomain.com",
    "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": "a@example.com", "from": "no-reply@yourdomain.com", "subject": "A", "html": "<p>A</p>"},
    {"to": "b@example.com", "from": "no-reply@yourdomain.com", "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": "user@example.com",
    "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": "user@example.com",
    "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 WeeSendHTTPError for non-2xx responses. To handle errors as return values, pass raise_on_error=False. 
from weesend import WeeSend, WeeSendHTTPError

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

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