### Quick Start: Generate and Receive Email

Source: https://github.com/cleantempmail/cleantempmail-python-examples/blob/main/README.md

A quick start example demonstrating how to generate a temporary email address and then retrieve any incoming emails using the requests library. Ensure you have your API key configured.

```python
import requests

# Configuration
API_KEY = "ct-test"
BASE_URL = "https://cleantempmail.com/api"

# Generate email
response = requests.get(
    f"{BASE_URL}/generate-email",
    headers={\"X-API-Key\": API_KEY}
)
email = response.json()["data"]["email"]
print(f"✅ Generated: {email}")

# Wait for emails
import time
time.sleep(10)

# Get emails
response = requests.get(
    f"{BASE_URL}/emails",
    params={\"email\": email},
    headers={\"X-API-Key\": API_KEY}
)
emails = response.json()["data"]["emails"]
print(f"📧 Received {len(emails)} emails")
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/cleantempmail/cleantempmail-python-examples/blob/main/README.md

Clone the repository to your local machine. Install optional dependencies for async examples using pip.

```bash
git clone https://github.com/cleantempmail/cleantempmail-python-examples.git
cd cleantempmail-python-examples
```

```bash
pip install -r requirements.txt
```

--------------------------------

### Run Example Script

Source: https://github.com/cleantempmail/cleantempmail-python-examples/blob/main/QUICK_START.md

Execute a Python script to interact with the CleanTempMail API. Ensure you have Python 3 installed.

```bash
python3 01_generate_email.py
```

--------------------------------

### Get Single Email by ID (Python)

Source: https://context7.com/cleantempmail/cleantempmail-python-examples/llms.txt

Retrieves the full details of a specific email using its unique ID. This is a GET request that requires the email ID in the URL path. Authentication is done via the 'X-API-Key' header.

```python
import json
import urllib.request

API_KEY = "ct-test"
BASE_URL = "https://cleantempmail.com/api"

email_id = "abc123"
url = f"{BASE_URL}/email/{email_id}"
headers = {"X-API-Key": API_KEY}

req = urllib.request.Request(url, headers=headers)

with urllib.request.urlopen(req) as response:
    data = json.loads(response.read().decode())

    if data.get("success"):
        email = data["data"]
        print(f"Subject: {email['subject']}")
        print(f"From: {email['from_address']}")
        print(f"Content: {email.get('content', '')}")
```

```bash
# Using curl:
# curl -X GET "https://cleantempmail.com/api/email/abc123" \
#      -H "X-API-Key: ct-test"
```

--------------------------------

### Get System Statistics

Source: https://context7.com/cleantempmail/cleantempmail-python-examples/llms.txt

Retrieves overall system statistics including total emails, unique subjects, and active domains. Requires the API key.

```python
import json
import urllib.request

API_KEY = "ct-test"
BASE_URL = "https://cleantempmail.com/api"

url = f"{BASE_URL}/stats"
headers = {"X-API-Key": API_KEY}

req = urllib.request.Request(url, headers=headers)

with urllib.request.urlopen(req) as response:
    data = json.loads(response.read().decode())

    if data.get("success"):
        stats = data["data"]
        print(f"Total emails: {stats.get('total_emails', 0)}")
        print(f"Unique subjects: {stats.get('unique_subjects', 0)}")
        print(f"Active domains: {stats.get('active_domains', 0)}")
```

```bash
# Using curl:
# curl -X GET "https://cleantempmail.com/api/stats" \
#      -H "X-API-Key: ct-test"
```

--------------------------------

### Retrieve Emails for an Address (Python)

Source: https://context7.com/cleantempmail/cleantempmail-python-examples/llms.txt

Fetches all emails received by a specified temporary email address using a GET request. Returns up to 500 recent emails sorted by timestamp. Requires the email address as a query parameter.

```python
import json
import urllib.request
import urllib.parse
from datetime import datetime

API_KEY = "ct-test"
BASE_URL = "https://cleantempmail.com/api"

