temmail 2.1.0
Professional temporary email service wrapper with a comprehensive CLI tool.
Requires Python: >=3.8
Keywords: email, temporary, tempmail, api, cli

# TemMail

[![PyPI version](https://badge.fury.io/py/temmail.svg)](https://badge.fury.io/py/temmail)
[![Python versions](https://img.shields.io/pypi/pyversions/temmail.svg)](https://pypi.org/project/temmail/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/bl)


**TemMail** is a professional Python wrapper for the `temp-mail.io` API, providing advanced temporary email functionality with a comprehensive CLI tool.

## Features

-   🚀 **Easy to Use**: Simple API for creating and managing temporary email accounts.
-   📧 **Message Management**: Full message handling with read/unread status.
-   🔍 **Search & Filter**: Advanced search capabilities across messages.
-   💾 **Export Options**: Export messages in JSON, TXT, or EML formats.
-   🖥️ **CLI Tool**: Full-featured command-line interface.
-   🔄 **Auto-monitoring**: Monitor accounts for new messages with callbacks.
-   🛡️ **Error Handling**: Comprehensive error handling with retry logic.
-   📊 **Statistics**: Get detailed account and message statistics.
-   ⚙️ **Configurable**: Extensive configuration options.
-   🎯 **Type Hints**: Full type annotation support.

## Installation

You can install TemMail using `pip`:

```bash
pip install temmail
```

For development, you can install the extra dependencies:

```bash
pip install temmail[dev]
```

### Package Structure
The project is organized like this:
```
temmail/
├── temmail/
│   ├── __init__.py
│   ├── cli.py
│   ├── core.py
│   ├── exceptions.py
│   ├── config.py
│   ├── models.py
│   └── utils.py
├── tests/
│   ├── __init__.py
│   ├── test_core.py
│   ├── test_cli.py
│   └── test_config.py
├── docs/
│   ├── README.md
│   ├── CHANGELOG.md
│   └── LICENSE
├── pyproject.toml
├── setup.cfg
├── setup.py
├── MANIFEST.in
└── .gitignore
```

## Usage

TemMail offers both a powerful Python API and a comprehensive Command-Line Interface (CLI) to manage temporary email accounts.

### Python API Examples

Here are some examples of how to use the Python API:

```python
from temmail import get_temp_email, wait_for_message, TemMailAccount

# 1. Create a temporary email account
account: TemMailAccount = get_temp_email()
print(f"Your temporary email: {account.email}")

# 2. Get and manage messages
messages = account.get_messages()
print(f"Received {len(messages)} messages")

if messages:
    # Mark the first message as read
    messages[0].mark_as_read()
    print(f"Marked message '{messages[0].subject}' as read.")

# 3. Wait for a specific message
def is_verification(msg):
    return "verify" in msg.subject.lower()

print("Waiting for a verification email...")
message = wait_for_message(account, timeout=60, filter_func=is_verification)
if message:
    print(f"Got verification email: {message.subject}")
else:
    print("No verification email received within the timeout.")

# 4. Search messages
search_results = account.search_messages(query="important", field="subject")
print(f"Found {len(search_results)} messages with 'important' in subject.")

# 5. Get account statistics
stats = account.get_stats()
print(f"Account statistics: Total messages: {stats.total_messages}, Unread: {stats.unread_messages}")

# 6. Delete the account (use with caution!)
# account.delete()
# print(f"Account {account.email} deleted.")
```

### Command-Line Interface (CLI) Examples

TemMail also comes with a powerful CLI. Here are some examples:

```bash
# 1. Create a new temporary email account
temmail create

# 2. Monitor for new messages and open the first one automatically
temmail monitor --stop-first --auto-open

# 3. List all unread messages
temmail messages --unread

# 4. Search messages by subject containing "password"
temmail search "password" --field subject

# 5. Export all messages to a JSON file
temmail export -o messages.json --format json

# 6. Get information about the current account
temmail info

# 7. Delete the current temporary email account (use with caution!)
# temmail delete --yes
```

## Documentation

For more detailed information, please refer to the [official documentation](./index.md).

## Contributing

Contributions are welcome! If you'd like to contribute to the project, please follow these steps:

1.  Fork the repository on GitHub.
2.  Create a new branch with a descriptive name.
3.  Make your changes and commit them with a clear message.
4.  Push your changes to your fork.
5.  Create a pull request to the main repository.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.ile for details.


### Documentation
Full documentation is available at https://temmail.readthedocs.io