vorlek 1.1.0

Python SDK for the Vorlek email-marketing aggregation API

Vorlek Python SDK

Python client for the Vorlek API. It exposes the Phase 2 tool surface with automatic idempotency keys, normalized {data, meta} results, and typed exceptions for API and network failures.

pip install vorlek

Requires Python 3.10 or newer.

Quickstart (sync)

import os

from vorlek import VorlekClient

with VorlekClient(api_key=os.environ["VORLEK_API_KEY"]) as client:
    result = client.contact.upsert(
        provider="sendgrid",
        email="[e-mail]",
        first_name="Jamie",
        properties={"plan": "free"},
    )

print(result.data["contact_id"])
print(result.meta.request_id)

Quickstart (async)

import asyncio
import os

from vorlek import AsyncVorlekClient


async def main() -> None:
    async with AsyncVorlekClient(api_key=os.environ["VORLEK_API_KEY"]) as client:
        result = await client.connection.status(provider="sendgrid")
        print(result.data["status"])
        print(result.meta.request_id)


asyncio.run(main())

Methods

All tool calls are keyword-only and return VorlekResult[T], where result.data is the normalized tool payload and result.meta includes the request id, quota state, rate-limit state, and idempotency replay state when present.

result.data is parsed JSON: at runtime it is dict[str, object], even though the per-tool aliases (UpsertContactResult, SendTransactionalResult, etc.) point at the generated dataclasses for type-checker convenience. Use subscript syntax — result.data["contact_id"], not result.data.contact_id.

Namespace	Method	Endpoint
client.contact	upsert(...)	POST /v1/tools/upsert_contact
client.connection	status(...)	POST /v1/tools/get_connection_status
client.send	transactional(...)	POST /v1/tools/send_transactional
client.campaign	stats(...)	POST /v1/tools/get_campaign_stats
client.campaign	list(...)	POST /v1/tools/list_campaigns
client.template	list(...)	POST /v1/tools/list_templates

Supported providers are sendgrid, mailchimp, and klaviyo. Argument types are generated from the live OpenAPI schema and are also documented at https://vorlek.dev/openapi.json.

Error handling

Vorlek raises subclasses of VorlekError. Caller mistakes are grouped under VorlekClientError, while more specific classes let applications handle common cases directly.

from vorlek import (
    VorlekClient,
    VorlekClientError,
    VorlekError,
    VorlekRateLimitedError,
    is_retryable_error,
)

client = VorlekClient(api_key="vk_live_...")

try:
    result = client.contact.upsert(provider="sendgrid", email="[e-mail]")
except VorlekRateLimitedError as err:
    print(f"rate limited, retry after {err.retry_after} seconds")
except VorlekClientError as err:
    print(f"fix the request before retrying: {err.code} {err.message}")
except VorlekError as err:
    if is_retryable_error(err):
        print(f"retry with backoff: {err.code}")
    else:
        print(f"not retry-safe: {err.code}")
else:
    print(result.data)
finally:
    client.close()

Every error exposes code, category, retry_safe, http_status, request_id, provider, retry_after, and detail.

Idempotency

Every tool call sends an Idempotency-Key header. By default the SDK generates a fresh ULID per request.

Pass idempotency_key to retry one logical operation with the same key:

result = client.contact.upsert(
    provider="mailchimp",
    email="[e-mail]",
    idempotency_key="01HV0011V0110011V011001100",
)
print(result.meta.idempotency.replay if result.meta.idempotency else False)

Calling the same key twice with the same request body is safe. Reusing the same key with a different body raises VorlekIdempotencyConflictError.

from_ on transactional sends

Python reserves from as a keyword, so the SDK accepts from_ and sends it to the API as from.

client.send.transactional(
    provider="sendgrid",
    to="[e-mail]",
    from_="[e-mail]",
    subject="Welcome",
    text="Thanks for trying Vorlek.",
)

Test mode

vk_test_* keys pass through the SDK today. Full test-mode behavior, including provider-free deterministic tool responses, is planned for Phase 3.6 and will be documented at https://vorlek.dev/docs/test-mode when it ships.

Examples

The examples/ directory contains small scripts that run from a virtual environment:

export VORLEK_API_KEY=vk_live_...
python examples/upsert.py
python examples/send_transactional.py
python examples/cross_provider_round_trip.py

Each script exits successfully with a skip message when required environment variables are missing.

Cross-SDK parity

The TypeScript SDK is published as @vorlek/sdk. Both SDKs surface the same {data, meta} success contract and the same six tool namespaces. Python v1 ships the full 18-class error hierarchy; the TypeScript retrofit is tracked at https://github.com/vorlek/vorlek-sdk-ts/issues/2.

Local development

python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"

ruff check .
ruff format --check .
mypy src/vorlek
pytest -q
python scripts/generate_types.py && git diff --exit-code src/vorlek/_generated/