Python
SDK
The official Posthawk SDK for Python. Built on httpx with typed dataclass responses and a simple result pattern. Send your first email in under a minute.
$ pip install posthawkposthawkSend emails with
five lines of code
Initialize the client, call send, and check the result. Every method returns a PosthawkResponse with .data and .error.
from posthawk import Posthawkclient = Posthawk("ck_live_...")result = client.emails.send( from_email="hello@yourdomain.com", to="user@example.com", subject="Welcome!", html="<h1>Hello!</h1>",)if result.error: print(result.error.message)else: print("Sent!", result.data.job_id)from posthawk import Posthawkclient = Posthawk("ck_live_...")# Every method returns PosthawkResponseresult = client.emails.send( from_email="hello@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"Job ID: {result.data.job_id}") print(f"Status URL: {result.data.status_url}")No try/except
needed
SDK methods never raise exceptions for API errors. Check result.error first, then access result.data safely.
Schedule, cancel,
and send now
Send later by adding scheduled_for. Full management API to list, cancel, reschedule, or send immediately with send_now.
# Schedule for laterfrom datetime import datetime, timedelta, timezoneresult = client.emails.send( from_email="hello@yourdomain.com", to="user@example.com", subject="Reminder", text="Don't forget your meeting!", scheduled_for=datetime.now(timezone.utc) + timedelta(hours=24),)# Manage scheduled emailsresult = client.scheduled.list(status="scheduled")client.scheduled.cancel("id")client.scheduled.reschedule( "id", scheduled_for="2026-04-01T10:00:00Z")# Send a scheduled email immediatelyclient.scheduled.send_now("id")# Create a newsletterresult = client.newsletters.create( slug="weekly-digest", name="Weekly Digest", double_opt_in=True,)nl_id = result.data.id# Add a subscriberclient.newsletters.add_subscriber( nl_id, email="user@example.com", name="Alex",)# Create and send an issueissue = client.newsletters.create_issue( nl_id, subject="Issue #1: Getting Started", html="<h1>Welcome!</h1><p>Your first issue.</p>",)client.newsletters.send_issue(nl_id, issue.data.id)Publish issues,
manage subscribers
Full newsletter management API: create newsletters, add subscribers, draft issues, and send to all active subscribers in one call.
Batch sends &
a clean list
Queue up to 100 emails in one call with emails.batch, and manage the suppression list with suppressions so bounced and complained addresses never get hit again.
# Send up to 100 emails in a single callresult = client.emails.batch([ {"from_email": "hi@you.com", "to": "a@example.com", "subject": "Hi", "html": "<p>One</p>"}, {"from_email": "hi@you.com", "to": "b@example.com", "subject": "Hi", "template_id": "t_welcome"},])print(result.data.queued, result.data.failed)# Keep your sender reputation cleanclient.suppressions.create(email="bounced@example.com")result = client.suppressions.list()One client,
the whole API
Every Posthawk endpoint is a typed method on the client — no raw HTTP, no guessing at shapes.
client.emailssend · get · batch
client.scheduledlist · get · cancel · reschedule · send_now
client.broadcastscreate · list · send · cancel
client.newslettersissues · subscribers · CRUD
client.contactslist · create · update · import_contacts
client.domainsverify · receiving · update_limits · webhook
client.webhookscreate · update · test · delete
client.suppressionslist · create · delete
client.templatesrender
Up and running
in minutes
Install the package
One command to add Posthawk to your project. Only requires httpx as a dependency.
Create a client
Initialize with your API key. The SDK handles auth headers, serialization, and error wrapping.
Send your first email
Call client.emails.send() with your content. Get back a typed dataclass with delivery status.
Dataclass Responses
Every response is a typed dataclass with .data and .error attributes. Full IDE autocomplete out of the box.
httpx Powered
Built on httpx with connection pooling and a 30s timeout. Context manager support for clean resource cleanup.
Schedule Emails
Schedule, list, cancel, and reschedule emails. Accepts datetime objects or ISO 8601 strings.
Never Raises
Every method returns PosthawkResponse with .data and .error — no try/except needed. Only the constructor raises for missing keys.
Start sending emails
Install the SDK and send your first email in under a minute.