Metadata-Version: 2.4
Name: ai-newsletter
Version: 1.0.2
Summary: Official Python SDK for the Signal AI / AI Newsletter public REST API.
Author: Signal AI
License: MIT
Project-URL: Homepage, https://ai-newsletter.app/developers
Project-URL: Documentation, https://ai-newsletter.app/developers
Project-URL: Changelog, https://github.com/ai-newsletter/sdks/blob/main/CHANGELOG.md
Keywords: ai-newsletter,signal-ai,newsletter,email,sdk,api
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-httpx>=0.30; extra == "dev"

# ai-newsletter (Python)

Official Python SDK for the Signal AI public REST API.

## Install

```bash
pip install ai-newsletter
```

## Quick start

```python
from ai_newsletter import AiNewsletter

with AiNewsletter(api_key="sk_live_…") as client:  # or sk_test_…
    client.subscribers.create(newsletter_id="d5…", email="jane@example.com")

    job = client.sends.create(
        newsletter_id="d5…",
        type="transactional",
        to="jane@example.com",
        subject="Welcome!",
        html="<p>Hi Jane</p>",
    )

    stats = client.analytics.for_newsletter("d5…")
    print(stats["open_rate"])
```

## Pagination

```python
for sub in client.subscribers.iterate(newsletter_id="d5…"):
    print(sub["email"])
```

## Retries & timeouts

Retries (with exponential backoff and jitter) are automatic for
`408 / 425 / 429 / 5xx` and network errors. `Retry-After` is honoured.

```python
client = AiNewsletter(api_key="…", max_retries=5, timeout=60.0)
```

## Errors

```python
from ai_newsletter import AiNewsletterError

try:
    client.subscribers.create(...)
except AiNewsletterError as e:
    print(e.status, e.code, str(e), e.retry_after)
```

## Verify webhooks

```python
from ai_newsletter import verify_webhook_signature

if not verify_webhook_signature(raw_body, request.headers["X-Webhook-Signature"], SECRET):
    abort(401)
```

## Test mode

Pass an `sk_test_` key — all traffic targets the sandbox tables.
`client.is_test` reports the mode.

## License

MIT
