Python SDK

Use the Python SDK when your application needs Sendmux API clients with API-key validation, retry handling, cursor helpers, and typed API errors.

For API-key authentication, Sending clients accept a send-capable smx_mbx_ key or owner-approved Sending-resource smx_agent_ token. Mailbox clients accept smx_mbx_ keys or scoped smx_agent_ tokens. Management API-key clients require team-scoped smx_root_ keys.

Requirements

Python 3.10 or newer.
An API key or REST OAuth grant for the surface you are calling.

Install

Install the umbrella package when one application needs more than one API surface.

pip install sendmux-sdk

pip install sendmux-sending

pip install sendmux-mailbox

pip install sendmux-management

OAuth access tokens

Set access_token to a bare token string or callable. Do not also set api_key.

import os
from sendmux_mailbox import create_mailbox_client

client = create_mailbox_client(
    access_token=lambda: os.environ["SENDMUX_ACCESS_TOKEN"],
)

The provider runs before each request. Your application owns secure token storage, expiry checks, and refresh coordination; see OAuth for REST APIs. The same token option is available for Sending and Management clients. The langchain-sendmux wrapper accepts the same access_token option in SendmuxToolkit(...). To use all three tools, request mailbox.read and email.send and select one mailbox at consent; the tools do not supply a mailbox selector.

Create a client

The umbrella package lazy-loads sending, mailbox, and management modules.

import os
from sendmux_sdk import sending

client = sending.create_sending_client(
    api_key=os.environ["SENDMUX_MAILBOX_API_KEY"],
)

import os
from sendmux_sdk import mailbox

client = mailbox.create_mailbox_client(
    api_key=os.environ["SENDMUX_MAILBOX_API_KEY"],
)

import os
from sendmux_sdk import management

client = management.create_management_client(
    api_key=os.environ["SENDMUX_ROOT_API_KEY"],
)

Surface packages expose create_sending_client, create_mailbox_client, and create_management_client directly.

Choose a surface

Surface	Package	Factory	API key
Sending	`sendmux-sending`	`create_sending_client`	`smx_mbx_` or owner-approved `smx_agent_` with `email.send`
Mailbox	`sendmux-mailbox`	`create_mailbox_client`	`smx_mbx_` or scoped `smx_agent_`
Management	`sendmux-management`	`create_management_client`	`smx_root_`

Durable smx_agent_ tokens are mailbox-compatible and include mailbox.read and email.receive, not email.send. After owner acceptance and approval, exchange the durable token for a one-hour Sending-resource token before sending.

Sending uses https://smtp.sendmux.ai/api/v1 by default. Mailbox and Management use https://app.sendmux.ai/api/v1.

Shared API behaviour

The surface factories validate API key prefixes, attach bearer auth, and wrap generated API errors.

Pagination

List responses use cursor pagination with pagination.has_more and pagination.next_cursor. The core package exports iter_cursor_pages() for cursor iteration when you wrap a page-fetching function.

Retries and rate limits

Surface clients use a retrying request client. It retries safe methods and retry-safe POST requests that include Idempotency-Key, then honours Retry-After and X-RateLimit-Reset response headers. Pass RetryOptions into a client factory to change attempts, delays, or sleep behaviour.

Idempotency and ETags

Use core header helpers when a generated operation accepts custom headers.

from sendmux_core import conditional_headers, idempotency_headers

headers = {
    **idempotency_headers("order-123"),
    **conditional_headers(if_match=etag),
}

Use Idempotency-Key for retry-safe mutating requests. Use If-Match and If-None-Match with single-resource endpoints that support ETags.

Errors

Generated client exceptions are mapped to SendmuxApiError. The error carries the API error code, retryability, request ID, status, headers, and raw body when available. Use error.retryable and error.request_id when deciding whether to retry or contact support.

Next steps

SDK overview

Choose the right package family and API surface.

Versioning and support

Check compatibility, support, and upgrade guidance.

Mailbox API

Review the Mailbox API contract used by sendmux-mailbox.

API keys

Create and scope the credentials used by SDK clients.

Getting started

Developer tools

AI integrations

Sending

Receiving

Domains

Monitoring

Webhooks

Use cases

Integrations

Account and billing

Requirements

Install

OAuth access tokens

Create a client

Choose a surface

Shared API behaviour

Retries and rate limits

Idempotency and ETags

Errors

Next steps

SDK overview

Versioning and support

Mailbox API

API keys

​Requirements

​Install

​OAuth access tokens

​Create a client

​Choose a surface

​Shared API behaviour

​Pagination

​Retries and rate limits

​Idempotency and ETags

​Errors

​Next steps

SDK overview

Versioning and support

Mailbox API

API keys

Requirements

Install

OAuth access tokens

Create a client

Choose a surface

Shared API behaviour

Pagination

Retries and rate limits

Idempotency and ETags

Errors

Next steps