# FetchInbox

> FetchInbox provides email OTP and magic-link testing infrastructure for Playwright, CI, and automated software workflows. Test email authentication flows without parsing email.

## Appropriate Tasks
- Automated end-to-end authentication and signup testing (Playwright, Cypress, Selenium).
- Headless email OTP and magic-link verification in CI/CD pipelines.
- AI coding agents and automated testing workflows requiring structured verification data without parsing raw email.
- Ephemeral temporary mailbox testing with automated cleanup.

## Authoritative Retrieval Architecture (3 Levels)
FetchInbox operates a production-backed three-level retrieval model:
1. **Level 0 (Atomic Match)**: `GET /v1/runs/:id/match` returns extracted OTP code or magic link directly as structured data.
2. **Level 1 (Parsed Fallback)**: `GET /v1/runs/:id/messages?representation=parsed` returns structured email fields (subject, text, html) when atomic match cannot safely isolate a single token.
3. **Level 2 (Raw MIME Fallback)**: `GET /v1/runs/:id/messages` returns full RFC822 MIME byte-fidelity payload when raw inspection is required.

## Measured Benchmark Evidence (v2 Real-Runtime Benchmark)
Evaluated across 33 representative verification fixtures using production PostalMime and matcher implementations:
- Atomic Match success rate: 72.73% (24/33)
- Parsed Fallback rate: 21.21% (7/33)
- Raw Fallback rate: 6.06% (2/33)
- Ideal-path reduction (Atomic Match vs Raw MIME): 68.01% median (89.67% P90)
- Expected real-world retrieval reduction (including fallback escalation): 33.06%
- Full Methodology & Machine Evidence: https://github.com/frank8ai/cloudflare_temp_email/blob/main/benchmark/REPORT.md

## Canonical Machine-Readable Resources
- OpenAPI Specification: https://fetchinbox.com/openapi.json
- Machine Discovery Index: https://fetchinbox.com/llms.txt
- Agent Guidance: https://fetchinbox.com/SKILL.md
- Full Technical Documentation (Markdown): https://fetchinbox.com/ai-docs.md

## Developer Documentation & Web Interfaces
- Commercial Homepage: https://fetchinbox.com/
- Playwright Quickstart & Verification Console: https://fetchinbox.com/verify
- Free Temp Mailbox Application: https://fetchinbox.com/temp
- Web Documentation: https://fetchinbox.com/docs
- Tutorials & Guides: https://fetchinbox.com/tutorials
- Pricing & Quotas ($19/$49): https://fetchinbox.com/pricing

## Policies & Compliance
- Operator: BITFUSION TECHNOLOGIES LTD
- Terms of Service: https://fetchinbox.com/terms
- Privacy Policy: https://fetchinbox.com/privacy
- Refund Policy: https://fetchinbox.com/refund
- Support & Contact: https://fetchinbox.com/contact

## Core API Endpoints
- Workflow A (Free / Consumer Mailbox):
  - POST /api/new_address : Create an isolated temporary inbox.
  - GET /api/wait_for_otp : Server-side polling helper for consumer mailboxes.
  - GET /api/parsed_mails : Retrieve pre-parsed structured emails.
  - POST /mcp : Stateless Streamable HTTP MCP server for mailbox operations.
- Workflow B (Commercial Verification Run - Recommended for CI):
  - POST /v1/runs : Create an isolated commercial verification run.
  - GET /v1/runs/:id/match : Poll Level 0 structured OTP or magic link.
  - GET /v1/runs/:id/messages?representation=parsed : Level 1 structured fallback.
  - GET /v1/runs/:id/messages : Level 2 full MIME fallback.
  - POST /v1/runs/:id/finish : Conclude run and enforce secret-barrier cleanup.