evilmail 1.0.0__tar.gz

evilmail-1.0.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.tox/
+.venv/
+venv/

evilmail-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EvilMail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

evilmail-1.0.0/PKG-INFO

@@ -0,0 +1,377 @@
+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)