evilmail 1.0.0

Official Python SDK for the EvilMail API

EvilMail Python SDK

Official Python client library for the EvilMail disposable email API

Installation • Quick Start • Async • API Reference • Error Handling • Documentation

---

The EvilMail Python SDK provides a modern, fully-typed interface for integrating temporary email, disposable email addresses, email verification code extraction, inbox management, and custom domain email services into your Python applications. Supports both synchronous and asynchronous clients with complete type hints and dataclass response models.

Features

• Sync + Async Clients — Choose EvilMail or AsyncEvilMail based on your application architecture
• Temporary Email — Create anonymous disposable email addresses with configurable TTL
• Email Verification Codes — Auto-extract OTP codes from Google, Facebook, Instagram, TikTok, Discord, Twitter, LinkedIn, iCloud
• Account Management — Full CRUD for persistent email accounts on custom domains
• Inbox Access — Read emails, list messages, fetch full HTML & plain text content
• Random Email Generator — Batch create random email accounts with auto-generated passwords
• Domain Management — List free, premium, and custom email domains
• Fully Typed — Complete type hints with py.typed marker, mypy --strict compatible
• Dataclass Models — All API responses parsed into frozen dataclasses
• Context Manager Support — Automatic resource cleanup with with / async with
• Built on httpx — Modern, high-performance HTTP client with connection pooling

Installation

pip install evilmail

Requires Python 3.9+.

Quick Start

from evilmail import EvilMail

client = EvilMail("your-api-key")

# Create a temporary disposable email address
temp = client.temp_email.create(domain="evilmail.pro", ttl_minutes=60)
print(f"Temporary email: {temp.email}")
print(f"Session token: {temp.session_token}")
print(f"Expires at: {temp.expires_at}")

# Check session status
session = client.temp_email.check_session(temp.session_token)

# Read a specific message from temp inbox
message = client.temp_email.get_message(temp.session_token, uid=1)
print(f"Subject: {message.subject}")

# List inbox messages from a persistent account
messages = client.inbox.list("[e-mail]")
for msg in messages:
    print(f"{msg.sender}: {msg.subject}")

# Extract a Google verification code automatically
code = client.verification.get_code("google", "[e-mail]")
print(f"Verification code: {code.code}")

# Batch create random email accounts
batch = client.random_email.create_batch("yourdomain.com", count=5, password_length=20)
for entry in batch.emails:
    print(f"{entry.email}: {entry.password}")

client.close()

Async Usage

import asyncio
from evilmail import AsyncEvilMail

async def main():
    async with AsyncEvilMail("your-api-key") as client:
        # Create temp email
        temp = await client.temp_email.create(domain="evilmail.pro")
        print(f"Email: {temp.email}")

        # Extract verification code
        code = await client.verification.get_code("google", "[e-mail]")
        print(f"Code: {code.code}")

        # List accounts
        accounts = await client.accounts.list()
        for acct in accounts:
            print(f"Account: {acct.email}")

asyncio.run(main())

Authentication

All requests require an API key via the X-API-Key header. Get your key from the EvilMail dashboard.

# Basic
client = EvilMail("your-api-key")

# With custom settings
client = EvilMail(
    "your-api-key",
    base_url="https://evilmail.pro",  # default
    timeout=60.0,                      # seconds, default 30
)

Context Managers

Both clients support context managers for automatic resource cleanup:

# Synchronous
with EvilMail("your-api-key") as client:
    accounts = client.accounts.list()

# Asynchronous
async with AsyncEvilMail("your-api-key") as client:
    accounts = await client.accounts.list()

---

API Reference

Temporary Email

Create anonymous, disposable email addresses with automatic expiration. Perfect for sign-up verification, automated testing, and privacy protection.

client.temp_email.create(*, domain=None, ttl_minutes=None)

Create a new temporary email address.

Parameter	Type	Required	Description
domain	str	No	Preferred domain for the disposable address
ttl_minutes	int	No	Time-to-live in minutes

Returns: TempEmail — email, domain, session_token, ttl_minutes, expires_at

client.temp_email.check_session(token)

Check if a temporary email session is still active.

client.temp_email.get_message(token, uid)

Read a specific message from a temp email inbox.

Parameter	Type	Required	Description
token	str	Yes	Session token from create()
uid	int	Yes	Message UID

Returns: Message

client.temp_email.delete(token)

Permanently delete a temporary email session.

