Metadata-Version: 2.4
Name: guerrillamail-api
Version: 1.0.0
Summary: Python client for the Guerrilla Mail disposable email JSON API
Project-URL: Homepage, https://github.com/4EYES44/guerrillamail-api
Project-URL: Documentation, https://github.com/4EYES44/guerrillamail-api#readme
Project-URL: Repository, https://github.com/4EYES44/guerrillamail-api
Project-URL: Issues, https://github.com/4EYES44/guerrillamail-api/issues
Author: guerrillamail-api contributors
License-Expression: MIT
License-File: LICENSE
Keywords: api,disposable-email,guerrilla-mail,temporary-email
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: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# guerrillamail-api

Python client for the [Guerrilla Mail](https://www.guerrillamail.com/) disposable email JSON API.

Create temporary inboxes, poll for new mail, read full messages, customize addresses, extend lifetime, and delete messages — with automatic `PHPSESSID` / `SUBSCR` cookie handling.

## Install

```bash
pip install guerrillamail-api
```

## Quick start

```python
from guerrillamail import GuerrillaMailClient

with GuerrillaMailClient() as gm:
    mailbox = gm.create_email()
    print("Address:", mailbox.address)
    print("Expires in (s):", mailbox.seconds_remaining())

    inbox = gm.check_inbox()
    for msg in inbox.messages:
        print(msg.mail_from, "—", msg.mail_subject)

    full = gm.read_message(inbox.messages[0].mail_id)
    print(full.mail_body)
```

## Wait for an incoming email

```python
with GuerrillaMailClient() as gm:
    gm.create_email()
    gm.check_inbox()  # consume welcome mail sequence

    # Poll until a message arrives (adjust filters as needed)
    msg = gm.wait_for_message(
        timeout=180,
        poll_interval=5,
        subject_contains="verification",
    )
    print(msg.mail_body)
```

## Custom address

```python
with GuerrillaMailClient() as gm:
    gm.create_email()
    gm.set_username("mytestuser")
    print(gm.mailbox.address)
```

## API coverage

| Method | Guerrilla Mail function |
|--------|-------------------------|
| `create_email()` | `get_email_address` |
| `set_username()` | `set_email_user` |
| `check_inbox()` | `check_email` |
| `list_inbox()` | `get_email_list` |
| `read_message()` | `fetch_email` |
| `delete_messages()` | `del_email` |
| `forget_address()` | `forget_me` |
| `extend_time()` | `extend` |
| `get_older_list()` | `get_older_list` |

Lower-level methods (`get_email_address`, `check_email`, …) return raw JSON dicts.

## Rate limits

The public API may be rate-limited. Avoid tight polling; use `poll_interval` ≥ 5 seconds in production.

## License

MIT
