Metadata-Version: 2.4
Name: posthawk
Version: 0.1.0
Summary: Official Posthawk SDK for sending emails
Project-URL: Homepage, https://posthawk.dev
Project-URL: Documentation, https://docs.posthawk.dev/sdk-python
Project-URL: Repository, https://github.com/endibuka/posthawk-python
License-Expression: MIT
Keywords: email,posthawk,sdk,transactional-email
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24.0
Description-Content-Type: text/markdown

# Posthawk Python SDK

The official Python SDK for [Posthawk](https://posthawk.dev) — send transactional emails, schedule deliveries, and manage email jobs.

## Install

```bash
pip install posthawk
```

## Quick Start

```python
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

```python
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

```python
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

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

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

## Manage Scheduled Emails

```python
# 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:

```python
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`:

```python
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:

```python
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

| 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
