Metadata-Version: 2.4
Name: smailpro-temp-client
Version: 0.1.0
Summary: Free SmailPro temp-email client with persistent state and duplicate protection
Project-URL: Homepage, https://github.com/YOUR_GITHUB_USERNAME/smailpro-temp-client
Project-URL: Documentation, https://github.com/YOUR_GITHUB_USERNAME/smailpro-temp-client/blob/main/smailpro_client/DOCUMENTATION.md
Project-URL: Issues, https://github.com/YOUR_GITHUB_USERNAME/smailpro-temp-client/issues
Author: dev
License-Expression: MIT
License-File: LICENSE
Keywords: otp,playwright,smailpro,temp-mail,temporary-email
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: playwright>=1.40
Description-Content-Type: text/markdown

# smailpro-temp-client

`smailpro-temp-client` is a Python package for working with the free SmailPro temp-email web flow.

It supports:

- creating temporary addresses
- loading and saving mailbox state as JSON
- polling inboxes for new messages
- opening full message bodies
- persisting a local registry so the same temp email is not accepted twice across runs

The public import path is `smailpro_client`.

## Install

From a local checkout:

```bash
pip install .
```

After publishing to PyPI:

```bash
pip install smailpro-temp-client
```

Then install the browser runtime used by Playwright:

```bash
python3 -m playwright install chromium
```

## CLI

Create a unique temporary email and save its state:

```bash
smailpro-client --create-only --show-json --save-state smail_state.json
```

Read the current inbox:

```bash
smailpro-client --state-file smail_state.json --list-only --show-json
```

Wait for unseen messages only:

```bash
smailpro-client --state-file smail_state.json --wait-timeout 300 --poll-interval 5 --show-json
```

Read the first message body:

```bash
smailpro-client --state-file smail_state.json --list-only --read-first --show-json
```

## Python API

```python
import asyncio

from smailpro_client import EmailRegistry, MailState, SmailProClient


async def main() -> None:
    registry = EmailRegistry()
    async with SmailProClient() as client:
        email = await client.create_unique_email(registry=registry, max_attempts=10)
        messages = await client.list_messages(email)
        state = MailState(email=email, messages=messages)
        print(state.to_dict())


asyncio.run(main())
```

## Publishing

The repository includes:

- `pyproject.toml` for packaging
- `.github/workflows/publish.yml` for GitHub Actions Trusted Publishing
- `smailpro_client/README.md` and `smailpro_client/DOCUMENTATION.md` for module-level docs

Before your first real release, replace the placeholder GitHub URLs in `pyproject.toml`.
