Metadata-Version: 2.4
Name: deaddropzone
Version: 0.2.0
Summary: Python SDK for DeadDrop — receive-only email inboxes for AI agents
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Description-Content-Type: text/markdown

# DeadDrop Python SDK

Python client for the [DeadDrop API](https://deaddrop.zone) — programmable email inboxes for the agentic era.

## Install

```bash
pip install deaddropzone
```

The distribution name is `deaddropzone` (the `deaddrop` name on PyPI is taken), but the import name is still `deaddrop`:

```python
from deaddrop import DeadDrop
```

## Quick start

```python
from deaddrop import DeadDrop

dd = DeadDrop(api_key="dd_live_...")

# Create an inbox
inbox = dd.create_inbox(slug="my-signup-test")
print(f"Send email to: {inbox.address}")

# Wait for an OTP (blocks until one arrives or timeout)
otp = dd.wait_for_otp(inbox.id, timeout=60)
print(f"Got OTP: {otp.value}")

# Wait for a verification link
link = dd.wait_for_link(inbox.id, "verification", timeout=60)
print(f"Verify at: {link.url}")
```

## Ephemeral inboxes (no auth)

```python
from deaddrop import DeadDrop

dd = DeadDrop()  # no API key needed
inbox = dd.create_ephemeral_inbox()
# inbox expires in 1 hour
```

## Configuration

| Parameter  | Env var            | Default                     |
| ---------- | ------------------ | --------------------------- |
| `api_key`  | `DEADDROP_API_KEY` | —                           |
| `base_url` | `DEADDROP_API_URL` | `https://api.deaddrop.zone` |

## Convenience methods

The SDK provides high-level methods that compose the long-poll wait endpoint with extraction:

- **`wait_for_message(inbox_id, ...)`** — Block until a message arrives matching filters.
- **`wait_for_otp(inbox_id, ...)`** — Wait for a message with an OTP, return the highest-confidence match.
- **`wait_for_link(inbox_id, link_type, ...)`** — Wait for a message with a specific link type.

All accept optional `timeout`, `after`, `subject_contains`, and `from_contains` filters.

## Inbox pools

```python
pool = dd.create_pool("ci-tests", target_size=5)
inbox = dd.checkout_inbox(pool.id)
# ... use inbox ...
dd.return_inbox(pool.id, inbox.id)
```

## Error handling

```python
from deaddrop import DeadDrop, DeadDropError
from deaddrop.errors import TimeoutError

dd = DeadDrop(api_key="dd_live_...")

try:
    otp = dd.wait_for_otp(inbox_id, timeout=10)
except TimeoutError:
    print("No OTP arrived in time")
except DeadDropError as e:
    print(f"API error: {e.code} — {e.message}")
```

## License

MIT
