Metadata-Version: 2.4
Name: evilmail
Version: 1.0.0
Summary: Official Python SDK for the EvilMail API
Project-URL: Homepage, https://evilmail.pro
Project-URL: Documentation, https://evilmail.pro/docs
Project-URL: Repository, https://github.com/Evil-Mail/evilmail-python
Project-URL: Issues, https://github.com/Evil-Mail/evilmail-python/issues
Author-email: EvilMail <sdk@evilmail.pro>
License-Expression: MIT
License-File: LICENSE
Keywords: anonymous-email,api-client,custom-domain-email,disposable-email,email,email-api,email-client,email-verification,evilmail,inbox,mail,otp,privacy,random-email,sdk,temp-email,temporary-email,verification-code
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx<1.0.0,>=0.24.0
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://evilmail.pro">
    <img src="https://avatars.githubusercontent.com/u/267867069?v=4" alt="EvilMail Logo" width="120" height="120" style="border-radius: 20px;">
  </a>
</p>

<h1 align="center">EvilMail Python SDK</h1>

<p align="center">
  <strong>Official Python client library for the <a href="https://evilmail.pro">EvilMail</a> disposable email API</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/evilmail/"><img src="https://img.shields.io/pypi/v/evilmail.svg?style=flat-square&color=blue" alt="PyPI Version"></a>
  <a href="https://pypi.org/project/evilmail/"><img src="https://img.shields.io/pypi/pyversions/evilmail.svg?style=flat-square" alt="Python Versions"></a>
  <a href="https://pypi.org/project/evilmail/"><img src="https://img.shields.io/pypi/dm/evilmail.svg?style=flat-square&color=green" alt="Monthly Downloads"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License: MIT"></a>
  <a href="https://mypy-lang.org/"><img src="https://img.shields.io/badge/type--checked-mypy-blue.svg?style=flat-square" alt="Checked with mypy"></a>
</p>

<p align="center">
  <a href="#installation">Installation</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#async-usage">Async</a> •
  <a href="#api-reference">API Reference</a> •
  <a href="#error-handling">Error Handling</a> •
  <a href="https://evilmail.pro/docs">Documentation</a>
</p>

---

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

```bash
pip install evilmail
```

Requires **Python 3.9+**.

## Quick Start

```python
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("user@yourdomain.com")
for msg in messages:
    print(f"{msg.sender}: {msg.subject}")

# Extract a Google verification code automatically
code = client.verification.get_code("google", "user@yourdomain.com")
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

```python
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", "user@yourdomain.com")
        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](https://evilmail.pro).

```python
# 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:

```python
# 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:

```python
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", "user@yourdomain.com")
    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](https://github.com/Evil-Mail/evilmail-node) |
| **PHP** | `evilmail/evilmail-php` | [Evil-Mail/evilmail-php](https://github.com/Evil-Mail/evilmail-php) |
| **Python** | `evilmail` | [Evil-Mail/evilmail-python](https://github.com/Evil-Mail/evilmail-python) |
| **Go** | `evilmail-go` | [Evil-Mail/evilmail-go](https://github.com/Evil-Mail/evilmail-go) |

## Links

- [EvilMail Website](https://evilmail.pro) — Temporary & custom domain email platform
- [API Documentation](https://evilmail.pro/docs) — Full REST API reference
- [Chrome Extension](https://github.com/Evil-Mail/evilmail-chrome) — Disposable temp email in your browser
- [Firefox Add-on](https://github.com/Evil-Mail/evilmail-firefox) — Temp email for Firefox
- [Mobile App](https://github.com/Evil-Mail/evilmail-mobile) — Privacy-first email on Android

## License

[MIT](LICENSE)

## Support

- Issues: [github.com/Evil-Mail/evilmail-python/issues](https://github.com/Evil-Mail/evilmail-python/issues)
- Email: support@evilmail.pro
- Website: [evilmail.pro](https://evilmail.pro)
