mailtd

Official Python SDK for Mail.td — temp mail & temporary email with REST API, webhooks, and custom domains. Instant inboxes, password protected, sign in from any device.

• Temp Mail API — Create and manage temporary email addresses programmatically
• Webhooks — Get notified in real-time when emails arrive
• Custom Domains — Use your own domain for branded temporary mailboxes
• Password Protected — Sign in to the same mailbox from any device

Install

pip install mailtd

Requires Python 3.9+.

Quick Start

from mailtd import MailTD

client = MailTD("td_...")

# Create a temporary email address
account = client.accounts.create("test@mail.td", password="mypassword")

# List messages
messages, page = client.messages.list(account.id)

# Get a message
msg = client.messages.get(account.id, messages[0].id)
print(msg.subject, msg.text_body)

Use Cases

• Automated testing — Create temp mail addresses in CI/CD to test signup flows, OTP verification, and transactional emails
• Email verification testing — Validate that your app sends the right emails with the right content
• QA environments — Give each test run its own mailbox, then tear it down

Authentication

All API calls require a Pro API Token (td_...). Pass it when creating the client:

# With a token string
client = MailTD("td_...")

# With custom base URL
client = MailTD("td_...", base_url="https://api.mail.td")

# As context manager
with MailTD("td_...") as client:
    messages, _ = client.messages.list(account_id)

Resources

Accounts

domains = client.accounts.list_domains()
account = client.accounts.create("user@mail.td", password="pass123")
info = client.accounts.get(account_id)
client.accounts.reset_password(account_id, password="newpass")
client.accounts.delete(account_id)

Messages

messages, page = client.messages.list(account_id)
msg = client.messages.get(account_id, message_id)
eml = client.messages.get_source(account_id, message_id)
attachment = client.messages.get_attachment(account_id, message_id, 0)
client.messages.mark_as_read(account_id, message_id)
count = client.messages.batch_mark_as_read(account_id, all=True)
client.messages.delete(account_id, message_id)

Domains (Pro)

domains = client.domains.list()
result = client.domains.create("example.com")
status = client.domains.verify(domain_id)
client.domains.delete(domain_id)

Webhooks (Pro)

webhook = client.webhooks.create("https://example.com/hook", events=["email.received"])
deliveries = client.webhooks.list_deliveries(webhook.id)
secret = client.webhooks.rotate_secret(webhook.id)
client.webhooks.delete(webhook.id)

Tokens (Pro)

result = client.tokens.create("CI Token")
tokens = client.tokens.list()
client.tokens.revoke(token_id)

Billing (Pro)

status = client.billing.get_status()
client.billing.cancel()
client.billing.resume()
url = client.billing.get_portal_url()

User (Pro)

me = client.user.get_me()
accounts = client.user.list_accounts()
client.user.delete_account(account_id)
client.user.reset_account_password(account_id, password="newpass")
messages, page = client.user.list_account_messages(account_id)

Error Handling

from mailtd import MailTD, APIError

try:
    client.accounts.create("taken@mail.td", password="...")
except APIError as e:
    print(e.status)  # 409
    print(e.code)    # "address_taken"

Links

• Website — Temp mail & temporary email with REST API
• API Documentation — Full API reference
• Node.js SDK — npm install mailtd
• Go SDK — go get github.com/mailtd/mailtd-go
• CLI — Command-line tool

License

MIT