Metadata-Version: 2.4
Name: mailtm-unofficial
Version: 0.1.1
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 community (unofficial) Python client 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 or via
the Mercure real-time hub.

![PyPI - Version](https://img.shields.io/pypi/v/mailtm-unofficial)
![PyPI - License](https://img.shields.io/pypi/l/mailtm-unofficial)
![PyPI - Python Versions](https://img.shields.io/pypi/pyversions/mailtm-unofficial)

## Table of contents

- [Installation](#installation)
- [Quick start](#quick-start)
- [Features](#features)
- [API reference](#api-reference)
- [Real-time events](#real-time-events)
- [Error handling](#error-handling)
- [Rate limits](#rate-limits)
- [Development](#development)
- [License](#license)

## Installation

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

**From PyPI:**

```bash
pip install mailtm-unofficial
```

**From GitHub:**

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

**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)
```

Mail.tm is a **receive-only** service — you can't send email from these addresses, only receive it.
Accounts are deleted automatically after a while; you can also delete them yourself with
`mail.delete_account()`.

## 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 reference

### Domains

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

### Accounts

```python
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)
```

`create_account()` generates the address and password for you when they're omitted and stores
them on the client, so you can call `mail.login(mail.address, mail.password)` again later.

### Messages

```python
mail.get_messages(page=1)         # -> Paginated[Message]
mail.iter_messages()              # -> Iterator[Message]
mail.get_message(message_id)      # -> Message (full, with body + attachments)
mail.mark_seen(message_id, seen=True)  # -> bool
mail.delete_message(message_id)
mail.get_source(source_id)        # -> dict (raw source + downloadUrl)
mail.download_message(message_id) # -> bytes (.eml file)
mail.download_attachment(attachment_or_url)  # -> bytes
mail.wait_for_message(from_=..., subject=..., contains=..., timeout=60)  # -> Message
```

### Real-time

```python
mail.stream_messages(account_id=None)  # -> EventStream (blocking Mercure 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)
```

## Error handling

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 per second      |
| `APIError`            | other  | Any other API error                  |

## Rate limits

- 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.

## Development

```bash
git clone https://github.com/irawrre/mailtm.git
cd mailtm
pip install -e .
pip install pytest
pytest
```

## License

[MIT](LICENSE)
