Skip to main content
Use the Python SDK when your application needs Sendmux API clients with API-key validation, retry handling, cursor helpers, and typed API errors.
Sending and Mailbox clients require mailbox-scoped smx_mbx_ keys. Management clients require team-scoped smx_root_ keys.

​
Requirements

  • Python 3.10 or newer.
  • A Sendmux API key for the surface you are calling.

​
Install

Install the umbrella package when one application needs more than one API surface. 
pip install sendmux-sdk

​
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"],
)
Surface packages expose create_sending_client, create_mailbox_client, and create_management_client directly.

​
Choose a surface

SurfacePackageFactoryAPI key
Sendingsendmux-sendingcreate_sending_clientsmx_mbx_
Mailboxsendmux-mailboxcreate_mailbox_clientsmx_mbx_
Managementsendmux-managementcreate_management_clientsmx_root_
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.