Metadata-Version: 2.4
Name: poststack
Version: 0.4.0
Summary: Official Python SDK for the PostStack Email API
Project-URL: Homepage, https://poststack.dev
Project-URL: Documentation, https://poststack.dev/docs
Project-URL: Repository, https://github.com/getpoststack/python-sdk
Project-URL: Issues, https://github.com/getpoststack/python-sdk/issues
Author: PostStack
License: MIT
License-File: LICENSE
Keywords: api,email,poststack,smtp,transactional
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: respx>=0.20.0; extra == 'dev'
Description-Content-Type: text/markdown

# PostStack Python SDK

Official Python SDK for the [PostStack](https://poststack.dev) Email API —
an [EU-hosted, GDPR-compliant](https://poststack.dev/security)
[email API for Python](https://poststack.dev) with sync and async clients,
full type hints, and drop-in compatibility with Django, FastAPI, Flask,
and Starlette. Up to 75% cheaper than Resend, SendGrid, and Postmark.

Docs: [poststack.dev/docs/sdk](https://poststack.dev/docs/sdk).

## Installation

```bash
pip install poststack
```

Requires Python 3.10+.

## Quick start

```python
from poststack import PostStack

client = PostStack(api_key="sk_live_...")

result = client.emails.send({
    "from": "hello@example.com",
    "to": ["user@example.com"],
    "subject": "Hello from PostStack",
    "html": "<p>Welcome!</p>",
})

print(result["id"])
```

## Async usage

```python
import asyncio
from poststack import AsyncPostStack

async def main():
    client = AsyncPostStack(api_key="sk_live_...")
    try:
        result = await client.emails.send({
            "from": "hello@example.com",
            "to": ["user@example.com"],
            "subject": "Hello from PostStack",
            "html": "<p>Welcome!</p>",
        })
        print(result["id"])
    finally:
        await client.aclose()

asyncio.run(main())
```

Or use it as an async context manager:

```python
async with AsyncPostStack(api_key="sk_live_...") as client:
    result = await client.emails.send({...})
```

## Error handling

Any non-2xx response raises `PostStackError`:

```python
from poststack import PostStack, PostStackError

client = PostStack(api_key="sk_live_...")

try:
    client.emails.send({"from": "x@y.com", "to": ["z@w.com"], "subject": "hi"})
except PostStackError as e:
    print(e.status_code, e.error, e.request_id)
```

## Configuration

```python
client = PostStack(
    api_key="sk_live_...",
    base_url="https://api.poststack.dev",  # default
    timeout=30.0,                           # default (seconds)
)
```

Override timeout per call:

```python
client.emails.send({...}, timeout=60.0)
```

## Resources

- `client.emails` — send, get, list, cancel, reschedule, batch, events, insights
- `client.domains` — create, list, get, verify, update, delete, DMARC
- `client.contacts` — CRUD, import, export, unsubscribe
- `client.contact_properties` — custom properties
- `client.segments` — create, list, get, update, delete, contacts, preview
- `client.templates` — CRUD, publish, duplicate, presets
- `client.webhooks` — CRUD, test, deliveries, replay
- `client.broadcasts` — CRUD, send, test, variants
- `client.suppressions` — list, add, remove
- `client.api_keys` — CRUD
- `client.mailboxes` — CRUD, aliases, password
- `client.subscription_topics` — topics + contact subscriptions
- `client.workflows` — CRUD, steps, activate, pause, trigger
- `client.signup_forms` — CRUD, submit
- `client.email_validations` — validate, validate_batch

## Links

- [PostStack — EU-hosted email API](https://poststack.dev)
- [API documentation](https://poststack.dev/docs)
- [Pricing](https://poststack.dev/pricing) · [Compare providers](https://poststack.dev/pricing/compare)
- [Migrate from Resend](https://poststack.dev/migrate/resend) · [from SendGrid](https://poststack.dev/migrate/sendgrid) · [from Postmark](https://poststack.dev/migrate/postmark)
- [Status](https://poststack.dev/status) · [Security](https://poststack.dev/security) · [DPA](https://poststack.dev/dpa)

## License

MIT — see [LICENSE](./LICENSE).
