Metadata-Version: 2.4
Name: multimail
Version: 0.1.0
Summary: Python SDK for the MultiMail API — email infrastructure for AI agents
Project-URL: Homepage, https://multimail.dev
Project-URL: Documentation, https://multimail.dev/docs
Project-URL: Repository, https://github.com/multimail-dev/multimail-python
Author-email: David Hanke <david@multimail.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,api,email,mcp,multimail
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Provides-Extra: async
Requires-Dist: httpx[http2]>=0.24.0; extra == 'async'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# multimail

Python SDK for the [MultiMail API](https://multimail.dev) — email infrastructure for AI agents.

## Installation

```bash
pip install multimail
```

## Quick Start

```python
from multimail import MultiMail

mm = MultiMail("mm_live_your_api_key")

# List mailboxes
mailboxes = mm.list_mailboxes()
mailbox_id = mailboxes[0]["id"]

# Send an email
result = mm.send_email(
    mailbox_id,
    to=["recipient@example.com"],
    subject="Hello from my agent",
    markdown="This email was sent by an AI agent using **MultiMail**.",
)
print(result)  # {"id": "...", "status": "pending_scan", "thread_id": "..."}

# Check inbox
emails = mm.list_emails(mailbox_id, direction="inbound")

# Read a specific email
email = mm.get_email(mailbox_id, emails["emails"][0]["id"])
print(email["subject"], email["text_body"])
```

## Async Support

```python
from multimail import AsyncMultiMail

async with AsyncMultiMail("mm_live_your_api_key") as mm:
    mailboxes = await mm.list_mailboxes()
    result = await mm.send_email(
        mailboxes[0]["id"],
        to=["recipient@example.com"],
        subject="Async email",
        markdown="Sent asynchronously!",
    )
```

## Oversight & Approval

MultiMail supports graduated oversight modes. When a mailbox uses `gated_send`, emails require human approval:

```python
# List emails waiting for approval
pending = mm.list_pending()

# Approve or reject
mm.decide(pending[0]["id"], "approve")
mm.decide(pending[1]["id"], "reject", reason="Not relevant")
```

## All Methods

### Account
- `get_account()` / `update_account(**fields)` / `delete_account()`

### Mailboxes
- `list_mailboxes()` / `create_mailbox(address, display_name, oversight_mode=...)` / `update_mailbox(id, **fields)` / `delete_mailbox(id)`

### Emails
- `list_emails(mailbox_id)` / `get_email(mailbox_id, email_id)` / `send_email(mailbox_id, to=, subject=, markdown=)` / `reply_email(mailbox_id, email_id, markdown=)` / `cancel_email(mailbox_id, email_id)` / `get_thread(mailbox_id, thread_id)` / `download_attachment(mailbox_id, email_id, filename)`

### Tags
- `get_tags(mailbox_id, email_id)` / `set_tags(mailbox_id, email_id, tags)` / `delete_tag(mailbox_id, email_id, key)`

### Contacts
- `list_contacts(q=)` / `add_contact(email, name=)` / `delete_contact(contact_id)`

### Oversight
- `list_pending()` / `decide(email_id, action, reason=)`

### API Keys
- `list_api_keys()` / `create_api_key(name, scopes=)` / `revoke_api_key(key_id)`

### Webhooks
- `list_webhooks()` / `create_webhook(url, events, secret=)` / `delete_webhook(webhook_id)`

### Domains
- `list_domains()` / `add_domain(domain)` / `verify_domain(domain_id)` / `delete_domain(domain_id)`

### Suppression
- `list_suppressions()` / `remove_suppression(address)`

### Usage & Audit
- `get_usage()` / `get_audit_log(limit=)`

## Error Handling

```python
from multimail import MultiMail, AuthenticationError, RateLimitError

mm = MultiMail("mm_live_your_api_key")
try:
    mm.send_email(mailbox_id, to=["test@example.com"], subject="Hi", markdown="Hello")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
```

## Links

- [MultiMail](https://multimail.dev) — Homepage
- [API Docs](https://multimail.dev/docs) — Full API reference
- [MCP Server](https://www.npmjs.com/package/@multimail/mcp-server) — For Claude, Cursor, and other MCP clients
