Metadata-Version: 2.4
Name: agentmail-to
Version: 0.1.0
Summary: Official AgentMail Python SDK — API-first email inbox for AI agents
Author-email: AgentMail Team <team@agentmail.to>
License: MIT
Project-URL: Homepage, https://agentmail.to
Project-URL: Documentation, https://docs.agentmail.to
Project-URL: Repository, https://github.com/agentmail-to/agentmail-python
Project-URL: Changelog, https://docs.agentmail.to/changelog
Keywords: email,ai-agent,webhook,inbox,smtp,api
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
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0
Provides-Extra: async
Requires-Dist: httpx[asyncio]>=0.27.0; extra == "async"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"

# AgentMail Python SDK

[![PyPI version](https://badge.fury.io/py/agentmail.svg)](https://pypi.org/project/agentmail/)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://pypi.org/project/agentmail/)

The official Python client library for [AgentMail](https://agentmail.to) — the email inbox API built for AI agents.

## Installation

```bash
pip install agentmail
```

With async support:

```bash
pip install agentmail[async]
```

## Quickstart

```python
from agentmail import AgentMail

client = AgentMail(api_key="am_live_...")

# Create an inbox for your agent
inbox = client.inboxes.create(username="my-agent")

# Send an email
message = client.send.send(
    inbox_id=inbox.id,
    to=["user@example.com"],
    subject="Your OTP Code",
    body_text="Your verification code is 847291.",
)

# Wait for a reply with a matching OTP
reply = client.inboxes.wait_for_message(
    inbox.id,
    timeout=60,
    from_addr="user@example.com",
)
print(f"OTP received: {reply.extracted_otp}")
```

## Key Features

- **Auto-retry** on rate limits (429) and server errors (5xx) — exponential backoff, max 3 attempts
- **Pagination** via cursor — `client.inboxes.list()` returns an iterator
- **Typed models** — all API objects are Pydantic v2 models with full type hints
- **`py.typed`** marker — compatible with mypy and pyright
- **Context manager** — `with AgentMail(api_key="...") as client:`

## Resource Namespaces

| Namespace | Key Methods |
|-----------|-------------|
| `client.inboxes` | `.create()`, `.get()`, `.list()`, `.update()`, `.delete()`, `.wait_for_message()` |
| `client.messages` | `.get()`, `.list()`, `.search()`, `.mark_read()`, `.mark_unread()`, `.reply()`, `.forward()` |
| `client.threads` | `.get()`, `.list()` |
| `client.webhooks` | `.create()`, `.get()`, `.list()`, `.delete()`, `.rotate_secret()` |
| `client.drafts` | `.create()`, `.get()`, `.list()`, `.update()`, `.delete()`, `.send()` |
| `client.labels` | `.create()`, `.get()`, `.list()`, `.add()`, `.remove()`, `.delete()` |
| `client.send` | `.send()` |
| `client.account` | `.get()`, `.stats()`, `.keys()` |
| `client.analytics` | `.volume()`, `.bounce_rate()` |
| `client.quarantine` | `.list()`, `.release()`, `.delete()` |
| `client.suppression` | `.list()`, `.add()`, `.remove()`, `.get()` |
| `client.attachments` | `.get()`, `.info()` |
| `client.keys` | `.list()`, `.create()`, `.revoke()` |

## Error Handling

```python
from agentmail import AgentMail, AgentMailError, RateLimitError, NotFoundError

try:
    inbox = client.inboxes.get("invalid-id")
except NotFoundError as e:
    print(f"Inbox not found: {e.message}")
except RateLimitError as e:
    print(f"Rate limited — retry after: {e.message}")
except AgentMailError as e:
    print(f"API error [{e.error_code}]: {e.message}")
```

## Examples

### OTP Verification Flow

```python
from agentmail import AgentMail

client = AgentMail(api_key="am_live_...")

# Create agent inbox
inbox = client.inboxes.create(username="otp-bot")

# Wait for email containing OTP (blocks up to 60s)
message = client.inboxes.wait_for_message(
    inbox.id,
    timeout=60,
    subject="Your verification code",
)
otp = message.extracted_otp
print(f"OTP: {otp}")  # e.g. "482917"
```

### Multi-Agent Inbox Provisioning

```python
# Bulk create inboxes for a team of agents
agent_names = ["sales-agent", "support-agent", "billing-agent"]
for name in agent_names:
    inbox = client.inboxes.create(username=name, agent_name=name)
    print(f"Created: {inbox.address}")
```

### Webhook Registration + Delivery Log

```python
import os

# Register a webhook for all message events
webhook = client.webhooks.create(
    url="https://my-agent.example.com/webhook",
    events=["message.received", "message.sent"],
)

# Inspect recent webhook deliveries
deliveries = client.webhooks.delivery_log(webhook.id)
for d in deliveries:
    print(f"{d['event']}: {d['status_code']} at {d['createdAt']}")
```

## Configuration

```python
client = AgentMail(
    api_key="am_live_...",
    base_url="https://api.agentmail.to",  # optional, for testing
    timeout=30.0,                          # request timeout (default 30s)
    max_retries=3,                         # auto-retry attempts (default 3)
    debug=True,                            # log requests/responses
)
```

## License

MIT © AgentMail Team