email_address = "mytest@tempmail.com"
params = urllib.parse.urlencode({"email": email_address})
url = f"{BASE_URL}/emails?{params}"
headers = {"X-API-Key": API_KEY}

req = urllib.request.Request(url, headers=headers)

with urllib.request.urlopen(req) as response:
    data = json.loads(response.read().decode())

    if data.get("success"):
        emails = data["data"]["emails"]
        print(f"Found {len(emails)} email(s)")

        for email in emails:
            print(f"From: {email['from_address']}")
            print(f"Subject: {email['subject']}")
            print(f"Content: {email.get('content', 'No content')}")
            timestamp = datetime.fromtimestamp(email.get('timestamp', 0))
            print(f"Date: {timestamp.strftime('%Y-%m-%d %H:%M:%S')}")
```

```bash
# Using curl:
# curl -X GET "https://cleantempmail.com/api/emails?email=mytest@tempmail.com" \
#      -H "X-API-Key: ct-test"
```

--------------------------------

### Generate Random Temporary Email

Source: https://context7.com/cleantempmail/cleantempmail-python-examples/llms.txt

Generates a random temporary email address. The email is active immediately and can start receiving messages.

```APIDOC
## Generate Random Temporary Email

### Description
Generates a random temporary email address instantly. The email is active immediately and can start receiving messages.

### Method
GET

### Endpoint
/api/generate-email

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Your API key for authentication.

### Request Example
```bash
curl -X GET "https://cleantempmail.com/api/generate-email" \
     -H "X-API-Key: ct-test"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the generated email details.
  - **email** (string) - The generated temporary email address.

#### Response Example
```json
{
  "success": true,
  "data": {
    "email": "abc123xyz@tempmail.com"
  }
}
```
```

--------------------------------

### Get Single Email by ID

Source: https://context7.com/cleantempmail/cleantempmail-python-examples/llms.txt

Retrieves the full details of a specific email using its unique ID.

```APIDOC
## Get Single Email by ID

### Description
Retrieves the full details of a specific email using its unique ID.

### Method
GET

### Endpoint
/api/email/{email_id}

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Your API key for authentication.

#### Path Parameters
- **email_id** (string) - Required - The unique identifier of the email to retrieve.

### Request Example
```bash
curl -X GET "https://cleantempmail.com/api/email/abc123" \
     -H "X-API-Key: ct-test"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the details of the specific email.
  - **subject** (string) - The subject of the email.
  - **from_address** (string) - The sender's email address.
  - **content** (string) - The body of the email.
  - **timestamp** (integer) - The Unix timestamp when the email was received.

#### Response Example
```json
{
  "success": true,
  "data": {
    "subject": "Welcome!",
    "from_address": "noreply@example.com",
    "content": "Thank you for signing up.",
    "timestamp": 1678886500
  }
}
```
```

--------------------------------

### Get Top Email Subjects

Source: https://context7.com/cleantempmail/cleantempmail-python-examples/llms.txt

Retrieves the most common email subjects in the system for analytics purposes. Requires the API key.

```python
import json
import urllib.request

API_KEY = "ct-test"
BASE_URL = "https://cleantempmail.com/api"

url = f"{BASE_URL}/statistics/top-subjects"
headers = {"X-API-Key": API_KEY}

req = urllib.request.Request(url, headers=headers)

with urllib.request.urlopen(req) as response:
    data = json.loads(response.read().decode())

    if data.get("success"):
        subjects = data["data"][:5]  # Top 5
        for i, item in enumerate(subjects, 1):
            print(f"{i}. {item['subject']} ({item['count']} emails)")
