Skip to content

python.mdx

Latest commit

 

History

History
167 lines (121 loc) · 3.72 KB

python.mdx

File metadata and controls

167 lines (121 loc) · 3.72 KB
Raw
title Python SDK
description Official ByteSend Python SDK for sending emails and managing contacts.
icon python

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

Installation

Install from PyPI:

pip install bytesend

Initialize

from bytesend import ByteSend, types


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

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

client = ByteSend("bs_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)

ByteSend forwards your custom headers to SES. Only the X-ByteSend-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 ByteSendHTTPError for non-2xx responses. To handle errors as return values, pass raise_on_error=False.

from bytesend import ByteSend, ByteSendHTTPError

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

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