✉️ TempMail MailTM (tempmail-mailtm)

A fast, lightweight, type-annotated, and production-ready Python client library for the 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

pip install tempmail-mailtm

Or install directly from source:

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

---

💡 Usage Examples

1. Basic Usage (Context Manager)

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

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:

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

• Modern modular package architecture (mailtm)
• Dynamic domain retrieval fallback
• Clean context manager support (with Mail())
• 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)

1. Is Mail.tm free to use?

Yes, Mail.tm is a free public temporary email service. No credit card or registration is required to generate disposable email addresses.

2. Will existing code referencing meail.py still work?

Yes! meail.py has been preserved as a legacy import wrapper forwarding calls to mailtm.Mail.

3. How long do temporary email accounts last?

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.

---

🤝 Contributing

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

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

👨‍💻 Maintainer & Author

MAHDI HASAN SHUVO

• GitHub: @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.