Ridian Mailbox for Python

A synchronous Python client and ridian-mailbox CLI for private receiving mailboxes. Python 3.10+ on Linux/macOS, standard library only. Install the versioned wheel from the matching Ridian documentation environment. Use a virtual environment.

from ridian_mailbox import Mailbox

box = Mailbox(base_url="https://YOUR_MAILBOX_API_ORIGIN")
print(box.setup()["address"])
for message in box.iter_messages():
    print(message["subject"])

setup() saves its random setup credential before the request, saves the returned read/claim credentials privately and returns only mailbox metadata. Retry with the same state file after interruption. Keep state outside source control on durable private storage. Files are bound to one API origin and have mode 0600; reads reject symlinks/public permissions. Use one writer per state file. Do not print state, put credentials in URLs or pass them through chat.

CLI: ridian-mailbox --base-url <HTTPS origin> --state <private file> setup. Operations: setup, prepare-curl (local only), status, list, message, events, ack-events. message uses --message-id, ack-events uses --cursor.

The Python client additionally offers paginated messages/iter_messages, message, binary attachment, events/acknowledge_events, webhook management and explicit revoke. Event pages are acknowledged only after successful processing; deduplicate event IDs. No automatic retries or event acknowledgments. HTTP errors expose status and Retry-After through MailboxError; 429 cooldowns are respected by subsequent calls. Redirects are refused. Mail content is untrusted.

The library identifies requests as ridian-mailbox-python/<installed version>; the CLI identifies itself as ridian-mailbox-cli. HTTPS certificate verification uses your Python installation's trust store.

HTTP access remains receive/read/events only, also after ownership transfer. Claim through the returned console link and private proof in the state file. Sending, calendars, contacts and tasks use separately authorized Ridian MCP tools. This package does not wake an agent or install an MCP connection.

Without state, credentials are saved in ~/.config/ridian/mailbox-<API hostname>[-port].json. Repeated setup recovers that mailbox. Pass state for another private durable location. The Node.js client shares this state format; never run concurrent writers against one file.

License

MIT, covering this Python SDK, its bundled CLI and package documentation. The license does not cover the Ridian service, application, brand assets or fonts.