Metadata-Version: 2.4
Name: tempmail-mailtm
Version: 1.0.0
Summary: Fast, lightweight, and modern Python client library for Mail.tm temporary disposable email API.
Home-page: https://github.com/Mahdi-hasan-shuvo/temp-mail
Author: MAHDI HASAN SHUVO
Author-email: MAHDI HASAN SHUVO <shuvobbhh@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Mahdi-hasan-shuvo/temp-mail
Project-URL: Repository, https://github.com/Mahdi-hasan-shuvo/temp-mail.git
Project-URL: Documentation, https://github.com/Mahdi-hasan-shuvo/temp-mail#readme
Project-URL: Bug Tracker, https://github.com/Mahdi-hasan-shuvo/temp-mail/issues
Keywords: temp-mail,disposable-email,mailtm,tempmail,email-generator,automation,temporary-email-api,python-email
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: user-agent>=0.1.10
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: requests-mock>=1.9.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# ✉️ TempMail MailTM (`tempmail-mailtm`)

[![PyPI version](https://img.shields.io/pypi/v/tempmail-mailtm.svg?color=blue)](https://pypi.org/project/tempmail-mailtm/)
[![Python Version](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![CI Status](https://github.com/Mahdi-hasan-shuvo/temp-mail/actions/workflows/ci.yml/badge.svg)](https://github.com/Mahdi-hasan-shuvo/temp-mail/actions)
[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

A fast, lightweight, type-annotated, and production-ready Python client library for the [Mail.tm](https://mail.tm) temporary disposable email service.

Ideal for **automated testing**, **QA email verification**, **bot development**, and **privacy protection**.

---

## ✨ Features

- ⚡ **Zero-boilerplate API**: Create accounts and fetch inbox messages in under 5 lines of Python code.
- 🔄 **Dynamic Domain Resolution**: Automatically queries live, active domains from Mail.tm so account creation never breaks.
- 🛡️ **Robust Exception Handling**: Custom exceptions for HTTP errors, authentication failures, rate limits, and missing resources.
- 🔒 **Context Manager Support**: Clean automatic HTTP session cleanup with `with Mail() as client:`.
- 🧩 **100% Backward Compatible**: Preserves full support for existing `meail.py` scripts.
- 📦 **PEP 561 Compliant**: Includes `py.typed` marker for static type checking with `mypy`.

---

## 🏗️ Architecture Flow

```
┌─────────────────┐       GET /domains       ┌──────────────────┐
│  Python Client  │ ───────────────────────> │  api.mail.tm     │
│  (mailtm / Mail)│ <─────────────────────── │  (Mail.tm Cloud) │
└────────┬────────┘    Available Domains     └──────────────────┘
         │
         │ POST /accounts
         ├─────────────────────────────────> Create Disposable Email
         │
         │ POST /token
         ├─────────────────────────────────> Obtain JWT Bearer Token
         │
         │ GET /messages
         └─────────────────────────────────> Fetch Inbox & Parsed Text/HTML
```

---

## 🚀 Quickstart & Installation

### Installation via pip

```bash
pip install tempmail-mailtm
```

*Or install directly from source:*

```bash
git clone https://github.com/Mahdi-hasan-shuvo/temp-mail.git
cd temp-mail
pip install .
```

---

## 💡 Usage Examples

### 1. Basic Usage (Context Manager)

```python
from mailtm import Mail

with Mail() as client:
    # 1. Create a random temporary email account
    account = client.create_account()
    print("Email Address:", account['address'])
    print("Password:     ", account['_password'])

    # 2. Get JWT Token
    auth = client.token(account['address'], account['_password'])
    token = auth['token']

    # 3. Check Inbox Messages
    messages = client.get_messages(token)
    for msg in messages:
        print(f"From: {msg['from']['address']} | Subject: {msg['subject']}")
```

### 2. Custom Address & Domain Specification

```python
from mailtm import Mail

client = Mail()

# Create account with custom prefix
account = client.create_account(email="qa_test_runner_2026")
print("Generated Address:", account['address'])

client.close()
```

---

## 📖 API Reference

### `Mail(base_url="https://api.mail.tm")`
Main client class wrapping Mail.tm API endpoints.

| Method | Return Type | Description |
| :--- | :--- | :--- |
| `get_domains()` | `List[dict]` | Returns list of currently active domain objects. |
| `create_account(email=None, password=None, domain=None)` | `Dict[str, Any]` | Registers a new temporary email account. Returns account dict with `_password`. |
| `token(address, password)` | `Dict[str, Any]` | Retrieves JWT Bearer token dictionary (`{'token': '...', 'id': '...'}`). |
| `get_messages(token, page=1)` | `List[Dict[str, Any]]` | Returns detailed list of inbox messages (id, from, to, subject, text, html, downloadUrl). |
| `get_message(token, message_id)` | `Dict[str, Any]` | Returns single detailed message object. |
| `delete_message(token, message_id)` | `bool` | Deletes a message by ID. |
| `delete_account(token, account_id)` | `bool` | Permanently deletes an account by ID. |

---

## ⚠️ Error Handling

`mailtm-python` provides explicit exception types derived from `MailTMError`:

```python
from mailtm import Mail, AuthenticationError, RateLimitError, APIError

try:
    client = Mail()
    client.token("wrong_email@domain.com", "wrong_password")
except AuthenticationError as err:
    print("Authentication failed:", err)
except RateLimitError as err:
    print("Rate limit reached. Please wait before sending more requests.")
except APIError as err:
    print("API Error:", err.status_code, err)
```

---

## 🛣️ Roadmap

- [x] Modern modular package architecture (`mailtm`)
- [x] Dynamic domain retrieval fallback
- [x] Clean context manager support (`with Mail()`)
- [x] Full unit test suite with mock requests
- [ ] Async client implementation (`aiohttp` / `httpx`)
- [ ] Built-in polling event listener for incoming emails (`on_message`)

---

## ❓ Frequently Asked Questions (FAQ)

<details>
<summary><b>1. Is Mail.tm free to use?</b></summary>
Yes, Mail.tm is a free public temporary email service. No credit card or registration is required to generate disposable email addresses.
</details>

<details>
<summary><b>2. Will existing code referencing <code>meail.py</code> still work?</b></summary>
Yes! <code>meail.py</code> has been preserved as a legacy import wrapper forwarding calls to <code>mailtm.Mail</code>.
</details>

<details>
<summary><b>3. How long do temporary email accounts last?</b></summary>
Mail.tm accounts persist as long as the underlying domain remains active on the service. Messages are stored on Mail.tm servers until deleted or purged according to Mail.tm retention policies.
</details>

---

## 🤝 Contributing

Contributions are welcome! Please check out [CONTRIBUTING.md](CONTRIBUTING.md) for details on code style, testing, and submitting pull requests.

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 👨‍💻 Maintainer & Author

**MAHDI HASAN SHUVO**
- GitHub: [@Mahdi-hasan-shuvo](https://github.com/Mahdi-hasan-shuvo)
- Role: Senior Automation Engineer | Tool Builder | Full-Stack Developer

---

## 🌟 Support & Commercial Inquiries

If this project helps you in your automated testing or workflows, please consider giving it a ⭐ on GitHub!

For custom automation development or commercial integrations, reach out via [GitHub Issues](https://github.com/Mahdi-hasan-shuvo/temp-mail/issues).