```

```bash
# Using curl:
# curl -X GET "https://cleantempmail.com/api/statistics/top-subjects" \
#      -H "X-API-Key: ct-test"
```

--------------------------------

### Initialize Git Repository

Source: https://github.com/cleantempmail/cleantempmail-python-examples/blob/main/QUICK_START.md

Initialize a Git repository in the project directory and prepare for pushing to GitHub. This involves setting up the remote origin and committing initial files.

```bash
cd python-examples
git init
git add .
git commit -m "Initial commit: CleanTempMail Python examples"
git branch -M main
git remote add origin https://github.com/cleantempmail/cleantemp mail-python-examples.git
git push -u origin main
```

--------------------------------

### Use Client Class Demo

Source: https://github.com/cleantempmail/cleantempmail-python-examples/blob/main/QUICK_START.md

Run a Python script that utilizes the reusable client class for CleanTempMail API interactions.

```bash
python3 example_client.py
```

--------------------------------

### Using the Python Client Class

Source: https://context7.com/cleantempmail/cleantempmail-python-examples/llms.txt

This class provides an object-oriented interface for API operations, including email generation, retrieval, deletion, inbox clearing, statistics, and waiting for new emails. Initialize the client with your API key.

```python
from cleantempmail import CleanTempMailClient

# Initialize client
client = CleanTempMailClient(api_key="ct-test")

# Generate random email
email = client.generate_email()
print(f"Generated: {email}")

# Generate custom email
custom_email = client.generate_email(prefix="mytest", domain="example.com")
print(f"Custom: {custom_email}")

# Get emails
emails = client.get_emails(email)
print(f"Inbox has {len(emails)} emails")

# Get single email
if emails:
    email_detail = client.get_email(emails[0]['id'])
    print(f"Subject: {email_detail['subject']}")

# Delete single email
if emails:
    success = client.delete_email(emails[0]['id'])
    print(f"Deleted: {success}")

# Clear inbox
count = client.clear_inbox(email)
print(f"Cleared {count} emails")

# Get statistics
stats = client.get_statistics()
print(f"Total emails in system: {stats.get('total_emails', 0)}")

# Get top subjects
top_subjects = client.get_top_subjects(limit=5)
for item in top_subjects:
    print(f"{item['subject']}: {item['count']} emails")

# Wait for new email with timeout
new_email = client.wait_for_email(email, timeout=60, interval=5)
if new_email:
    print(f"New email from: {new_email['from_address']}")

```

--------------------------------

### Generate Custom Email with Prefix

Source: https://context7.com/cleantempmail/cleantempmail-python-examples/llms.txt

Creates a temporary email address with a custom prefix and optionally a specific domain. The prefix must be 3-20 characters long.

```APIDOC
## Generate Custom Email with Prefix

### Description
Creates a temporary email with a custom prefix and optionally a specific domain. Prefix must be 3-20 characters using letters, numbers, dots, hyphens, or underscores.

### Method
POST

### Endpoint
/api/generate-email

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Your API key for authentication.

#### Request Body
- **prefix** (string) - Required - The desired prefix for the email address (3-20 characters).
- **domain** (string) - Optional - A specific domain to use for the email address.

### Request Example
```json
{
  "prefix": "mytest",
  "domain": "example.com"
}
```

```bash
curl -X POST "https://cleantempmail.com/api/generate-email" \
     -H "X-API-Key: ct-test" \
     -H "Content-Type: application/json" \
     -d '{"prefix": "mytest"}'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the generated email details.
  - **email** (string) - The generated temporary email address.

#### Response Example
```json
{
  "success": true,
  "data": {
    "email": "mytest@tempmail.com"
  }
}
```
```

--------------------------------

### Generate Random Temporary Email (Python)

Source: https://context7.com/cleantempmail/cleantempmail-python-examples/llms.txt

Use this Python script to generate a random temporary email address. Requires the 'X-API-Key' header for authentication. The generated email is immediately active.

```python
import json
import urllib.request

API_KEY = "ct-test"
BASE_URL = "https://cleantempmail.com/api"

url = f"{BASE_URL}/generate-email"
headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

req = urllib.request.Request(url, headers=headers)

with urllib.request.urlopen(req) as response:
    data = json.loads(response.read().decode())

    if data.get("success"):
        email = data["data"]["email"]
        print(f"Generated: {email}")
        # Output: Generated: abc123xyz@tempmail.com
```

