Posthawk Python SDK

The official Python SDK for Posthawk — send transactional emails, schedule deliveries, and manage email jobs.

Install

pip install posthawk

Quick Start

from posthawk import Posthawk

client = Posthawk("ck_live_...")

result = client.emails.send(
    from_email="hi@yourdomain.com",
    to="user@example.com",
    subject="Hello from Posthawk",
    html="<h1>Welcome!</h1><p>Your account is ready.</p>",
)

if result.error:
    print(result.error.message)
else:
    print(f"Sent! Job ID: {result.data.job_id}")

Send Email

result = client.emails.send(
    from_email="hi@yourdomain.com",
    to=["alice@example.com", "bob@example.com"],
    cc="manager@example.com",
    subject="Weekly Report",
    html="<h1>Report</h1>",
    text="Plain text fallback",
    headers={"X-Custom": "value"},
    metadata={"campaign": "onboarding"},
    tags={"type": "transactional"},
)

Schedule Emails

from datetime import datetime, timedelta, timezone

result = client.emails.send(
    from_email="hi@yourdomain.com",
    to="user@example.com",
    subject="Reminder",
    text="Don't forget your appointment tomorrow!",
    scheduled_for=datetime.now(timezone.utc) + timedelta(hours=24),
)

print(f"Scheduled for: {result.data.scheduled_for}")

Check Delivery Status

result = client.emails.get("job-id-here")

if not result.error:
    print(f"Status: {result.data.status}")
    # pending | processing | completed | failed

Manage Scheduled Emails

# List all scheduled emails
result = client.scheduled.list(status="scheduled", limit=10)
for email in result.data.data:
    print(f"{email.subject} → {email.scheduled_for}")

# Get a specific scheduled email
result = client.scheduled.get("scheduled-email-id")

# Cancel before it sends
result = client.scheduled.cancel("scheduled-email-id")

# Reschedule to a new time
result = client.scheduled.reschedule(
    "scheduled-email-id",
    scheduled_for="2026-04-01T10:00:00Z",
)

Self-Hosted

Point the SDK at your own Posthawk instance:

client = Posthawk("ck_live_...", base_url="https://api.yourdomain.com")

Error Handling

SDK methods never raise exceptions for API errors. Every method returns a PosthawkResponse with .data and .error:

result = client.emails.send(
    from_email="hi@yourdomain.com",
    to="user@example.com",
    subject="Test",
    html="<p>Hello</p>",
)

if result.error:
    print(f"Error {result.error.status_code}: {result.error.message}")
else:
    print(f"Success: {result.data.job_id}")

Context Manager

Use a context manager to automatically close the HTTP connection pool:

with Posthawk("ck_live_...") as client:
    result = client.emails.send(
        from_email="hi@yourdomain.com",
        to="user@example.com",
        subject="Hello",
        html="<h1>Hi</h1>",
    )

API Reference

License

MIT