Metadata-Version: 2.4
Name: mailtm-unofficial
Version: 0.1.0
Summary: A Python client library for the mail.tm temporary email API
Author: mailtm
License: MIT
Project-URL: Documentation, https://docs.mail.tm
Keywords: mail.tm,temporary email,disposable email,email,api
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Dynamic: license-file

# mailtm

A Python client library for the [mail.tm](https://docs.mail.tm) temporary email API.
No API key or signup required — create a disposable inbox and receive emails over REST.

## Installation

Requires Python 3.8+ and `requests` (installed automatically).

**From GitHub:**
```bash
pip install git+https://github.com/irawrre/mailtm.git
```

**From PyPI:**
```bash
pip install mailtm-unofficial
```

**From source / for development:**
```bash
git clone https://github.com/irawrre/mailtm.git
cd mailtm
pip install .
```

## Quick start

```python
from mailtm import MailTM

with MailTM() as mail:
    # Creates a random address (e.g. qk3xh2m9ab@nembul.com) and logs in.
    account = mail.create_account()
    print("Email:", account.address)

    # Wait until a message arrives (matches sender and/or subject).
    message = mail.wait_for_message(from_="no-reply@github.com", timeout=120)
    print(message.subject)

    # Fetch the full message with body + attachments.
    message = mail.get_message(message.id)
    print(message.text)

    for attachment in message.attachments:
        data = mail.download_attachment(attachment)
        open(attachment.filename, "wb").write(data)
```

## Features

- **Domains** — list, pick an active public domain
- **Accounts** — create (auto-generates address/password), login, get `/me`, delete
- **Messages** — list/paginate, fetch full detail, mark seen, delete, download `.eml` source
- **Attachments** — download attachment bytes
- **Polling** — `wait_for_message(...)` with sender/subject/body filters and timeout
- **Real-time** — `stream_messages()` blocks on the Mercure SSE hub and yields an event every time a message lands

## API

```python
mail.get_domains(page=1)          # -> Paginated[Domain]
mail.get_domain(domain_id)        # -> Domain
mail.get_random_domain()          # -> Domain (active, non-private)

mail.create_account(address=None, password=None, autologin=True)  # -> Account
mail.login(address, password)     # -> Account (stores bearer token)
mail.get_token(address, password) # -> Token
mail.me()                         # -> Account
mail.get_account(account_id)      # -> Account
mail.delete_account(account_id=None)

mail.get_messages(page=1)         # -> Paginated[Message]
mail.iter_messages()              # -> Iterator[Message]
mail.get_message(message_id)      # -> Message (full)
mail.mark_seen(message_id)        # -> bool
mail.delete_message(message_id)
mail.get_source(source_id)        # -> dict (raw source)
mail.download_message(message_id) # -> bytes (.eml)
mail.download_attachment(attachment_or_url)  # -> bytes
mail.wait_for_message(from_=..., subject=..., contains=..., timeout=60)  # -> Message
mail.stream_messages()            # -> EventStream (real-time SSE)
```

## Real-time events

Instead of polling you can block on the Mercure hub. Each event carries the
account resource with an updated `used` counter, fired whenever a message is received:

```python
from mailtm import MailTM

with MailTM() as mail:
    account = mail.create_account()
    for event in mail.stream_messages().iter_events():
        print("Account storage now:", event.account().used)
```

## Errors

All failures raise `APIError` subclasses carrying the HTTP status code:

| Exception           | Status | Meaning                              |
| ------------------- | ------ | ------------------------------------ |
| `ValidationError`   | 400/422| Malformed or invalid payload         |
| `AuthenticationError` | 401   | Bad or missing bearer token          |
| `NotFoundError`     | 404    | Resource does not exist              |
| `RateLimitError`    | 429    | More than 8 requests/second          |
| `APIError`          | other  | Any other API error                  |

## Notes

- The general rate limit is 8 queries per second per IP address.
- `POST /accounts`, `GET /domains`, and `POST /token` need no authentication; everything else requires a bearer token.
- Deleting an account is permanent.
