Metadata-Version: 2.4
Name: finemail-sdk
Version: 0.2.0
Summary: Dependency-free Python SDK for the FineMail agent mailbox API.
Project-URL: Homepage, https://finemail.app
Project-URL: Documentation, https://finemail.app/sdk/README.md
Author: Fine Structure
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agent,email,fine-structure,finemail,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# FineMail Python SDK

Dependency-free Python client for FineMail's authenticated REST tool bridge. Python 3.9 or newer is required.

```bash
pip install https://finemail.app/sdk/finemail_sdk-0.2.0-py3-none-any.whl
```

```python
import os
from finemail_sdk import FineMailClient

client = FineMailClient(os.environ["FINEMAIL_MCP_TOKEN"])
inboxes = client.list_inboxes()
messages = client.list_messages(folder="unread", limit=20)
print({"inboxes": inboxes, "messages": messages})
```

The client exposes the complete FineMail platform as Python methods:

- inbox lifecycle and meaningful address management
- message list/search, rich text/HTML, CC/BCC, attachments, labels and deletion
- RFC-threaded conversations, reply, reply-all and forward
- drafts, scheduled send and cancellation
- real-time `wait_for_email`, signed webhooks and attachment access
- custom domains, security allow/block rules, usage and configuration

Every call uses `POST https://finemail.app/api/mcp/tools/{tool}`. Configure a scoped MCP token beginning with `fse2_mcp_` in a secret store or environment variable. MCP clients may alternatively use FineMail's OAuth 2.1 PKCE flow. Never put a token in source code, browser bundles, logs, or version control.

The default request timeout is 30 seconds. Use `FineMailClient(..., timeout=10)` or pass `timeout=5` to one method. `FineMailError` includes safe `status`, `code`, and `details` fields and never includes the bearer token in its message.
