Skip to main content

Helo Python SDK

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

Installation

pip install sdk_helo_email

Requires Python 3.11+ and installs httpx and pydantic automatically.

Quick start

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:
    ...

Async

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())

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:

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

Resources

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

Error handling

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 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.

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:

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

make install
make check
make test

Metadata

Release files for sdk-helo-email 1.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sdk-helo-email 1.4.0
File Size Uploaded Provenance Actions
sdk_helo_email-1.4.0.tar.gz 32.3 kB With provenance Details for sdk_helo_email-1.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sdk-helo-email 1.4.0
File Interpreter ABI Platform Actions
sdk_helo_email-1.4.0-py3-none-any.whl Python 3 none any Details for sdk_helo_email-1.4.0-py3-none-any.whl

Total release size: 66.5 kB

Release files / sdk_helo_email-1.4.0.tar.gz

Download URL sdk_helo_email-1.4.0.tar.gz
Size 32.3 kB
Tags Source
SHA-256 checksum
How to use checksums
4283cab3ecdf1e499f2c3721351362fffdca1a2a78c967dddcabf1625e34bddd
BLAKE2b-256 checksum
How to use checksums
331111b5a9275d684c34a244effa8a668b9d71a3eeaa6402c0c9156fd4a1f3c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / sdk_helo_email-1.4.0-py3-none-any.whl

Download URL sdk_helo_email-1.4.0-py3-none-any.whl
Size 34.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b3d0e5ef13f69d8fbd412721cbe56d190366d7dee3120223fd0a1b3cd75cab12
BLAKE2b-256 checksum
How to use checksums
843f9101886a6d077be25e585de79dcbd732742ff53e0904e64701d071b56b62
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for sdk-helo-email 1.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sdk_helo_email-1.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page