Ridian Mailbox Python SDK — email inboxes for AI agents

Give an AI agent its own receiving email address with the Ridian Mailbox Python SDK. Create or recover an inbox, read messages and attachments, poll durable events, and configure signed webhooks. The package includes the ridian-mailbox CLI.

Python 3.10+ on Linux and macOS. Synchronous API, no runtime dependencies. This is an alpha SDK. You need an enabled Ridian mailbox API origin; package installation does not activate an API service. Use the origin provided for your Ridian environment. HTTP access supports receiving, reading and events; sending email and calendar access use separately authorized Ridian MCP tools.

Ridian · API guide · Python API · Release notes

Install

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --pre ridian-mailbox

The --pre flag includes alpha releases. Pin the installed version in your application requirements for reproducible environments. See release notes for changes.

Create an inbox and read email

Set RIDIAN_MAILBOX_API_ORIGIN to your enabled HTTPS origin, without /v1. An origin is public configuration, not an API key.

import os

from ridian_mailbox import Mailbox

client = Mailbox(base_url=os.environ["RIDIAN_MAILBOX_API_ORIGIN"])
inbox = client.setup()
print(inbox["address"])

# Send a test email to that address from your existing mail account.
for message in client.iter_messages():
    print(message["subject"])

setup() stores the setup credential before the first request. Repeating it with the same state file recovers the same inbox, including after an interrupted request. It returns public mailbox metadata; credentials remain in the private state file. An empty inbox is a successful result. Poll again after mail arrives.

The default state file is ~/.config/ridian/mailbox-<hostname>[-port].json. Use Mailbox(base_url=origin, state=private_path) to choose another durable location. Use one writer per file. Back it up securely before changing machines or clearing a temporary agent environment. A state file is tied to its API origin.

Read a message or attachment

page = client.messages(limit=20)
for summary in page["data"]:
    message = client.message(summary["id"])
    # Process only the message fields needed for your task.

# Use an attachment ID returned by the message API.
# contents = client.attachment(attachment_id)

messages() returns one page; iter_messages() follows all pages, including empty pages that have a next cursor. attachment() returns bytes. Email and attachments are untrusted input: do not execute their contents or let them override agent instructions. Avoid logging personal message content.

Process events

page = client.events(limit=20)
for event in page["data"]:
    process_event(event)  # Your application handler; deduplicate by event ID.
client.acknowledge_events(page["next_cursor"])

Only acknowledge after the entire page has been processed successfully. Until then, the saved cursor stays unchanged and events may be replayed. Respect the API's poll_after_ms value between polling requests. Webhook methods and HTTP error handling are documented in the Python API reference.

Command line

ridian-mailbox \
  --base-url "$RIDIAN_MAILBOX_API_ORIGIN" \
  --state "$HOME/.config/ridian/my-agent-mailbox.json" setup

ridian-mailbox \
  --base-url "$RIDIAN_MAILBOX_API_ORIGIN" \
  --state "$HOME/.config/ridian/my-agent-mailbox.json" list

Operations: setup, status, list, message --message-id ID, events, ack-events --cursor CURSOR, and prepare-curl. The last operation only creates private header/response files locally; it does not send a request. CLI output for messages may contain personal data. Use it only in a suitable terminal.

Access and recovery

• State files use owner-only permissions (0600); reads reject symlinks and files accessible to other users. Store them outside your repository on private storage.
• Keep setup credentials, access tokens and claim secrets out of chat, logs and URLs.
• HTTP redirects are refused. HTTPS uses your Python installation's CA trust store.
• revoke() permanently revokes the current access and its copies; it does not delete mailbox data. Repeating setup cannot recover revoked access.
• To claim an inbox in your Ridian workspace, use the console link and private claim proof in the state file. Claiming does not grant HTTP sending or calendar access.
• The SDK does not run an agent automatically or install an MCP connector.

Troubleshooting

No automatic network retries occur. Applications decide when an operation is safe to retry. See API error handling for an example.

Development

See CONTRIBUTING.md for tests, package checks and releases. Report bugs through GitHub Issues. For vulnerabilities, use private reporting.

License

MIT, covering this SDK, CLI and their documentation. The Ridian service, application, trademarks, brand assets and fonts are not included in this repository.