Python SDK Overview

Server-side only — This SDK is designed for server-side environments (Python servers, serverless functions). Never use it in browser/frontend code as this exposes your API key. See Frontend Integration for the proxy pattern.

Coverage. The Python SDK does not generate invitations, URL verification, sub-accounts, balance, account, functions and 10DLC yet, and no SDK generates voice calls. Those endpoints are still reachable: use the CLI or the REST API. See the coverage table.

The official Zavu SDK for Python provides a clean, Pythonic interface to the Zavu API with full type hints.

Installation

pip install zavudev
# or
uv add zavudev
# or
poetry add zavudev

Requirements

Python 3.9 or higher

Quick Start

import os
from zavudev import Zavudev

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),
)

result = zavu.messages.send(
    to="+14155551234",
    text="Hello from Zavu!"
)

print(f"Message sent: {result.message.id}")

Configuration

Initialize the Client

from zavudev import Zavudev

# Basic initialization
zavu = Zavudev(
    api_key="zv_live_xxx",
)

# With custom base URL
zavu = Zavudev(
    api_key="zv_live_xxx",
    base_url="https://api.zavu.dev"
)

Environment Variables

We recommend storing your API key in environment variables:

import os
from zavudev import Zavudev

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),
)

Accessing Response Headers

Use .with_raw_response() to access the full HTTP response including headers:

response = zavu.messages.send.with_raw_response(
    to="+14155551234",
    text="Hello!"
)

remaining = response.headers.get("X-RateLimit-Remaining")
print(f"Remaining requests: {remaining}")

result = response.parse()
print(f"Message ID: {result.message.id}")

Error Handling

from zavudev import Zavudev, ZavudevError, APIError

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),
)

try:
    zavu.messages.send(to="invalid-number", text="Hello")
except APIError as e:
    print(f"Status: {e.status_code}")
    print(f"Message: {e.message}")
except ZavudevError as e:
    print(f"Error: {e.message}")

Exception Types

Exception	Description
`ZavudevError`	Base exception class
`APIError`	API error with status code

Async Support

The SDK supports async/await with asyncio:

import asyncio
import os
from zavudev import AsyncZavudev

async def main():
    zavu = AsyncZavudev(
        api_key=os.environ.get("ZAVUDEV_API_KEY"),
    )

    result = await zavu.messages.send(
        to="+14155551234",
        text="Hello async!"
    )

    print(f"Message sent: {result.message.id}")

asyncio.run(main())

Retries

The SDK supports automatic retries with configurable backoff:

from zavudev import Zavudev

zavu = Zavudev(
    api_key="zv_live_xxx",
    max_retries=3,
)

result = zavu.messages.send(
    to="+14155551234",
    text="Hello!"
)

Type Hints

The SDK includes full type annotations:

from zavudev import Zavudev
from zavudev.types import Message

zavu = Zavudev(
    api_key=os.environ.get("ZAVUDEV_API_KEY"),
)

result = zavu.messages.send(
    to="+14155551234",
    text="Hello!"
)

message: Message = result.message

Debugging

Enable debug logging:

import logging
from zavudev import Zavudev

logging.basicConfig(level=logging.DEBUG)

zavu = Zavudev(
    api_key="zv_live_xxx",
)

​Installation

​Requirements

​Quick Start

​Configuration

​Initialize the Client

​Environment Variables

​Accessing Response Headers

​Error Handling

​Exception Types

​Async Support

​Retries

​Type Hints

​Debugging

Installation

Requirements

Quick Start

Configuration

Initialize the Client

Environment Variables

Accessing Response Headers

Error Handling

Exception Types

Async Support

Retries

Type Hints

Debugging