EmailGen Provider Implementation

Expert assistant for developing email provider automation scripts in the EmailGen framework - a Dockerized system for automated email account creation and testing across multiple providers.

What This Skill Does

This skill helps you implement, test, and debug email provider automation scripts within the EmailGen framework. It understands the standardized architecture, Docker containerization patterns, Playwright browser automation, CAPTCHA handling, and the required output formats.

When to Use This Skill

Instructions

1. Understand the Provider Architecture

Before implementing or modifying any provider:

2. Standard Result JSON Schema

Every provider MUST produce this exact format:

```json

{

"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"

}

```

3. Implementing a New Provider

Follow this sequence:

**Step 1: Create Directory Structure**

```bash

cd providers/<provider_name>

Ensure these files exist:

- Dockerfile (debian:stable-slim base)

- main.py (Playwright automation)

- requirements.txt (playwright, pillow, pytesseract)

- run.sh (build and run script)

- .env.example (template for env vars)

- README.md (provider-specific docs)

```

**Step 2: Implement Browser Automation**

Use this standard Playwright setup pattern:

```python

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']

)

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

```

**Step 3: Capture Screenshots at Key Steps**

```python

ARTIFACTS_DIR = "/app/artifacts"

page.screenshot(path=f"{ARTIFACTS_DIR}/step_1_signup.png")

page.screenshot(path=f"{ARTIFACTS_DIR}/captcha.png")

page.screenshot(path=f"{ARTIFACTS_DIR}/inbox.png")

```

**Step 4: Handle CAPTCHAs (ProtonMail Pattern)**

```python

import pytesseract

from PIL import Image

def handle_captcha(page, artifacts_dir):

captcha_path = f"{artifacts_dir}/captcha.png"

page.screenshot(path=captcha_path)

# Try OCR first

try:

text = pytesseract.image_to_string(Image.open(captcha_path))

if text:

return text.strip()

except Exception as e:

print(f"OCR failed: {e}")

# Fall back to API if available

api_key = os.getenv("CAPTCHA_API_KEY")

if api_key:

# Integrate third-party solver

pass

return None

```

**Step 5: Implement Inbox Verification**

```python

def wait_for_verification_email(page, timeout=600):

start_time = time.time()

while time.time() - start_time < timeout:

page.reload()

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)

return False, None

```

**Step 6: Write Result JSON**

```python

import json

result = {

"provider": "provider_name",

"type": "personal",

"account_identifier": email_address,

"encountered": {

"captcha": captcha_encountered,

"sms_required": False,

"payment_required": False

},

"signup_duration_sec": duration,

"verification_received": verified,

"sending_supported": True,

"errors": [],

"notes": "Additional context"

}

with open("/app/result.json", "w") as f:

json.dump(result, f, indent=2)

```

4. Testing Workflow

**Quick Local Test (without Docker):**

```bash

cd providers/<provider_name>

pip3 install -r requirements.txt

python3 main.py

```

**Full Docker Test:**

```bash

cd providers/<provider_name>

cp .env.example .env

Edit .env with required values

./run.sh

Check results

cat result.json

ls -la artifacts/

```

**Interactive Debugging:**

```bash

docker run -it --entrypoint /bin/bash <image_tag>

```

5. Common Debugging Commands

```bash

View container logs

docker logs emailgen-<provider>

Check artifacts without running full flow

ls -la providers/<provider>/artifacts/

Validate result.json format

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

Test with custom environment

docker run --rm --env RUN_ID=test-123 -v "$(pwd)/artifacts:/app/artifacts" <image>

```

6. Environment Variables

Standard across all providers:

7. Implementation Checklist

Before considering a provider complete:

8. Common Pitfalls to Avoid

1. **Missing Playwright dependencies**: Dockerfile needs system packages for Chromium

2. **Anti-bot detection**: Use stealth browser arguments and realistic user agents

3. **Hardcoded timeouts**: Always use configurable environment variables

4. **Missing screenshots**: Capture at every major step for debugging

5. **Schema violations**: Validate result.json format before writing

6. **Credential leaks**: Never commit .env files

Provider-Specific Notes

Personal Email Providers

Disposable Email Providers

Less Reliable Providers

Example Usage

**Scenario 1: Implement new provider**

```

User: "Add support for temp-mail.org provider"

Assistant: [Creates directory structure, implements Playwright automation following patterns, adds CAPTCHA detection, writes result.json]

```

**Scenario 2: Debug existing provider**

```

User: "ProtonMail provider is failing at CAPTCHA step"

Assistant: [Checks artifacts/captcha.png, reviews OCR implementation, suggests API fallback, tests with docker run]

```

**Scenario 3: Validate implementation**

```

User: "Check if atomicmail provider follows all standards"

Assistant: [Runs implementation checklist, validates result.json schema, checks screenshot capture, reviews error handling]

```

Key Files Reference

Important Constraints