sendmux-mailbox

Generated Python client for the Sendmux Mailbox API.

Documentation

• Mailbox API reference: sendmux.ai/docs/mailbox-api/introduction
• Source repository: Sendmux/sendmux-sdk

Requirements

• Python 3.10 or newer.
• A mailbox-scoped smx_mbx_* key or scoped smx_agent_* token.

For OAuth, use a REST access token with the scopes and mailbox access required by the operation. See OAuth for REST APIs.

Installation

pip install sendmux-mailbox

OAuth access tokens

Pass either api_key or access_token. access_token accepts a bare token string or a synchronous callable; the callable is evaluated for each authenticated request. Your application owns token storage, expiry checks and refresh coordination.

import os

from sendmux_mailbox import create_mailbox_client

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

Usage

import os

from sendmux_mailbox import MailboxAPIApi, create_mailbox_client, iter_mailbox_events

client = create_mailbox_client(api_key=os.environ["SENDMUX_MAILBOX_API_KEY"])
api = MailboxAPIApi(client)

messages = api.mailbox_list_messages(limit=25)

for message in messages.data:
    print(message.id, message.subject)

The package exports every generated Mailbox model and API class plus:

• create_mailbox_client
• configure_mailbox
• SendmuxMailboxApiClient
• iter_mailbox_events
• file helpers: upload_mailbox_attachment_from_file, create_mailbox_attachment_upload_from_file, upload_mailbox_attachment_via_presigned_file, and send_mailbox_message_with_files

Connection checks

Check the current credential before choosing a mailbox:

with create_mailbox_client(api_key=os.environ["SENDMUX_MAILBOX_API_KEY"]) as client:
    connection = MailboxAPIApi(client).mailbox_get_connection()
    print(connection.data.label)

The result includes team and credential details, permissions and authorised mailboxes.

Attachments

Message and event attachment metadata includes download_url, a short-lived presigned URL for that single attachment. Prefer download_mailbox_attachment() or read_mailbox_text_attachment() when you already have an authenticated client. Plain HTTP clients can fetch download_url promptly with no Authorization header; if it expires, call mailbox_get_message() or list/search messages again to receive fresh metadata.

Mailbox direct uploads, presigned uploads, and file helpers share the mailbox attachment cap, currently 7,500,000 bytes per attachment. Presigned uploads also pin the exact declared byte length and content type.

import os
import urllib.request

from sendmux_mailbox import MailboxAPIApi, create_mailbox_client, read_mailbox_text_attachment

client = create_mailbox_client(api_key=os.environ["SENDMUX_MAILBOX_API_KEY"])
api = MailboxAPIApi(client)

message = api.mailbox_get_message("msg_123")
attachment = message.data.attachments[0]
content = urllib.request.urlopen(attachment.download_url, timeout=30).read()
text = read_mailbox_text_attachment(
    client,
    message_id="msg_123",
    attachment_id=attachment.id,
)

upload = api.mailbox_upload_attachment(
    body=b"hello\n",
    filename="hello.txt",
    _headers={"Content-Type": "text/plain"},
)

api.mailbox_send_message(
    send_mailbox_message_body={
        "to": [{"email": "recipient@example.com", "name": None}],
        "subject": "Attachment",
        "text_body": "See attached.",
        "attachments": [{
            "blob_id": upload.data.blob_id,
            "filename": "hello.txt",
            "content_type": "text/plain",
        }],
    },
)

For local files, use helper functions so file bytes stay out of model context:

import os

from sendmux_mailbox import create_mailbox_client, send_mailbox_message_with_files

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

send_mailbox_message_with_files(
    client,
    files=["./report.pdf"],
    idempotency_key="report-123",
    body={
        "to": [{"email": "recipient@example.com", "name": None}],
        "subject": "Report",
        "text_body": "Attached.",
    },
)

Use upload_mailbox_attachment_via_presigned_file(...) when you want the upload step to use the short-lived signed URL and no API key on the file PUT. Inline base64 attachments remain available for tiny generated sends through the generated attachments[].content body shape.

Events

Use iter_mailbox_events for typed server-sent mailbox events.

for event in iter_mailbox_events(
    client,
    close_after=300,
    event_types="message.received",
):
    print(event.event_type, event.message_id)

Pagination

Use iter_cursor_pages from sendmux-core with list operations that return cursor pagination.

import os

from sendmux_core import iter_cursor_pages
from sendmux_mailbox import MailboxAPIApi, create_mailbox_client

client = create_mailbox_client(api_key=os.environ["SENDMUX_MAILBOX_API_KEY"])
api = MailboxAPIApi(client)

for message in iter_cursor_pages(lambda cursor: api.mailbox_list_messages(cursor=cursor, limit=50)):
    print(message.id)

Migrate from 1.x to 2.0

If you annotate or construct thread-message list results (fixtures, mocks, or wrappers typed with the operation's result model), add the thread identity when upgrading to 2.0. mailbox_list_thread_messages returns MailboxThreadMessageSummaryCursorListResponse instead of MailboxMessageSummaryCursorListResponse: its meta is MailboxThreadMessagesMeta, whose thread_id is required and whose sync_state is an optional string. Code that only reads thread-message results keeps working.

1. Update thread-message annotations and type checks to the thread-specific result model:

   from sendmux_mailbox import MailboxThreadMessageSummaryCursorListResponse
   
   # Before: isinstance(response, MailboxMessageSummaryCursorListResponse)
   def is_thread_message_list(response: object) -> bool:
       return isinstance(response, MailboxThreadMessageSummaryCursorListResponse)
   

2. Add the thread identity to every thread-message result you construct:

   from sendmux_mailbox import MailboxThreadMessageSummaryCursorListResponse
   
   # Before: "meta": {"request_id": "req_fixture"}
   fixture = MailboxThreadMessageSummaryCursorListResponse.model_validate(
       {
           "ok": True,
           "meta": {"request_id": "req_fixture", "thread_id": "thr_1"},
           "data": [],
           "pagination": {"has_more": False},
       }
   )
   

   Ordinary mailbox_list_messages results remain MailboxMessageSummaryCursorListResponse: they have no thread identity and their meta is MailboxSyncMeta with an optional sync_state. Identity, submission, quota, and thread list responses likewise carry MailboxIdentityListMeta or MailboxQueryMeta with optional identity_state or query_state; no new field is required there.

3. Run your tests and mypy. A constructed thread-message result without thread_id fails validation with meta.thread_id Field required.

MailboxRealtimeMessage.body is a MailboxRealtimeMessageBody. The earlier generated name, MailboxRealtimeMessageAllOfBody, remains importable from sendmux_mailbox and sendmux_mailbox.models as a deprecated alias of that class: reading it emits a DeprecationWarning, and the alias is removed in 3.0. Switch imports to MailboxRealtimeMessageBody.

Update sendmux-mailbox, its lockfile, and affected annotations or fixtures together. To roll back, restore those package, lockfile, and call-site changes together.

Support

Open an issue in Sendmux/sendmux-sdk with the package name, version, and request ID from any API error.

Licence

MIT. See the licence file.