posthawk 0.3.0

Official Posthawk SDK for sending emails

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="[e-mail]",
    to="[e-mail]",
    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="[e-mail]",
    to=["[e-mail]", "[e-mail]"],
    cc="[e-mail]",
    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="[e-mail]",
    to="[e-mail]",
    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="[e-mail]",
    to="[e-mail]",
    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="[e-mail]",
        to="[e-mail]",
        subject="Hello",
        html="<h1>Hi</h1>",
    )

API Reference

Method	Description
client.emails.send(...)	Send an email or schedule one
client.emails.get(job_id)	Check delivery status
client.scheduled.list(...)	List scheduled emails
client.scheduled.get(id)	Get a scheduled email
client.scheduled.cancel(id)	Cancel a scheduled email
client.scheduled.reschedule(id, ...)	Reschedule an email

License

MIT