CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

EmailGen is a Dockerized framework for automating email account creation and testing across multiple email providers. Each provider runs in a Debian 13 Docker container with browser automation capabilities.

Current Implementation Status

All 5 providers are fully implemented with Playwright-based browser automation:

Fully Implemented Providers

ProtonMail (494 lines): Complete with advanced CAPTCHA handling (OCR/API), account creation, inbox access
tmail (430 lines): Disposable email with instant address generation, inbox monitoring, sending tests
Guerrilla Mail (380 lines): Temporary email generation, inbox access, email list extraction
Mailinator (339 lines): Public inbox access, email monitoring, no signup required
AtomicMail (275 lines): Full account creation with CAPTCHA detection, inbox access, and sending capabilities.

All implemented providers include:

Full Playwright browser automation with stealth settings
Screenshot capture at key steps
Comprehensive error handling
Standard result.json output format
Docker containerization with proper dependencies

Common Development Commands

Running a Provider

# Navigate to provider directory
cd providers/<provider_name>

# Copy and configure environment
cp .env.example .env
# Edit .env with required values

# Build and run the container
./run.sh

# Results appear in:
# - artifacts/ directory (logs, screenshots)
# - result.json (copied to provider root)

Testing Individual Providers

# Quick test without Docker (requires local Python environment)
cd providers/<provider_name>
pip3 install -r requirements.txt
python3 main.py

# Docker-based testing with environment override
docker build -t test-provider .
docker run --rm --env RUN_ID=test-123 -v "$(pwd)/artifacts:/app/artifacts" test-provider

Architecture Overview

Provider Structure Pattern

All providers follow an identical directory structure and execution model:

Container-based Execution: Each provider runs in a Debian 13 Docker container with Playwright for browser automation
Standardized Interface: All
```
main.py
```
files produce a uniform
```
result.json
```
output format
Artifact Collection: Screenshots, logs, and results are persisted to
```
artifacts/
```
directory
Environment Configuration:
```
.env
```
files control runtime behavior (proxies, CAPTCHA API keys, run IDs)

Result JSON Schema

Every provider must output this standard format:

{
  "provider": "string",
  "type": "personal|disposable|less_reliable",
  "account_identifier": "email@domain",
  "encountered": {
    "captcha": boolean,
    "sms_required": boolean,
    "payment_required": boolean
  },
  "signup_duration_sec": number,
  "verification_received": boolean,
  "sending_supported": boolean,
  "errors": [],
  "notes": "string"
}

Browser Automation Pattern

All providers use Playwright for automation with this common setup:

Headless/headful mode configurable via environment
Screenshot capture at key steps
Network request logging for debugging
Cookie/session persistence for multi-step flows

Implementation Guidelines

When Adding New Provider Support

Copy existing provider directory structure exactly
Maintain the same Dockerfile base image (debian:stable-slim)
Include Playwright in requirements.txt
Implement standard result.json output format
Capture screenshots at: signup form, CAPTCHA, inbox view, errors
Handle timeouts gracefully (default 10 minutes for verification)

Handling CAPTCHAs (ProtonMail Focus)

The ProtonMail provider includes special CAPTCHA handling:

Tesseract OCR for text extraction (already in Dockerfile)
Pillow for image processing
Optional third-party solver integration via CAPTCHA_API_KEY
Document all CAPTCHA solving attempts in result.json

Docker Build Optimization

Base image: debian:stable-slim (not full debian:13)
Install only required system packages
Use pip3 install with --no-cache-dir flag
Create artifacts directory in Dockerfile to avoid permission issues

Key Implementation Challenges

Browser Automation Gotchas

Playwright requires additional system dependencies for Debian (handled in Dockerfile)
Some providers detect automated browsers - use stealth techniques
Session management across container restarts requires cookie persistence

Provider-Specific Challenges

ProtonMail: Complex CAPTCHA system, requires OCR/AI models
Disposable providers: May have API endpoints alongside web UI
Rate limiting: All providers implement some form of rate limiting
IP reputation: Some providers block datacenter IPs

Testing Workflow

Start with stub implementation (current state)
Implement browser automation incrementally
Test each step with screenshot capture
Validate result.json format
Document specific provider quirks in provider README

Environment Variables

Standard across all providers:

