Metadata-Version: 2.4
Name: python-posthorn
Version: 0.5.0
Summary: Zero-dependency Python client for the Posthorn HTTP API
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# python-posthorn

Zero-dependency Python client for Posthorn's HTTP API.

## Install locally

```bash
pip install -e ./python-posthorn
```

## Basic usage

```python
from python_posthorn import PosthornClient

client = PosthornClient(
    "http://localhost:8888",
    "your-api-key",
    default_path="/api/transactional",
)

response = client.send({"message": "hello"})
print(response)
```

> [!NOTE]
> The endpoint path and required payload fields are configured per
> deployment and not fixed by this client. For example, the deployment at
> `example.com:8080` exposes its send endpoint at `/api/send` and
> requires both `message` and `subject_line`:
>
> ```python
> client = PosthornClient(
>     "http://example.com:8080",
>     "your-api-key",
>     default_path="/api/send",
> )
>
> response = client.send({"message": "hello", "subject_line": "Greetings"})
> ```
>
> Check with the operator of your Posthorn instance for its configured path
> and required fields.

## Setting the recipient

In API-key mode, each endpoint has a configured recipient (`to`) list — the
payload does not need a `to` or `email` field for that. To send to a
different recipient for a single request, set the reserved `to_override`
field to a string or a list of email addresses:

```python
response = client.send({
    "message": "hello",
    "subject_line": "Greetings",
    "to_override": "alice@example.com",
})
```

`to_override` only overrides recipients; the sender identity is fixed by the
endpoint configuration and cannot be overridden per-request.

## Features

- `GET /healthz`
- `GET /metrics`
- authenticated JSON send requests
- `Idempotency-Key` support
- typed `200` success and dry-run responses
- typed `422` validation errors
- explicit exception classes for `401`, `409`, `429`, and `502`
