---
title: "OneSend Python SDK"
description: "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."
url: https://onesend.email/docs/sdk-python/
---
# 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:

```bash
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

```python
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`:

```python
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_`.

```python
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.

```python
try:
    onesend.emails.send({...})
except OneSendError as e:
    if e.code == "domain_not_allowed":
        ...
    raise
```

## Tests

```bash
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.
