Omnifox Python SDK: sync and async clients

How to install the omnifox package, create the Omnifox and AsyncOmnifox clients, and the differences you need to know when using the async one.

Aug 19, 2026

Watch this step in the video · Official SDKs: Node, Python and PHP

The Omnifox Python SDK is published on PyPI as omnifox. It ships two clients with the same surface: Omnifox (sync) and AsyncOmnifox (async). It requires Python 3.9 or higher and depends on httpx and pydantic.

Installation

pip install omnifox

Sync client

from omnifox import Omnifox

client = Omnifox("your-token-here", workspace_id=1)

contact = client.contacts.get("email:[email protected]")

client.messages.send(
    contact="id:42",
    channel_id=5,
    text="Hello from the Omnifox SDK",
)

for c in client.contacts.list(pagination="cursor"):
    print(c.id, c.display_name)

client.close()

It also works as a context manager: with Omnifox("...") as client:.

Async client

import asyncio
from omnifox import AsyncOmnifox

async def main() -> None:
    async with AsyncOmnifox("your-token-here", workspace_id=1) as client:
        async for contact in client.contacts.list(pagination="cursor"):
            print(contact.id, contact.email)

        await client.messages.send(
            contact="phone:+593987654321",
            whatsapp_template={"name": "welcome_v2", "language": "es"},
        )

asyncio.run(main())

If you don't use async with, close the client with await client.aclose().

Constructor parameters

api_key is positional and required; everything else is keyword-only.

Parameter Default Notes
api_key — Positional. Empty raises ValueError("api_key is required").
workspace_id None Numeric workspace id.
base_url https://app.omnifox.io/api/v1 Test environments only.
timeout 30.0 In seconds (unlike the Node SDK, which uses milliseconds).
max_retries 3 Retries on 429, 500, 502, 503, 504, and connection errors.
backoff_base 0.5 Initial wait between retries, in seconds.
backoff_max 30.0 Cap on the wait between retries.
user_agent — User-Agent header.
default_headers None Extra headers on every call.
http_client None Your own httpx.Client or httpx.AsyncClient. If you pass it, the SDK does not close it.

The SDK does not read environment variables: the key is always passed explicitly.

The async detail that confuses people most

Not every list() is awaited the same way:

  • Paginated lists (contacts, conversations, messages, channels, broadcasts, custom fields, tags, quick replies, webhooks, workflows, users, workspaces, teams, companies, deals, and CRM activities) return an iterator. You walk them with async for, with no await.
  • Non-paginated lists (pipelines.list(), boards.list(), appointments.list(), products.list(), orders.list(), quotes.list()) return a list and do take await.
  • Everything else (get, create, send, …) takes await.

Workspace required in four calls

Four endpoints require the workspace id inside the body, even when the token is already pinned to one. In the Python SDK they are:

  • client.users.update_status()
  • client.teams.create()
  • client.channels.connect()
  • client.broadcasts.create()

If you didn't pass workspace_id to the constructor, those methods raise a local ValueError before hitting the network.

Verification

print(client.users.me())

If something doesn't work

  • ValueError: api_key is required: the key arrived empty.
  • TypeError when calling a method: check the keyword parameter names; they differ from the Node SDK's.
  • An unwrapped httpx.ConnectError or httpx.ReadTimeout: the retries ran out. The SDK does not convert those network exceptions into its own errors.
  • ValueError when requesting a report: the preset is not valid. The accepted ones are today, yesterday, 7d, 30d, 90d, this_month, and last_month.

Tips

  • The start-date parameter for reports is called from_, with an underscore, because from is a reserved word in Python.
  • To merge contacts, the exact names are primary_contact_id and merged_contact_id, both numeric and keyword-only.
  • To trigger a workflow, the real signature is trigger(workflow_id, context={...}, force=False).

Related articles

Was this helpful?

Related articles

Message us on WhatsApp