---

Accounts

Manage persistent email accounts on custom domains.

client.accounts.list()

Returns: list[Account] — email, domain, created_at

client.accounts.create(email, password)

Returns: CreatedAccount — email

client.accounts.delete(emails)

Returns: DeleteResult — deleted_count

client.accounts.change_password(email, new_password)

---

Inbox

Read emails from persistent account inboxes with full message content.

client.inbox.list(email)

Returns: list[InboxMessage] — uid, sender, subject, date, seen

client.inbox.get_message(uid, email)

Returns: Message — uid, sender, subject, text, html, date, seen

---

Verification Codes

Automatically extract OTP verification codes from emails sent by popular services.

client.verification.get_code(service, email)

Supported services: facebook, twitter, google, icloud, instagram, tiktok, discord, linkedin

Returns: VerificationCode — code, service, email, sender, subject, date

---

Random Email

Generate random email accounts with secure auto-generated credentials.

client.random_email.preview()

Returns: RandomEmailPreview — username, email, password, domain

client.random_email.create_batch(domain, *, count=None, password_length=None)

Returns: RandomEmailBatch — count, emails: list[RandomEmailEntry]

---

Domains

List available email domains by tier.

client.domains.list()

Returns: Domains — free, premium, customer, package_type, authenticated

---

Response Models

All API responses are parsed into frozen dataclasses with complete type hints:

Model	Fields
TempEmail	email, domain, session_token, ttl_minutes, expires_at
InboxMessage	uid, sender, subject, date, seen
Account	email, domain, created_at
CreatedAccount	email
DeleteResult	deleted_count
Message	uid, sender, subject, text, html, date, seen
VerificationCode	code, service, email, sender, subject, date
RandomEmailPreview	username, email, password, domain
RandomEmailEntry	email, password
RandomEmailBatch	count, emails
Domains	free, premium, customer, package_type, authenticated

---

Error Handling

The SDK raises typed exceptions for precise error handling:

from evilmail import (
    EvilMailError,       # Base exception for all SDK errors
    APIError,            # Non-success HTTP response from the API
    AuthenticationError, # 401 Unauthorized — invalid API key
    ForbiddenError,      # 403 Forbidden — insufficient permissions
    NotFoundError,       # 404 Not Found — resource does not exist
    RateLimitError,      # 429 Too Many Requests — slow down
    ServerError,         # 5xx Server Error — API-side issue
    ConnectionError,     # Network connectivity issues
    TimeoutError,        # Request timeout exceeded
    ValidationError,     # Invalid parameters (client-side validation)
)

try:
    code = client.verification.get_code("google", "[e-mail]")
    print(f"Your code: {code.code}")
except NotFoundError:
    print("No verification email found yet")
except RateLimitError as exc:
    print(f"Rate limited: {exc.message}")
except AuthenticationError:
    print("Invalid API key — check your credentials")
except EvilMailError as exc:
    print(f"Error: {exc}")

---

Use Cases

• Automated Testing & QA — Generate disposable email addresses for end-to-end test suites with pytest, unittest, or Robot Framework
• Web Scraping & Automation — Create temp emails for sign-up flows in Selenium, Playwright, or Scrapy pipelines
• Email Verification Bots — Automatically extract OTP codes from Google, Facebook, Instagram, and more
• Account Provisioning — Bulk create and manage email accounts for SaaS platforms
• Privacy & Anonymity — Use anonymous email addresses to protect user identity
• CI/CD Pipelines — Integrate email testing into GitHub Actions, GitLab CI, or Jenkins workflows
• Async Web Applications — Native async support for FastAPI, aiohttp, and Django async views
• Data Science & Research — Programmatic email generation for data collection workflows

---

Related SDKs

Language	Package	Repository
Node.js	evilmail	Evil-Mail/evilmail-node
PHP	evilmail/evilmail-php	Evil-Mail/evilmail-php
Python	evilmail	Evil-Mail/evilmail-python
Go	evilmail-go	Evil-Mail/evilmail-go

Links

• EvilMail Website — Temporary & custom domain email platform
• API Documentation — Full REST API reference
• Chrome Extension — Disposable temp email in your browser
• Firefox Add-on — Temp email for Firefox
• Mobile App — Privacy-first email on Android

License

MIT

Support

• Issues: github.com/Evil-Mail/evilmail-python/issues
• Email: [e-mail]
• Website: evilmail.pro