python-posthorn

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

Install locally

pip install -e ./python-posthorn

Basic usage

from python_posthorn import PosthornClient

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

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

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:

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