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.
onesendis the intended package name, but it is not reserved on PyPI yet. Do notpip install onesendfrom 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
| Namespace | Methods |
|---|---|
emails | send, batch, get, list, iterate, cancel, resend |
domains | list, get, create, verify, delete, zone |
templates | list, get, render, render_source |
contacts | list, iterate, upsert, get, update, delete |
campaigns | list, create, get, update, delete, check, test, schedule, send, pause, resume, cancel, report |
statistics | overview |
suppressions | list, add, remove |
tools | check_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_retriestimes (default 2) with exponential backoff, or after theRetry-Afterheader 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. Passidempotency_key=toemails.send/emails.batchto 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.