Metadata-Version: 2.4
Name: sdk_helo_email
Version: 1.4.0
Summary: Helo Email API (https://helohq.com)
License: MIT
Project-URL: Homepage, https://api.helohq.com
Project-URL: Documentation, https://docs.helohq.com
Project-URL: Repository, https://github.com/helo-email/helo-sdk-python
Keywords: helo,sdk,api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing_extensions>=4.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.22; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"

# Helo Python SDK

Helo Email API (https://helohq.com)

## Installation

```bash
pip install sdk_helo_email
```

Requires Python 3.11+ and installs `httpx` and `pydantic` automatically.

## Quick start

```python
import sdk_helo_email as helo

# The API key is read from HELO_API_KEY when not passed explicitly.
client = helo.Helo()

paginated_events = client.activity.list_events(
    channel_id="550e8400-e29b-41d4-a716-446655440000",
    message_id="550e8400-e29b-41d4-a716-446655440000",
)
```

Pass the key directly when you manage several accounts or read it from a secrets manager:

```python
client = helo.Helo(api_key="your-api-key")
```

Override the base URL, timeout, or retry count (defaults: `https://api.helohq.com`, 30 seconds,
2 retries):

```python
client = helo.Helo(
    base_url="https://api.helohq.com",
    timeout=60.0,
    max_retries=2,
)
```

Use `with` so the underlying connection pool is closed:

```python
with helo.Helo() as client:
    ...
```

## Async

`AsyncHelo` mirrors the synchronous API; every resource method becomes a coroutine.

```python
import asyncio
import sdk_helo_email as helo


async def main() -> None:
    async with helo.AsyncHelo() as client:
        paginated_events = await client.activity.list_events(
            channel_id="550e8400-e29b-41d4-a716-446655440000",
            message_id="550e8400-e29b-41d4-a716-446655440000",
        )


asyncio.run(main())
```

## Automatic retries

A request that fails with a network error, a timeout, or a `408`, `429`, `500`, `502`, `503` or
`504` response is retried up to 2 times, with exponential backoff and full jitter. It
is only retried when sending it again can't do anything twice: a `GET`, `PUT` or `DELETE`,
or a request carrying an idempotency key. A `429` is always retried, since the server
refused the request without acting on it. A `Retry-After` header is honoured; one asking
for more than 8 seconds is not retried early, and the error is returned instead.

Operations that take an idempotency key generate one for each call when you don't pass
one, and send it on every retry, so a send whose response was lost is never sent twice.
Pass your own key to make your own retries (a background job run again, say) safe too.

Set `max_retries=0` on the client to disable retries, or another number to change how many.

## Clearing a field

Leaving an argument out (or passing `None`) leaves the field as it is. To clear a field the API
accepts `null` for, name it in `null_fields`; the method's docstring lists which ones it takes:

```python
client.templates.update(template_id, null_fields=["text"])
```

## Resources

| Attribute | Documentation |
| --------- | ------------- |
| `client.activity` | [docs/Activity.md](docs/Activity.md) |
| `client.broadcasts` | [docs/Broadcasts.md](docs/Broadcasts.md) |
| `client.channels` | [docs/Channels.md](docs/Channels.md) |
| `client.domains` | [docs/Domains.md](docs/Domains.md) |
| `client.sending` | [docs/Sending.md](docs/Sending.md) |
| `client.statistics` | [docs/Statistics.md](docs/Statistics.md) |
| `client.suppressions` | [docs/Suppressions.md](docs/Suppressions.md) |
| `client.templates` | [docs/Templates.md](docs/Templates.md) |
| `client.webhooks` | [docs/Webhooks.md](docs/Webhooks.md) |

## Error handling

Every API error subclasses `APIError` and carries `.status_code`, `.error_code`, `.detail`, and
`.request_id`. `RateLimitError` also exposes `.retry_after`.

```python
import sdk_helo_email as helo

try:
    paginated_events = client.activity.list_events(
except helo.AuthenticationError as exc:
    print(f"auth failed: {exc} (status {exc.status_code})")
except helo.APIError as exc:
    print(f"API error {exc.status_code}: {exc}")
```

| Exception | HTTP status |
| --------- | ----------- |
| `BadRequestError` | 400 |
| `AuthenticationError` | 401 |
| `PermissionDeniedError` | 403 |
| `NotFoundError` | 404 |
| `ConflictError` | 409 |
| `UnprocessableEntityError` | 422 |
| `RateLimitError` | 429 |
| `InternalServerError` | 5xx |

Network failures raise `APIConnectionError` (or `APITimeoutError`) once retries are exhausted.
Both subclass `HeloError`, the base of every exception this library raises.

## Webhook signature verification

Webhook deliveries are signed with the endpoint's signing key. Verify every delivery before
acting on it, against the **raw** request body — parsing and re-serializing the JSON changes
the bytes and the signature will not match.

```python
import json
import os

from flask import Flask, abort, request

import sdk_helo_email as helo

app = Flask(__name__)


@app.post("/webhooks/helo")
def receive_webhook() -> tuple[str, int]:
    try:
        helo.verify_webhook_signature(
            request.headers.get("X-Helo-Webhook-Signature"),
            request.get_data(),  # raw body, exactly as received
            os.environ["HELO_WEBHOOK_SIGNING_KEY"],
        )
    except helo.WebhookSignatureError:
        abort(400)

    event = json.loads(request.get_data())
    # ... handle the event, then acknowledge quickly
    return "", 204
```

`verify_webhook_signature` returns `None` when the signature is valid and raises otherwise.
Each rejection has its own class, so a stale delivery can be treated differently from a
genuinely bad one:

| Exception | Meaning |
| --- | --- |
| `WebhookSignatureMalformedHeaderError` | The header was not in the expected format |
| `WebhookSignatureUnsupportedVersionError` | The delivery used a signing scheme this SDK version cannot verify — upgrade the package |
| `WebhookSignatureTimestampSkewError` | Correctly signed, but too old to accept — possible replay, or clock drift |
| `WebhookSignatureMismatchError` | Wrong signing key, or the body was modified in transit |

All four inherit from `WebhookSignatureError` (itself a `HeloError`), so catch that
one class to handle any rejection. If you only want a boolean, use
`is_valid_webhook_signature` instead:

```python
if helo.is_valid_webhook_signature(signature_header, raw_body, signing_key):
    ...
```

The body may be passed as `str` or `bytes`. The signature header may carry several versions at
once (`t=...,v1=...,v2=...`) while a new signing scheme is being rolled out. This SDK verifies
against the newest version it supports (`SUPPORTED_WEBHOOK_SIGNATURE_VERSIONS`) and ignores
elements it does not recognize, so a rollout will not break this integration.

To compute a signature yourself — signing a fixture in tests, for example — use
`generate_webhook_signature(payload, signing_key, timestamp)`.

## Development

```bash
make install
make check
make test
```
