{"openapi":"3.1.0","info":{"title":"VeriDock API","version":"1","description":"Verify an email address: four statuses, a reason code, a 0-100 score and the individual checks behind the answer. Documentation: https://veridock.io/docs","contact":{"email":"team@veridock.io","url":"https://veridock.io/docs"}},"servers":[{"url":"https://app.veridock.io/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/verify":{"get":{"operationId":"verifyEmail","summary":"Verify an email address","description":"Returns a status, reason and score. Unknown results are never billed. Keys prefixed vd_test_ return fixed results and never use credits.","parameters":[{"name":"email","in":"query","required":true,"schema":{"type":"string"},"description":"The address to verify. URL-encode it."},{"name":"smtp","in":"query","schema":{"type":"boolean","default":true},"description":"Set false to skip the live SMTP check for a faster, syntax-and-DNS-only answer."},{"name":"timeout","in":"query","schema":{"type":"integer","default":8000},"description":"Maximum milliseconds to wait for the receiving server before returning unknown."},{"name":"cache","in":"query","schema":{"type":"boolean","default":true},"description":"Set false to force a fresh check and bypass the 30-day result cache."}],"responses":{"200":{"description":"The verification result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResult"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"verifyEmailPost","summary":"Verify an email address (JSON body)","description":"Accepted and behaves identically to GET.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"}}}}}},"responses":{"200":{"description":"The verification result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResult"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key prefixed vd_live_ or vd_test_. Never ship a live key to a browser."}},"responses":{"Error":{"description":"Error. Failed requests are never billed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"invalid_request, unauthorized, quota_exceeded, rate_limited or internal_error"},"message":{"type":"string"}}}}}}}}},"schemas":{"VerifyResult":{"type":"object","properties":{"email":{"type":"string","description":"The normalized (lower-cased, trimmed) address that was verified."},"status":{"type":"string","enum":["deliverable","undeliverable","risky","unknown"]},"reason":{"type":"string","enum":["accepted_email","invalid_syntax","invalid_domain","no_mx_record","rejected_email","mailbox_full","disposable","role_account","catch_all","low_quality","low_deliverability","timeout","greylisted","unavailable_smtp"]},"score":{"type":"integer","minimum":0,"maximum":100},"checks":{"type":"object","properties":{"syntax":{"type":"boolean"},"domain":{"type":"boolean"},"mx":{"type":"boolean"},"smtp":{"type":"boolean"},"disposable":{"type":"boolean"},"role_account":{"type":"boolean"},"catch_all":{"type":"boolean"},"free_provider":{"type":"boolean"}}},"domain":{"type":"object","properties":{"name":{"type":"string"},"mx":{"type":"array","items":{"type":"string"}},"provider":{"type":["string","null"]}}},"suggestion":{"type":["string","null"],"description":"A corrected address when a likely typo is detected."},"billed":{"type":"boolean","description":"Whether this request consumed a credit. Always false for unknown and for cached results."},"duration_ms":{"type":"integer"}}}}}}