temmail 2.1.0

Professional temporary email service wrapper with a comprehensive CLI tool.

TemMail

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:

pip install temmail

For development, you can install the extra dependencies:

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:

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:

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

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 file for more details.ile for details.

Documentation

Full documentation is available at https://temmail.readthedocs.io