inbox-api

Python SDK for the Inbox API — email management for developers.

Installation

pip install inbox-api

Quick Start

Sync

from inbox_api import InboxApiClient

with InboxApiClient("https://api.example.com", "cw_your_token") as client:
    result = client.messages.list("account_id", page_size=5)
    for msg in result.items:
        print(f"{msg.subject} — from {msg.from_email}")

Async

import asyncio
from inbox_api import AsyncInboxApiClient

async def main():
    async with AsyncInboxApiClient("https://api.example.com", "cw_your_token") as client:
        result = await client.messages.list("account_id", page_size=5)
        for msg in result.items:
            print(f"{msg.subject} — from {msg.from_email}")

asyncio.run(main())

Authentication

The SDK authenticates using API tokens prefixed with cw_. Pass your token as the second argument to the client constructor.

client = InboxApiClient("https://api.example.com", "cw_your_token")

Resources

Send an Email

from inbox_api import InboxApiClient
from inbox_api.models.send import SendEmailRequest

with InboxApiClient("https://api.example.com", "cw_your_token") as client:
    client.send.send(SendEmailRequest(
        account_id="account_id",
        to=[{"email": "recipient@example.com"}],
        subject="Hello from Inbox API",
        body_text="Sent via the Python SDK.",
    ))

Search Messages

from inbox_api import InboxApiClient

with InboxApiClient("https://api.example.com", "cw_your_token") as client:
    results = client.search.search("account_id", "invoice")
    for msg in results.items:
        print(f"{msg.subject} — {msg.snippet}")

Pagination

Use iter_all() to automatically paginate through all results:

from inbox_api import InboxApiClient

# Sync — iterate all messages
with InboxApiClient("https://api.example.com", "cw_your_token") as client:
    for msg in client.messages.iter_all("account_id"):
        print(msg.subject)

from inbox_api import AsyncInboxApiClient

# Async — iterate all messages
async with AsyncInboxApiClient("https://api.example.com", "cw_your_token") as client:
    async for msg in client.messages.iter_all("account_id"):
        print(msg.subject)

# Limit to first 5 pages for safety
with InboxApiClient("https://api.example.com", "cw_your_token") as client:
    for msg in client.messages.iter_all("account_id", max_pages=5):
        print(msg.subject)

Available on: client.messages.iter_all(), client.threads.iter_all(), client.contacts.iter_all(), client.search.iter_all().

Error Handling

from inbox_api import InboxApiClient, ApiError, RateLimitError, NotFoundError

with InboxApiClient("https://api.example.com", "cw_your_token") as client:
    try:
        msg = client.messages.get("nonexistent_id")
    except NotFoundError:
        print("Message not found")
    except RateLimitError as e:
        print(f"Rate limited — retry after {e.retry_after}s")
    except ApiError as e:
        print(f"API error {e.status_code}: {e.message}")

Retry Configuration

The SDK automatically retries on 429 (rate limit) and 5xx (server error) responses with exponential backoff.

from inbox_api import InboxApiClient

# Default: 2 retries with exponential backoff
client = InboxApiClient("https://api.example.com", "cw_your_token")

# Disable retries
client = InboxApiClient("https://api.example.com", "cw_your_token", max_retries=0)

# More retries for batch operations
client = InboxApiClient("https://api.example.com", "cw_your_token", max_retries=5)

When a 429 response includes a Retry-After header, the SDK respects it instead of using calculated backoff.

Timeout Configuration

import httpx
from inbox_api import InboxApiClient

# Default: 30s request timeout, 5s connect timeout
client = InboxApiClient("https://api.example.com", "cw_your_token")

# Custom timeout
client = InboxApiClient(
    "https://api.example.com",
    "cw_your_token",
    timeout=httpx.Timeout(60.0, connect=10.0),
)

Advanced

Custom httpx Client

Inject a pre-configured httpx client for full control over transport settings:

import httpx
from inbox_api import InboxApiClient

custom_client = httpx.Client(
    proxy="http://proxy.example.com:8080",
)
client = InboxApiClient(
    "https://api.example.com",
    "cw_your_token",
    http_client=custom_client,
)

When you provide a custom client, the SDK will not close it on context manager exit.

License

MIT