UniLink Python SDK (Build With UniLink Using Python)

The official UniLink Python SDK gives you a clean, Pythonic interface to the UniLink API — install it in one command and build data pipelines, Django integrations, and automation scripts with minimal boilerplate.

Python is the dominant language for data pipelines, automation scripts, and backend integrations that move data between services. The UniLink Python SDK brings the same clean, documented interface to the Python ecosystem that the JavaScript SDK provides for Node.js — install it in a virtual environment, set your API key as an environment variable, and start calling methods with named parameters and typed return values. Whether you are writing a nightly script that syncs UniLink contacts to your data warehouse, a Django view that shows order history, or a Flask webhook handler, the SDK handles the HTTP layer so you can focus on the logic.

What the Python SDK Does

The UniLink Python SDK provides a synchronous client built on the requests library and an asynchronous client built on aiohttp. The synchronous UniLink class is the right choice for scripts, Celery tasks, management commands, and any context where you call the API sequentially without concurrency concerns. The asynchronous AsyncUniLink class is the right choice for FastAPI endpoints, async Django views, and any code that uses Python's asyncio event loop — it avoids blocking the event loop during HTTP calls. Both clients expose identical method signatures, so switching between them requires only changing the import and adding await keywords.

The SDK is organized into resource namespaces: client.pages, client.contacts, client.orders, client.products, client.analytics, and client.domains. Each namespace provides list(), get(id), create(data), update(id, data), and delete(id) methods where the API supports them. Method parameters are keyword arguments — no positional argument ambiguity. The list() methods accept filter keyword arguments like status='pending', start_date='2026-01-01', and tag='subscriber' that map directly to the API's query parameters. Return values are Python dicts parsed from the JSON response.

Errors are raised as instances of UniLinkError, a subclass of Exception with status_code and message attributes. Specific subclasses cover common HTTP error conditions: UniLinkAuthError for 401 responses, UniLinkNotFoundError for 404, UniLinkRateLimitError for 429, and UniLinkConflictError for 409. Catching these specific exceptions rather than the base UniLinkError lets you handle each condition appropriately — retry on rate limit, skip on not found, update on conflict — without parsing error messages manually.

How to Get Started

1. Create or activate a Python virtual environment and install the package: pip install unilink. The package requires Python 3.8+ and installs requests as its only mandatory dependency.
2. Generate an API key from Settings → API at app.unilink.us. Set it as an environment variable: export UNILINK_API_KEY="your_key_here" (add to your .env file or shell profile).
3. Initialize the client: import os; from unilink import UniLink; client = UniLink(api_key=os.environ['UNILINK_API_KEY']).
4. Make your first call: pages = client.pages.list(); print(pages['data']). Confirm you see your account's pages returned as a list of dicts.
5. Test a write call if your key has write scope: contact = client.contacts.create(email='test@example.com', tags=['sdk-test']); print(contact['id']). Verify the contact appears in your UniLink dashboard.

How to Use the Python SDK

1. Sync client (scripts and Django/Flask): from unilink import UniLink; client = UniLink(api_key=os.environ['UNILINK_API_KEY']) — use this for all non-async contexts.
2. Async client (FastAPI and asyncio): from unilink import AsyncUniLink; client = AsyncUniLink(api_key=os.environ['UNILINK_API_KEY']); orders = await client.orders.list(status='pending') — identical method names, add await.
3. List with filters: contacts = client.contacts.list(tag='subscriber', start_date='2026-04-01', per_page=100) — all filter parameters are keyword arguments matching the API's query parameter names.
4. Iterate all pages: for contact in client.contacts.iterate(tag='subscriber'): process(contact) — the iterate() method is a generator that yields individual records across all pages automatically.
5. Error handling: from unilink import UniLinkConflictError; try: client.contacts.create(email=email) except UniLinkConflictError as e: client.contacts.update(e.existing_id, tags=[...]) — the UniLinkConflictError exposes the existing resource's ID for immediate update use.

Key Settings

Get the Most Out Of the Python SDK

For Django integrations, place the SDK client initialization in a dedicated services/unilink.py module at the application level. Import this module in your views, serializers, and management commands rather than initializing a new client in each file. This pattern gives you a single place to configure the client — timeout, retry settings, logging — and makes mocking straightforward in tests: patch the services.unilink.client object in your test setup and every code path that imports from that module uses the mock automatically.

The async client pairs naturally with FastAPI. Define a lifespan function that initializes AsyncUniLink at application startup and attaches it to the app state, then inject it as a dependency in your route functions. This avoids creating a new client connection on every request while still making it accessible anywhere in the application. The aiohttp session inside the async client reuses TCP connections across requests, which is a meaningful performance improvement when your API endpoints make multiple UniLink calls per request.

For ETL pipelines, use the SDK's iterate() generator as the source stage of your pipeline and process records in batches to stay memory-efficient. A pattern like collecting 500 records at a time from the generator and writing them to your data warehouse in a batch insert keeps both the UniLink API call rate and the database write overhead manageable. Tune the batch size based on your warehouse's optimal insert size — typically between 100 and 1,000 rows for most cloud data warehouses.

When running scheduled scripts with cron or Celery Beat, add structured logging around SDK calls so you have an audit trail for every automated operation. Log the method called, the filter parameters, the result count, and the execution time. This makes debugging silent failures — a script ran but pulled zero records due to a wrong date filter — straightforward compared to scripts that produce no output on success. The SDK does not emit logs by default; add them at the call site in your script wrapper.

Troubleshooting

• Install with pip install unilink and initialize with UniLink(api_key=os.environ['UNILINK_API_KEY']).
• Use the sync client (UniLink) for scripts and Django/Flask; use the async client (AsyncUniLink) for FastAPI and asyncio applications.
• The iterate() generator handles pagination automatically and keeps memory usage flat for large datasets.
• Catch specific error subclasses (UniLinkAuthError, UniLinkRateLimitError, UniLinkConflictError) for precise error handling logic.
• Initialize the client once at module level — not on every function call — for both performance and testability.