mailtm

A community (unofficial) Python client for the mail.tm temporary email API. No API key or signup required — create a disposable inbox and receive emails over REST or via the Mercure real-time hub.

Table of contents

• Installation
• Quick start
• Features
• API reference
• Real-time events
• Error handling
• Rate limits
• Development
• License

Installation

Requires Python 3.8+ and requests (installed automatically).

From PyPI:

pip install mailtm-unofficial

From GitHub:

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

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)

Mail.tm is a receive-only service — you can't send email from these addresses, only receive it. Accounts are deleted automatically after a while; you can also delete them yourself with mail.delete_account().

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 reference

Domains

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

Accounts

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)

create_account() generates the address and password for you when they're omitted and stores them on the client, so you can call mail.login(mail.address, mail.password) again later.

Messages

mail.get_messages(page=1)         # -> Paginated[Message]
mail.iter_messages()              # -> Iterator[Message]
mail.get_message(message_id)      # -> Message (full, with body + attachments)
mail.mark_seen(message_id, seen=True)  # -> bool
mail.delete_message(message_id)
mail.get_source(source_id)        # -> dict (raw source + downloadUrl)
mail.download_message(message_id) # -> bytes (.eml file)
mail.download_attachment(attachment_or_url)  # -> bytes
mail.wait_for_message(from_=..., subject=..., contains=..., timeout=60)  # -> Message

Real-time

mail.stream_messages(account_id=None)  # -> EventStream (blocking Mercure 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)

Error handling

All failures raise APIError subclasses carrying the HTTP status code:

Rate limits

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

Development

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

License

MIT