Python SDK quickstart

pushrail is the official Python SDK. It wraps the HTTP API, handles retries with backoff, exposes typed exceptions per error category, and offers an optional buffered mode for high-throughput emit paths. The SDK targets Python 3.9 and newer and is published to PyPI.

Install

pip install pushrail

poetry add pushrail

The package vendors its dependencies on httpx and pydantic.

Initialize

Create one Pushrail instance per process and pass it around. The constructor accepts your API key plus optional configuration.

import os
from pushrail import Pushrail

client = Pushrail(
    api_key=os.environ["PUSHRAIL_API_KEY"],
    # Optional:
    # base_url="https://api.pushrail.io",
    # timeout=10.0,            # seconds
    # max_retries=3,
    # buffered=False,
)

The client is thread-safe for concurrent emit calls. For graceful shutdown, especially with buffered mode, use it as a context manager or call client.close() explicitly.

with Pushrail(api_key=os.environ["PUSHRAIL_API_KEY"]) as client:
    client.events.emit({...})
# close() is called automatically on exit

Send your first event

result = client.events.emit({
    "eventType": "order.completed",
    "source": "checkout-service",
    "customerExternalId": "cust_42",
    "payload": {"orderId": "ord_9001", "totalCents": 4999},
})

print(result.id, result.status)
# e.g. "evt_01HXYZ...", "accepted"

The emit method accepts either a plain dict (as shown) or a pushrail.EmitEvent Pydantic model; pick whichever fits your code. The return is an EmitResult model with id, status, and idempotency_key.

For sending many events in one HTTP request, use client.events.emit_batch([...]), up to 100 events per call. See Ingestion for the full surface and error-handling patterns.