Docs / Developers and AI

OneSend Python SDK

Python client for a self-hosted OneSend server. It uses only the standard library (urllib), so it has no dependencies. Python 3.9 or later.

Not published to PyPI. onesend is the intended package name, but it is not reserved on PyPI yet. Do not pip install onesend from PyPI: that name is not controlled by this project. Install from this repository as shown below.

Install

From a clone of the repository:

pip install ./packages/sdk-python
# or, while working on the SDK:
pip install -e ./packages/sdk-python

You can also copy the onesend/ folder into your project.

Usage

from onesend import OneSend, OneSendError

onesend = OneSend(api_key="os_live_…", base_url="http://localhost:3000")
# or set ONESEND_API_KEY and ONESEND_BASE_URL and call OneSend()

sent = onesend.emails.send(
    {"from": "Acme <hello@acme.dev>", "to": "ada@example.com", "template": "welcome-email", "variables": {"first_name": "Ada"}},
    idempotency_key="signup-42",
)
print(sent["id"], sent["status"])

Send the template slug and its variables, not HTML. OneSend renders the template and gives the provider finished HTML, so one template works with every provider and during failover. welcome-email is the gallery template Welcome email copied into your workspace (Templates → Template gallery in the dashboard, or POST /v1/gallery/welcome-folio/clone with {"slug": "welcome-email"}).

For a one-off email without a template, send subject and html or text:

onesend.emails.send({"from": "hello@acme.dev", "to": "ada@example.com", "subject": "Hello", "text": "Hi Ada"})

There is no default server: base_url (or ONESEND_BASE_URL) is required, so the API key is only sent to a server you chose.

Responses are plain dictionaries with the field names of the REST API (camelCase). onesend.types has TypedDict definitions for editors and type checkers; /openapi.json on your server is the full schema.

Namespaces

NamespaceMethods
emailssend, batch, get, list, iterate, cancel, resend
domainslist, get, create, verify, delete, zone
templateslist, get, render, render_source
contactslist, iterate, upsert, get, update, delete
campaignslist, create, get, update, delete, check, test, schedule, send, pause, resume, cancel, report
statisticsoverview
suppressionslist, add, remove
toolscheck_dns, check_content, analyze_headers, check_addresses, generate_dmarc, build_spf

from is a Python keyword. In request dictionaries write "from"; in keyword filters (emails.list, statistics.overview) use from_.

for email in onesend.emails.iterate(status="bounced", from_="2026-11-01T00:00:00Z"):
    print(email["id"], email["to"])

onesend.emails.batch([
    {"from": "hello@acme.dev", "to": "a@example.com", "subject": "1", "text": "One"},
    {"from": "hello@acme.dev", "to": "b@example.com", "subject": "2", "template": "welcome", "variables": {"name": "Bo"}},
], idempotency_key="nightly-2026-11-08")

report = onesend.tools.check_content(subject="Our November update", html=html, type="broadcast")
for f in report["findings"]:
    print(f["level"], f["message"])

Errors, retries and idempotency

Errors raise OneSendError with status, type, code, message, details and request_id (status is 0 for network errors).

  • Network errors, 408, 429 and 5xx responses are retried up to max_retries times (default 2) with exponential backoff, or after the Retry-After header when the server sends one. Other 4xx errors are not retried.
  • Every POST, PATCH and DELETE sends an Idempotency-Key, the same one on each retry, so a retried send is not sent twice. Pass idempotency_key= to emails.send / emails.batch to keep it stable across processes or restarts; in a batch, item i uses <key>:<i>.
  • timeout (seconds, default 30) applies to each attempt.
try:
    onesend.emails.send({...})
except OneSendError as e:
    if e.code == "domain_not_allowed":
        ...
    raise

Tests

cd packages/sdk-python
python3 -m unittest discover -s tests

The tests run against a local mock HTTP server and do not need a OneSend server.

License

MIT, like the TypeScript SDK.