eSauti Marketing SDK for Python

Send customer and business events to an eSauti marketing tenant to drive marketing workflows. This SDK also retains its marketing REST API support for contacts, campaigns, and other tenant resources.

Customer API: Verify, WhatsApp, and Wallet

One esauti installation includes both Marketing and the Customer API:

import os
from esauti.api import ESauti

api = ESauti(os.environ["ESAUTI_API_KEY"])
balance = api.wallet.balance()
verification = api.verify.create(
    {"recipient": "+14165551234", "channel": "whatsapp", "language": "en"},
    idempotency_key="signup-123-send-otp-1",
)

The Customer API defaults to https://api.esauti.com and has its own API key. It exposes verify, whatsapp, and wallet, with typed dictionaries in esauti.api.models and errors in esauti.api.errors. It makes one request attempt, rejects redirects, and requires explicit idempotency keys where specified. Existing from esauti import EsautiClient usage, client.api tenant resources, and Marketing events remain available with their existing configuration.

Migrating from esauti-api: replace from esauti_api import ESauti with from esauti.api import ESauti. Update model and error imports in the same way, install this repository's esauti package, then remove the old esauti-api dependency. Method calls and response dictionaries are unchanged.

See Customer API documentation for all operations, error handling, and retry guidance.

Which SDK should I use?

The Marketing SDK keeps the existing esauti package, imports, and public methods. Both SDKs can coexist and release independently. Configure each client with the credentials and endpoint for its own product.

Requirements

• Python 3.10+
• requests >= 2.20

Installation

pip install esauti

Or from source:

git clone https://github.com/esauti/pyesauti
cd pyesauti
pip install -e ".[dev]"

Quick Start

Event Injection

from esauti import EsautiClient
from esauti.events import EventType

client = EsautiClient(
    base_url="https://your-instance.esauti.com",
    token="YOUR_BEARER_TOKEN",
)

receipt = client.events.send(
    EventType.CUSTOMER_CREATED,
    customer={"id": "cus_123", "email": "jane@esauti.com"},
    data={"status": "active"},
    source="my-app",
)
print(receipt)

HMAC Signing

from esauti import EsautiClient

client = EsautiClient(
    base_url="https://your-instance.esauti.com",
    token="YOUR_BEARER_TOKEN",
    hmac_secret="your-hmac-secret",
)

receipt = client.events.send(
    "order.created",
    customer={"id": "cus_456"},
    data={"value": 99.99, "currency": "USD"},
    source="shopify",
)

Marketing REST API

from esauti import EsautiClient

client = EsautiClient(
    base_url="https://your-instance.esauti.com/api",
    token="YOUR_BEARER_TOKEN",
)

# List contacts
contacts = client.api.contacts.list(limit=10)
print(contacts)

# Create a contact
contact = client.api.contacts.create({"firstname": "Jane", "email": "jane@esauti.com"})
print(contact)

Configuration

client = EsautiClient(
    base_url="https://...",
    token="...",
    hmac_secret=None,           # optional HMAC secret for event signing
    timeout=30.0,               # request timeout in seconds
    max_retries=3,              # max retry attempts
    debug=False,                # enable debug logging
    redact_pii=False,           # redact email/phone in logs
    events_endpoint="/api/integrations/events",  # override events URL
    source="sdk",               # X-eSauti-Source header value
)

Running Tests

pip install -e ".[dev]"
pytest

Project Structure

src/esauti/
├── __init__.py         # Public API
├── client.py           # EsautiClient entrypoint
├── auth.py             # BearerAuth, HmacAuth, CompositeAuth
├── transport.py        # HttpTransport abstraction + requests impl
├── retry.py            # RetryPolicy with exponential backoff + jitter
├── exceptions.py       # ApiError, EventValidationError
├── _logging.py         # Redacting structured logger
├── deadletter.py       # DeadLetter sink (JSONL file or custom hook)
├── api/
│   ├── __init__.py
│   └── client.py       # OpenAPI module (contacts, campaigns, etc.)
└── events/
    ├── __init__.py
    ├── registry.py     # EventType enum + registry loader
    ├── builder.py      # Event envelope builder + validator
    └── client.py       # EventsClient (build / send)

Documentation

Changelog

See CHANGELOG.md.