{"openapi":"3.0.3","info":{"title":"EmailCheck API","version":"1.0.0","description":"Validate email addresses before you send, store or bill for them.\n\nEvery call runs a syntax pass, live DNS lookups (MX + A/AAAA), a 10,000+ domain disposable-mailbox blocklist, role-account detection, free-provider detection, typo suggestions and a 0-100 deliverability score with human readable reasons.\n\n**Honest scope:** no SMTP handshake happens at the edge, so the API tells you whether the *domain* accepts mail and how risky the *address* looks. It does not claim to prove that a specific mailbox exists. Results are cached at the edge for 10 minutes to keep latency low.\n\n**Built for:** signup forms, lead qualification, CRM hygiene, bulk list cleaning, fraud checks.","termsOfService":"https://example.com/terms","contact":{"name":"Ayam Labs","url":"https://github.com/ayam04","email":"ayamullahkhan04@gmail.com"}},"servers":[{"url":"https://emailcheck.ayamk.in","description":"Direct origin"},{"url":"https://rapidapi.com","description":"RapidAPI marketplace"}],"tags":[{"name":"Verification","description":"Address level checks"},{"name":"Domain","description":"Domain level email infrastructure"}],"x-provider":"Ayam Labs","components":{"schemas":{"EmailVerification":{"type":"object","properties":{"email":{"type":"string","example":"jane.doe+newsletter@gmail.com"},"normalized":{"type":"string","nullable":true,"example":"jane.doe+newsletter@gmail.com"},"canonical":{"type":"string","nullable":true,"example":"janedoe@gmail.com","description":"Deduplication form: sub-address and Gmail dots removed."},"validFormat":{"type":"boolean","example":true},"localPart":{"type":"string","nullable":true,"example":"jane.doe+newsletter"},"domain":{"type":"string","nullable":true,"example":"gmail.com"},"score":{"type":"number","minimum":0,"maximum":100,"example":88,"description":"Risk score. 100 = cleanest possible signal."},"deliverability":{"type":"string","enum":["deliverable","risky","undeliverable","unknown"],"description":"Overall verdict. Based on DNS + address heuristics; mailbox existence is not confirmed."},"flags":{"$ref":"#/components/schemas/AddressFlags"},"provider":{"type":"string","nullable":true,"example":"Google Workspace / Gmail"},"didYouMean":{"type":"string","nullable":true,"example":null},"mxRecords":{"type":"array","items":{"type":"object","properties":{"exchange":{"type":"string"},"priority":{"type":"number"}},"required":["exchange","priority"]},"example":[{"exchange":"gmail-smtp-in.l.google.com","priority":5}]},"reasons":{"type":"array","items":{"type":"string"},"example":["Domain is a free consumer mailbox provider"]},"durationMs":{"type":"number","example":38}},"required":["email","normalized","canonical","validFormat","localPart","domain","score","deliverability","flags","provider","didYouMean","mxRecords","reasons","durationMs"]},"AddressFlags":{"type":"object","properties":{"disposable":{"type":"boolean","example":false,"description":"Domain is on the disposable / temporary mailbox blocklist."},"roleAccount":{"type":"boolean","example":false,"description":"Local part is a shared role address such as info@ or support@."},"freeProvider":{"type":"boolean","example":true,"description":"Domain belongs to a free consumer mailbox provider."},"randomLocalPart":{"type":"boolean","example":false,"description":"Local part looks machine generated."},"hasMx":{"type":"boolean","example":true,"description":"Domain publishes MX records."},"hasARecord":{"type":"boolean","example":true,"description":"Domain publishes A/AAAA records."},"nullMx":{"type":"boolean","example":false,"description":"Domain publishes a null MX (RFC 7505) and refuses mail."},"possibleTypo":{"type":"boolean","example":false,"description":"Domain looks like a misspelling of a popular provider."}},"required":["disposable","roleAccount","freeProvider","randomLocalPart","hasMx","hasARecord","nullMx","possibleTypo"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"INVALID_INPUT","description":"Stable machine-readable error code."},"message":{"type":"string","example":"Request validation failed","description":"Human-readable explanation."},"details":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},{"type":"object","additionalProperties":{"nullable":true}}],"description":"Optional structured details (usually field-level validation issues)."},"hint":{"type":"string","example":"Pass the email address in the \"email\" query parameter."}},"required":["code","message"]},"requestId":{"type":"string","example":"8f14e45f-ceea-467f-a8e7-9b5e4f0e2a31"},"timestamp":{"type":"string","example":"2026-11-21T10:15:30.000Z"}},"required":["error","requestId","timestamp"]},"BulkVerification":{"type":"object","properties":{"summary":{"$ref":"#/components/schemas/BulkSummary"},"results":{"type":"array","items":{"$ref":"#/components/schemas/EmailVerification"}},"durationMs":{"type":"number","example":210}},"required":["summary","results","durationMs"]},"BulkSummary":{"type":"object","properties":{"total":{"type":"number","example":3},"deliverable":{"type":"number","example":2},"risky":{"type":"number","example":1},"undeliverable":{"type":"number","example":0},"unknown":{"type":"number","example":0},"disposable":{"type":"number","example":0},"roleAccounts":{"type":"number","example":0},"duplicates":{"type":"number","example":0}},"required":["total","deliverable","risky","undeliverable","unknown","disposable","roleAccounts","duplicates"]},"DomainReport":{"type":"object","properties":{"domain":{"type":"string","example":"stripe.com"},"resolves":{"type":"boolean","example":true},"mx":{"type":"object","properties":{"found":{"type":"boolean"},"records":{"type":"array","items":{"type":"object","properties":{"exchange":{"type":"string"},"priority":{"type":"number"}},"required":["exchange","priority"]}}},"required":["found","records"]},"addresses":{"type":"array","items":{"type":"string"},"example":["104.18.6.125"]},"nameservers":{"type":"array","items":{"type":"string"},"example":["ns1.stripe.com"]},"provider":{"type":"string","nullable":true,"example":"Google Workspace / Gmail"},"classification":{"type":"object","properties":{"disposable":{"type":"boolean"},"freeProvider":{"type":"boolean"}},"required":["disposable","freeProvider"]},"emailAuth":{"type":"object","properties":{"spf":{"type":"object","properties":{"found":{"type":"boolean"},"record":{"type":"string","nullable":true},"policy":{"type":"string","nullable":true}},"required":["found","record","policy"]},"dmarc":{"type":"object","properties":{"found":{"type":"boolean"},"record":{"type":"string","nullable":true},"policy":{"type":"string","nullable":true}},"required":["found","record","policy"]},"dkimSelectors":{"type":"array","items":{"type":"object","properties":{"selector":{"type":"string"},"found":{"type":"boolean"}},"required":["selector","found"]}}},"required":["spf","dmarc","dkimSelectors"]},"durationMs":{"type":"number","example":120}},"required":["domain","resolves","mx","addresses","nameservers","provider","classification","emailAuth","durationMs"]},"DisposableCheck":{"type":"object","properties":{"domain":{"type":"string","example":"mailinator.com"},"disposable":{"type":"boolean","example":true}},"required":["domain","disposable"]}},"parameters":{}},"paths":{"/v1/verify":{"get":{"tags":["Verification"],"summary":"Verify a single email address","description":"Runs the full pipeline for one address: syntax, MX/AAAA DNS, disposable blocklist, role account detection, free provider detection, typo suggestion and scoring.","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":320,"example":"jane@example.com","description":"Address to verify."},"required":true,"description":"Address to verify.","name":"email","in":"query"}],"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailVerification"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Verification"],"summary":"Verify a single email address (JSON body)","description":"Same pipeline as the GET variant. Useful when addresses contain characters that need escaping in a query string.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","minLength":3,"maxLength":320,"example":"jane@example.com","description":"Address to verify."}},"required":["email"]}}}},"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailVerification"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/bulk":{"post":{"tags":["Verification"],"summary":"Verify up to 100 addresses in one request","description":"Deduplicates the input by canonical form, verifies with bounded concurrency and returns per-address results plus an aggregate summary. Regex-free: invalid lines are reported, not rejected.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"emails":{"type":"array","items":{"type":"string","minLength":3,"maxLength":320},"minItems":1,"maxItems":100,"example":["jane@gmail.com","info@stripe.com"],"description":"Up to 100 addresses per request."}},"required":["emails"]}}}},"responses":{"200":{"description":"Bulk results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkVerification"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/domain":{"get":{"tags":["Domain"],"summary":"Inspect a domain's email infrastructure","description":"Returns MX, A/AAAA, NS records, mail provider fingerprint, SPF policy, DMARC policy, DKIM selector probes and disposable/free classification.","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":253,"example":"stripe.com","description":"Domain to inspect."},"required":true,"description":"Domain to inspect.","name":"domain","in":"query"},{"schema":{"type":"string","enum":["true","false"],"example":"true","description":"Also probe four common DKIM selectors (slower)."},"required":false,"description":"Also probe four common DKIM selectors (slower).","name":"dkim","in":"query"}],"responses":{"200":{"description":"Domain report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainReport"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/disposable":{"get":{"tags":["Verification"],"summary":"Check a domain against the disposable mailbox blocklist","description":"Fast, DNS-free check of a single domain against 10,000+ known disposable and temporary mailbox providers.","parameters":[{"schema":{"type":"string","minLength":3,"maxLength":253,"example":"temp-mail.org"},"required":true,"name":"domain","in":"query"}],"responses":{"200":{"description":"Disposable check","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisposableCheck"}}}},"400":{"description":"Invalid request (bad parameters or unparsable input)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Upstream dependency timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}