Metadata-Version: 2.4
Name: plop-sdk
Version: 0.1.0
Summary: Plop Python SDK — receive and poll for emails in your tests and applications
Project-URL: Homepage, https://github.com/plop-email/plop-python
Project-URL: Repository, https://github.com/plop-email/plop-python
Project-URL: Issues, https://github.com/plop-email/plop-python/issues
License-Expression: MIT
License-File: LICENSE
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# Plop Python SDK

The official Python SDK for [Plop](https://plop.email) — receive and poll for emails in your tests and applications.

## Installation

```bash
pip install plop-sdk
```

## Quick Start

```python
from plop_sdk import Plop

# Reads PLOP_API_KEY from environment if not provided
plop = Plop(api_key="plop_...")

# List mailboxes
mailboxes = plop.mailboxes.list()

# List messages
messages = plop.messages.list(mailbox="qa", tag="login", limit=10)

# Get a specific message
message = plop.messages.get("message-uuid")

# Get the latest message
latest = plop.messages.latest(mailbox="qa", tag="otp")

# Wait for an email (polls until match or timeout)
email = plop.messages.wait_for(
    mailbox="qa",
    tag="verification",
    timeout=30,
    interval=1.0,
)
```

## Async Usage

```python
from plop_sdk import AsyncPlop

async with AsyncPlop() as plop:
    email = await plop.messages.wait_for(mailbox="qa", tag="login")
    messages = await plop.messages.list(mailbox="qa")
```

## Webhook Verification

```python
from plop_sdk import Plop

plop = Plop()

is_valid = plop.webhooks.verify(
    secret="whsec_...",
    signature=request.headers["x-plop-signature"],
    body=raw_body,
)
```

## Error Handling

```python
from plop_sdk import Plop, PlopError, PlopNotFoundError, PlopTimeoutError

plop = Plop()

try:
    message = plop.messages.get("nonexistent-id")
except PlopNotFoundError:
    print("Message not found")
except PlopError as e:
    print(f"API error: {e.message} (status={e.status})")
```

## Configuration

| Parameter | Environment Variable | Default |
|-----------|---------------------|---------|
| `api_key` | `PLOP_API_KEY` | Required |
| `base_url` | `PLOP_BASE_URL` | `https://api.plop.email` |
| `timeout` | - | `30.0` seconds |

## License

MIT
