Temp Mail Python Library

Official Python library for the Temp Mail API. Create temporary email addresses and receive emails programmatically.

Installation

pip install temp-mail

Quick Start

from tempmail import TempMailClient

# Initialize the client
client = TempMailClient("your-api-key")

# Create a temporary email address
email = client.create_email()
print(f"Your temporary email: {email.email}")

# Check for messages
messages = client.list_email_messages(email.email)
for message in messages:
    print(f"From: {message.from_addr}")
    print(f"Subject: {message.subject}")
    print(f"Body: {message.body_text}")

Features

• Create temporary email addresses - Generate disposable emails instantly
• List available domains - Get domains you can use for email creation
• Receive emails - Fetch messages sent to your temporary addresses
• Get individual messages - Retrieve specific messages by ID
• Get message source code - Access raw email source
• Download attachments - Download email attachments
• Delete messages - Clean up individual messages
• Delete emails - Remove email addresses and all their messages
• Rate limit monitoring - Track your API usage
• Async support - AsyncTempMailClient with the same interface for async/await code
• Error handling - Comprehensive exception handling
• Type hints - Full typing support for better development experience

API Reference

TempMailClient

The main client class for interacting with the Temp Mail API.

from tempmail import TempMailClient

# Basic initialization
client = TempMailClient("your-api-key")

# With custom parameters
client = TempMailClient(
    "your-api-key",
    base_url="https://api.temp-mail.io",
    timeout=30
)

Creating Email Addresses

# Create random email
email = client.create_email()

# Create with specific domain
email = client.create_email(domain="example.com")

# Create with specific email address
email = client.create_email(email="mytest@example.com")

# Create with domain type preference
from tempmail.models import DomainType
email = client.create_email(domain_type=DomainType.PREMIUM)

Listing Domains

domains = client.list_domains()
for domain in domains:
    print(f"Domain: {domain.name}, Type: {domain.type.value}")

Managing Messages

# List all messages for an email
messages = client.list_email_messages("test@example.com")
for message in messages:
    print(f"From: {message.from_addr}")
    print(f"Subject: {message.subject}")
    print(f"CC: {message.cc}")
    print(f"Attachments: {len(message.attachments or [])}")

# Get a specific message
message = client.get_message("message-id")

# Get message source code
source_code = client.get_message_source_code("message-id")

# Download an attachment
attachment_data = client.download_attachment("attachment-id")

# Delete a message
client.delete_message("message-id")

# Delete an entire email address and all its messages
client.delete_email("test@example.com")

Rate Limiting

# Get current rate limit status
rate_limit = client.get_rate_limit()
print(f"Limit: {rate_limit.limit}")
print(f"Remaining: {rate_limit.remaining}")
print(f"Used: {rate_limit.used}")
print(f"Reset time: {rate_limit.reset}")

# Access last rate limit from any request
last_rate_limit = client.last_rate_limit
if last_rate_limit:
    print(f"Last known remaining: {last_rate_limit.remaining}")

Async Usage

For async/await applications, use AsyncTempMailClient. It exposes the same methods as TempMailClient, but each one is a coroutine you await.

import asyncio

from tempmail import AsyncTempMailClient


async def main():
    # Use as an async context manager so the underlying connection is closed
    async with AsyncTempMailClient("your-api-key") as client:
        # Create a temporary email address
        email = await client.create_email()
        print(f"Your temporary email: {email.email}")

        # Check for messages
        messages = await client.list_email_messages(email.email)
        for message in messages:
            print(f"From: {message.from_addr}")
            print(f"Subject: {message.subject}")


asyncio.run(main())

If you don't use the context manager, close the client explicitly when you're done to release the connection pool:

client = AsyncTempMailClient("your-api-key")
try:
    email = await client.create_email()
finally:
    await client.close()

Every method available on TempMailClient (create_email, list_domains, list_email_messages, get_message, get_message_source_code, download_attachment, delete_message, delete_email, get_rate_limit) has an awaitable equivalent on AsyncTempMailClient, and the same exceptions are raised.

Error Handling

The library provides specific exception types for different error conditions:

from tempmail import (
    TempMailError,           # Base exception
    AuthenticationError,     # Invalid API key
    RateLimitError,         # Rate limit exceeded
    ValidationError,        # Invalid parameters
)

try:
    client = TempMailClient("invalid-key")
    email = client.create_email()
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limit exceeded")
except ValidationError as e:
    print(f"Invalid parameters: {e}")
except TempMailError as e:
    print(f"API error: {e}")

Development

Setup

# Clone the repository
git clone https://github.com/temp-mail-io/temp-mail-python
cd temp-mail-python

# Install uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies (including dev tools)
uv sync --extra dev

Running Tests

uv run pytest tests/

Code Quality

# Run all pre-commit hooks
uv run pre-commit run --all-files

# Or run individual tools
uv run ruff check          # Linting
uv run ruff format         # Formatting
uv run mypy tempmail/      # Type checking

Complete Example

from tempmail import TempMailClient, AuthenticationError, RateLimitError

# Initialize client
client = TempMailClient("your-api-key")

try:
    # Create a temporary email
    email = client.create_email()
    print(f"Created email: {email.email}")
    print(f"TTL: {email.ttl} seconds")

    # List available domains
    domains = client.list_domains()
    print(f"Available domains: {len(domains)}")

    # Check for messages (would be empty initially)
    messages = client.list_email_messages(email.email)
    print(f"Messages: {len(messages)}")

    # Check rate limit
    rate_limit = client.get_rate_limit()
    print(f"Requests remaining: {rate_limit.remaining}/{rate_limit.limit}")

except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limit exceeded")
except Exception as e:
    print(f"Error: {e}")

License

MIT License—see LICENSE file for details.

Links

• Temp Mail API Documentation
• GitHub Repository
• PyPI Package