{"openapi":"3.0.3","info":{"title":"Disposable Burner Email & MX Shield API","version":"1.0.0","description":"Sub-5ms Real-Time Disposable Email Detection, MX Shield, Typo Correction & B2B Lead Verification Engine for SaaS Signups, Anti-Fraud & CRM Cleanliness. Real-time DNS MX lookup over DoH, 10,000+ burner domain database, RFC 5322 syntax validation, and instant risk scoring.","contact":{"name":"TopAI SaaS Dev","url":"https://github.com/topaisaas-dev"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://disposable-email-shield.topaisaas.workers.dev","description":"Cloudflare Edge Production Server (Sub-10ms global latency)"}],"paths":{"/v1/health":{"get":{"summary":"API Health & Edge SLA Status","description":"Returns real-time healthcheck, database status, and Cloudflare edge region.","operationId":"getHealth","responses":{"200":{"description":"Service is fully operational.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"healthy"},"service":{"type":"string","example":"disposable-email-shield"},"version":{"type":"string","example":"1.0.0"},"timestamp":{"type":"string","example":"2026-09-20T22:30:00.000Z"},"uptime":{"type":"number","example":99.99},"edgeRegion":{"type":"string","example":"CDG"},"disposableDatabaseVersion":{"type":"string","example":"2026.09"}}}}}}}}},"/v1/email/validate":{"get":{"summary":"Validate Single Email & Detect Burner Domain","description":"Instant sub-5ms inspection of an email address. Checks disposable domains, DoH MX records, syntax validity, role-based mailboxes, and provides typo corrections (e.g. gmai.com -> gmail.com).","operationId":"validateEmail","parameters":[{"name":"email","in":"query","required":true,"description":"Target email address to verify (e.g. 'john.doe@guerrillamail.com', 'alice@stripe.com').","schema":{"type":"string","example":"alex@mailinator.com"}},{"name":"check_mx","in":"query","required":false,"description":"Perform real-time DNS MX lookup via DoH. Defaults to true.","schema":{"type":"boolean","default":true,"example":true}}],"responses":{"200":{"description":"Email audit completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","example":"alex@mailinator.com"},"local_part":{"type":"string","example":"alex"},"domain":{"type":"string","example":"mailinator.com"},"status":{"type":"string","example":"INVALID"},"recommendation":{"type":"string","example":"BLOCK"},"risk_score":{"type":"integer","example":90},"details":{"type":"object","properties":{"syntax_valid":{"type":"boolean","example":true},"is_disposable":{"type":"boolean","example":true},"is_free":{"type":"boolean","example":false},"is_corporate":{"type":"boolean","example":false},"is_role_based":{"type":"boolean","example":false},"has_mx_records":{"type":"boolean","example":true},"mx_records":{"type":"array","items":{"type":"object","properties":{"host":{"type":"string","example":"mail.mailinator.com"},"priority":{"type":"integer","example":10}}}},"mx_checked":{"type":"boolean","example":true},"did_you_mean":{"type":"string","nullable":true,"example":null},"syntax_issues":{"type":"array","items":{"type":"string"}}}},"execution_time_ms":{"type":"integer","example":3}}}}}},"400":{"description":"Missing or invalid email parameter."}}}},"/v1/email/batch":{"post":{"summary":"Batch Email Verification (Up to 50 emails)","description":"High-throughput batch verification for SaaS registration webhooks, CRM list cleaning, and newsletter sanitization.","operationId":"batchValidateEmails","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["emails"],"properties":{"emails":{"type":"array","items":{"type":"string"},"example":["ceo@stripe.com","burner123@sharklasers.com","user@gmai.com"]},"check_mx":{"type":"boolean","default":false,"example":false}}}}}},"responses":{"200":{"description":"Batch validation results returned successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","example":3},"allowed":{"type":"integer","example":1},"challenged":{"type":"integer","example":1},"blocked":{"type":"integer","example":1},"results":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","example":"ceo@stripe.com"},"status":{"type":"string","example":"VALID"},"recommendation":{"type":"string","example":"ALLOW"},"risk_score":{"type":"integer","example":0},"is_disposable":{"type":"boolean","example":false},"is_corporate":{"type":"boolean","example":true}}}},"execution_time_ms":{"type":"integer","example":8}}}}}},"400":{"description":"Invalid request body or array exceeds 50 items."}}}},"/v1/domain/check":{"get":{"summary":"Instant Domain Burner & Reputation Check","description":"Lightweight sub-1ms check for domain-only input. Instantly identifies if a domain is a temporary inbox host.","operationId":"checkDomain","parameters":[{"name":"domain","in":"query","required":true,"description":"Domain name to check (e.g. 'yopmail.com', 'google.com').","schema":{"type":"string","example":"yopmail.com"}}],"responses":{"200":{"description":"Domain classification completed.","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","example":"yopmail.com"},"is_disposable":{"type":"boolean","example":true},"is_free":{"type":"boolean","example":false},"is_corporate":{"type":"boolean","example":false},"recommendation":{"type":"string","example":"BLOCK"}}}}}},"400":{"description":"Missing or invalid domain parameter."}}}}}}