```bash
# Using curl:
# curl -X GET "https://cleantempmail.com/api/generate-email" \
#      -H "X-API-Key: ct-test"
```

--------------------------------

### Generate Custom Temporary Email (Python)

Source: https://context7.com/cleantempmail/cleantempmail-python-examples/llms.txt

This Python script generates a temporary email address with a custom prefix. You can also specify a domain. The prefix must be 3-20 characters. POST request with JSON payload is used.

```python
import json
import urllib.request

API_KEY = "ct-test"
BASE_URL = "https://cleantempmail.com/api"

data = {"prefix": "mytest"}  # Optional: add "domain": "example.com"

url = f"{BASE_URL}/generate-email"
headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

json_data = json.dumps(data).encode('utf-8')
req = urllib.request.Request(url, data=json_data, headers=headers, method='POST')

with urllib.request.urlopen(req) as response:
    result = json.loads(response.read().decode())

    if result.get("success"):
        email = result["data"]["email"]
        print(f"Generated: {email}")
        # Output: Generated: mytest@tempmail.com
```

```bash
# Using curl:
# curl -X POST "https://cleantempmail.com/api/generate-email" \
#      -H "X-API-Key: ct-test" \
#      -H "Content-Type: application/json" \
#      -d '{"prefix": "mytest"}'
```

--------------------------------

### Retrieve Emails for an Address

Source: https://context7.com/cleantempmail/cleantempmail-python-examples/llms.txt

Fetches all emails received by a specific temporary email address. Returns up to 500 recent emails sorted by timestamp (newest first).

```APIDOC
## Retrieve Emails for an Address

### Description
Fetches all emails received by a specific temporary email address. Returns up to 500 recent emails sorted by timestamp (newest first).

### Method
GET

### Endpoint
/api/emails

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Your API key for authentication.

#### Query Parameters
- **email** (string) - Required - The temporary email address to retrieve emails for.

### Request Example
```bash
curl -X GET "https://cleantempmail.com/api/emails?email=mytest@tempmail.com" \
     -H "X-API-Key: ct-test"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the list of emails.
  - **emails** (array) - An array of email objects.
    - **from_address** (string) - The sender's email address.
    - **subject** (string) - The subject of the email.
    - **content** (string) - The body of the email (may be null).
    - **timestamp** (integer) - The Unix timestamp when the email was received.

#### Response Example
```json
{
  "success": true,
  "data": {
    "emails": [
      {
        "from_address": "sender@example.com",
        "subject": "Test Email",
        "content": "This is the body of the test email.",
        "timestamp": 1678886400
      }
    ]
  }
}
```
```

--------------------------------

### Extract Verification Codes from Emails

Source: https://context7.com/cleantempmail/cleantempmail-python-examples/llms.txt

This script uses regular expressions to find common verification code formats within email subjects and content. It prioritizes 6-digit codes when multiple formats are found. Ensure the API key and base URL are correctly configured.

```python
import json
import urllib.request
import urllib.parse
import re

API_KEY = "ct-test"
BASE_URL = "https://cleantempmail.com/api"

PATTERNS = [
    r'\b\d{6}\b',                          # 6-digit code
    r'\b\d{4}\b',                          # 4-digit code
    r'\b[A-Z0-9]{8}\b',                    # 8-character alphanumeric
    r'code[:\s]+([A-Z0-9-]{4,})',          # After "code:"
    r'verification[:\s]+([A-Z0-9-]{4,})',  # After "verification:"
]

def extract_codes(text):
    codes = []
    for pattern in PATTERNS:
        matches = re.findall(pattern, text, re.IGNORECASE)
        codes.extend(matches)
    return list(set(codes))  # Remove duplicates

