mailtm

A Python client library for the mail.tm temporary email API. No API key or signup required — create a disposable inbox and receive emails over REST.

Installation

Requires Python 3.8+ and requests (installed automatically).

From GitHub:

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

From PyPI:

pip install mailtm-unofficial

From source / for development:

git clone https://github.com/irawrre/mailtm.git
cd mailtm
pip install .

Quick start

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)

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

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

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)

mail.get_messages(page=1)         # -> Paginated[Message]
mail.iter_messages()              # -> Iterator[Message]
mail.get_message(message_id)      # -> Message (full)
mail.mark_seen(message_id)        # -> bool
mail.delete_message(message_id)
mail.get_source(source_id)        # -> dict (raw source)
mail.download_message(message_id) # -> bytes (.eml)
mail.download_attachment(attachment_or_url)  # -> bytes
mail.wait_for_message(from_=..., subject=..., contains=..., timeout=60)  # -> Message
mail.stream_messages()            # -> EventStream (real-time 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:

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)

Errors

All failures raise APIError subclasses carrying the HTTP status code:

Notes

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