Metadata-Version: 2.4
Name: ridian-mailbox
Version: 0.1.0a3
Summary: Private Ridian mailbox access for Python agents and the command line
Author: Ridian
License-Expression: MIT
Project-URL: Homepage, https://getridian.com
Project-URL: Documentation, https://docs.getridian.com/agent-mailbox/
Keywords: ridian,email,mailbox,agents,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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.

```python
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.