def find_verification_codes(email_address):
    params = urllib.parse.urlencode({"email": email_address})
    url = f"{BASE_URL}/emails?{params}"
    headers = {"X-API-Key": API_KEY}
    req = urllib.request.Request(url, headers=headers)

    with urllib.request.urlopen(req) as response:
        data = json.loads(response.read().decode())

        if data.get("success"):
            for email in data["data"]["emails"]:
                text = f"{email['subject']} {email.get('content', '')}"
                codes = extract_codes(text)

                if codes:
                    print(f"Email: {email['subject']}")
                    print(f"Codes found: {', '.join(codes)}")

                    # Prefer 6-digit codes
                    six_digit = [c for c in codes if re.match(r'^\d{6}$', c)]
                    if six_digit:
                        return six_digit[0]
    return None

# Usage
code = find_verification_codes("mytest@tempmail.com")
if code:
    print(f"Verification code: {code}")

```

--------------------------------

### Auto-Poll for New Emails

Source: https://context7.com/cleantempmail/cleantempmail-python-examples/llms.txt

Continuously monitors an inbox for new emails with configurable polling interval and timeout. Requires the email address and API key.

```python
import json
import urllib.request
import urllib.parse
import time

API_KEY = "ct-test"
BASE_URL = "https://cleantempmail.com/api"

def get_emails(email_address):
    params = urllib.parse.urlencode({"email": email_address})
    url = f"{BASE_URL}/emails?{params}"
    headers = {"X-API-Key": API_KEY}
    req = urllib.request.Request(url, headers=headers)

    try:
        with urllib.request.urlopen(req) as response:
            data = json.loads(response.read().decode())
            if data.get("success"):
                return data["data"]["emails"]
    except:
        pass
    return []

def wait_for_email(email_address, timeout=60, interval=5):
    """Wait for a new email to arrive."""
    initial_emails = get_emails(email_address)
    initial_ids = {e['id'] for e in initial_emails}

    start_time = time.time()

    while time.time() - start_time < timeout:
        time.sleep(interval)
        current_emails = get_emails(email_address)

        for email in current_emails:
            if email['id'] not in initial_ids:
                return email  # New email found

    return None  # Timeout

# Usage
email_address = "mytest@tempmail.com"
print(f"Waiting for email to: {email_address}")
new_email = wait_for_email(email_address, timeout=120, interval=5)

if new_email:
    print(f"Received: {new_email['subject']}")
else:
    print("No email received within timeout")
```

--------------------------------

### Clear Entire Inbox

Source: https://context7.com/cleantempmail/cleantempmail-python-examples/llms.txt

Deletes all emails for a specific temporary email address. Returns the count of deleted emails. Requires the email address and API key.

```python
import json
import urllib.request
import urllib.parse

API_KEY = "ct-test"
BASE_URL = "https://cleantempmail.com/api"

email_address = "mytest@tempmail.com"
params = urllib.parse.urlencode({"email": email_address})
url = f"{BASE_URL}/emails/clear?{params}"
headers = {"X-API-Key": API_KEY}

req = urllib.request.Request(url, headers=headers, method='DELETE')

with urllib.request.urlopen(req) as response:
    data = json.loads(response.read().decode())

    if data.get("success"):
        count = data["data"].get("count", 0)
        print(f"Deleted {count} email(s)")
```

```bash
# Using curl:
# curl -X DELETE "https://cleantempmail.com/api/emails/clear?email=mytest@tempmail.com" \
#      -H "X-API-Key: ct-test"
```

--------------------------------

### Delete Single Email

Source: https://context7.com/cleantempmail/cleantempmail-python-examples/llms.txt

Removes a specific email from the inbox using its ID. Requires the email ID and API key.

```python
import json
import urllib.request

API_KEY = "ct-test"
BASE_URL = "https://cleantempmail.com/api"

email_id = "abc123"
url = f"{BASE_URL}/email/{email_id}"
headers = {"X-API-Key": API_KEY}

req = urllib.request.Request(url, headers=headers, method='DELETE')

with urllib.request.urlopen(req) as response:
    data = json.loads(response.read().decode())

    if data.get("success"):
        print(f"Email {email_id} deleted successfully")
```

```bash
# Using curl:
# curl -X DELETE "https://cleantempmail.com/api/email/abc123" \
#      -H "X-API-Key: ct-test"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.