Helo Email API (https://helohq.com)
pip install sdk_helo_emailRequires Python 3.11+ and installs httpx and pydantic automatically.
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:
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):
client = helo.Helo(
base_url="https://api.helohq.com",
timeout=60.0,
max_retries=2,
)Use with so the underlying connection pool is closed:
with helo.Helo() as client:
...AsyncHelo mirrors the synchronous API; every resource method becomes a coroutine.
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())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.
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:
client.templates.update(template_id, null_fields=["text"])| Attribute | Documentation |
|---|---|
client.activity |
docs/Activity.md |
client.broadcasts |
docs/Broadcasts.md |
client.channels |
docs/Channels.md |
client.domains |
docs/Domains.md |
client.sending |
docs/Sending.md |
client.statistics |
docs/Statistics.md |
client.suppressions |
docs/Suppressions.md |
client.templates |
docs/Templates.md |
client.webhooks |
docs/Webhooks.md |
Every API error subclasses APIError and carries .status_code, .error_code, .detail, and
.request_id. RateLimitError also exposes .retry_after.
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 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.
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 "", 204verify_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:
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).
make install
make check
make test