```
RUN_ID
```
: Unique identifier for tracking runs
```
HTTP_PROXY
```
/
```
HTTPS_PROXY
```
: Optional proxy configuration
```
CAPTCHA_API_KEY
```
: Third-party CAPTCHA solver credentials

Provider-specific variables should be documented in each provider's README.md.

Debugging Commands

# View container logs
docker logs emailgen-<provider>

# Interactive container shell
docker run -it --entrypoint /bin/bash <image_tag>

# Check artifacts without running full flow
ls -la providers/<provider>/artifacts/

# Validate result.json format
python3 -m json.tool providers/<provider>/result.json

Implementation Patterns

Playwright Setup Example

from playwright.sync_api import sync_playwright
import os

def setup_browser():
    playwright = sync_playwright().start()
    browser = playwright.chromium.launch(
        headless=os.getenv("HEADLESS", "true").lower() == "true",
        args=['--disable-blink-features=AutomationControlled']  # Stealth mode
    )
    context = browser.new_context(
        viewport={'width': 1920, 'height': 1080},
        user_agent='Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36'
    )
    page = context.new_page()
    return playwright, browser, context, page

# Always capture screenshots at key steps
page.screenshot(path=f"{ARTIFACTS_DIR}/step_1_signup.png")

CAPTCHA Handling Pattern (ProtonMail)

import pytesseract
from PIL import Image

def handle_captcha(page, artifacts_dir):
    # 1. Capture CAPTCHA screenshot
    captcha_path = f"{artifacts_dir}/captcha.png"
    page.screenshot(path=captcha_path)

    # 2. Try OCR with Tesseract (included in Dockerfile)
    try:
        text = pytesseract.image_to_string(Image.open(captcha_path))
        if text:
            return text.strip()
    except Exception as e:
        print(f"OCR failed: {e}")

    # 3. Fall back to API if available
    api_key = os.getenv("CAPTCHA_API_KEY")
    if api_key:
        # Integrate third-party solver
        pass

    return None

Inbox Verification Pattern

def wait_for_verification_email(page, timeout=600):
    """Wait for email with configurable timeout (default 10 min)"""
    start_time = time.time()

    while time.time() - start_time < timeout:
        # Navigate to inbox or refresh
        page.reload()

        # Check for verification email
        if page.locator('text="Verify your email"').count() > 0:
            page.screenshot(path=f"{ARTIFACTS_DIR}/verification_received.png")
            return True, time.time() - start_time

        time.sleep(10)  # Poll every 10 seconds

    return False, None

VS Code Workspace Integration

The repository includes

emailgen.code-workspace

with AI-friendly settings:

Disabled auto-formatting: Prevents conflicts with AI code generation
3-second auto-save delay: Avoids interrupting AI tools
Pre-configured tasks: Press
```
Cmd+K Cmd+R
```
to run current provider
Debug configurations: Python debugging with .env loading

Claude Code Permissions

Located in

.claude/settings.local.json

, pre-configured to allow:

File operations in provider directories
Docker build and run commands
Artifact inspection

Testing Checklist

When implementing a provider, ensure:

Dockerfile builds successfully
run.sh executes without errors
Screenshots captured at key steps (signup, CAPTCHA, inbox)
result.json follows the required schema
Error handling for network failures
Timeout configuration respected
Environment variables documented in provider README
Artifacts properly saved to artifacts/ directory

Common Pitfalls to Avoid

Missing Playwright dependencies: The Dockerfile needs system packages for Playwright
Detection by anti-bot systems: Use stealth browser arguments and realistic user agents
Hardcoded timeouts: Always use configurable environment variables
Missing screenshots: Capture at every major step for debugging
Schema violations: Validate result.json format before writing
Credential leaks: Never commit .env files, use .env.example as template

Provider-Specific Notes

Personal Email Providers

ProtonMail (Most Complex)

Requires CAPTCHA handling with OCR/AI
Rate limiting is aggressive
May need proxy rotation for multiple attempts

AtomicMail (Encrypted Provider)

End-to-end encryption like ProtonMail
No phone verification required
Has AI features (summarization, TTS)
Free tier available
May encounter CAPTCHA during signup

Disposable Email Providers

tmail, Guerrilla Mail: No signup required, just navigate to inbox
Focus on receive-only: Most don't support sending

Less Reliable Providers

Mailinator: Public inboxes, no authentication
Auto-generated addresses: Don't require account creation