{"openapi":"3.1.0","info":{"title":"VeriFlowMail API","version":"1.0.0","description":"Email verification API. Fast checks (syntax, DNS/MX, disposable, role, typos) are available now; deep mailbox checks are not yet available."},"servers":[{"url":"https://www.veriflowmail.com"}],"security":[{"apiKey":[]}],"paths":{"/api/v1/verifications":{"post":{"operationId":"createVerification","summary":"Verify one email address","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retrying with the same key returns the first response and is never charged twice. 1–255 visible ASCII characters, kept 24 hours.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","maxLength":320,"examples":["name@company.com"]},"mode":{"type":"string","enum":["fast","deep"],"default":"fast"}}}}}},"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"400":{"description":"invalid_json, invalid_request or deep_mode_unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_key_in_progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"test_mode_requires_test_address or idempotency_key_reused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or quota_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/usage":{"get":{"operationId":"getUsage","summary":"This month's usage, credit balance and rate limit","responses":{"200":{"description":"Usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Authorization: Bearer vfm_live_… or vfm_test_… (test keys only accept addresses at test.veriflowmail.com)."}},"schemas":{"Verification":{"type":"object","required":["id","email","normalized","status","reason","flags","suggestion","score","mode","mailbox_checked","checked_at","diagnostics"],"properties":{"id":{"type":"string"},"email":{"type":"string","description":"As submitted."},"normalized":{"type":["string","null"],"description":"Trimmed, with a lower-case ASCII domain. Null if the syntax is invalid."},"status":{"type":"string","enum":["deliverable","undeliverable","risky","unknown"]},"reason":{"type":"string","enum":["invalid_syntax","reserved_domain","domain_not_found","null_mx","no_mx_records","disposable_domain","parked_domain","website_only_domain","possible_typo","no_reply_address","role_account","temporary_failure","domain_accepts_mail","mailbox_exists","mailbox_not_found","mailbox_full","catch_all","greylisted","smtp_timeout","smtp_blocked"],"description":"`invalid_syntax`: The address is not a valid email address.\n`reserved_domain`: The domain is reserved for testing or documentation and can't receive mail.\n`domain_not_found`: The domain does not exist.\n`null_mx`: The domain explicitly states that it does not accept email.\n`no_mx_records`: The domain exists but has no mail server.\n`disposable_domain`: The domain belongs to a disposable (temporary) email service.\n`parked_domain`: The domain is parked or for sale with a parking service, so mail is unlikely to reach anyone.\n`website_only_domain`: The domain has a website but no mail server record. Mail would go to the web server and often bounces.\n`possible_typo`: The domain looks like a misspelling of a common provider. See `suggestion`.\n`no_reply_address`: The address is a no-reply address and is unlikely to be read.\n`role_account`: The address belongs to a role or team (e.g. info@), not a person.\n`temporary_failure`: A DNS lookup failed temporarily. Try again later.\n`domain_accepts_mail`: The domain can receive email. The mailbox itself was not checked (fast mode).\n`mailbox_exists`: The mail server confirmed that the mailbox exists.\n`mailbox_not_found`: The mail server said the mailbox does not exist.\n`mailbox_full`: The mailbox exists but is full.\n`catch_all`: The domain accepts mail for any address, so the mailbox can't be confirmed.\n`greylisted`: The mail server asked us to try again later.\n`smtp_timeout`: The mail server did not answer in time.\n`smtp_blocked`: The mail server refused to answer the check."},"flags":{"type":"object","properties":{"disposable":{"type":"boolean"},"role":{"type":"boolean"},"free_provider":{"type":"boolean"},"catch_all":{"type":["boolean","null"],"description":"Only known after a deep check."}}},"suggestion":{"type":["string","null"],"description":"Corrected address for a likely typo."},"score":{"type":"integer","minimum":0,"maximum":100},"mode":{"type":"string","enum":["fast","deep"]},"mailbox_checked":{"type":"boolean","description":"Whether the mailbox itself was checked. Always false in fast mode: `deliverable` then means the domain accepts mail, not that this mailbox exists."},"checked_at":{"type":"string","format":"date-time"},"diagnostics":{"type":"object","properties":{"mx_records":{"type":"array","items":{"type":"object","properties":{"exchange":{"type":"string"},"priority":{"type":"integer"}}}},"implicit_mx":{"type":"boolean"},"dns_error":{"type":["string","null"]},"duration_ms":{"type":"integer"}}}}},"Usage":{"type":"object","properties":{"object":{"const":"usage"},"plan":{"type":"string"},"period":{"type":"string","examples":["2026-10"]},"fast_checks":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":"integer"},"remaining":{"type":"integer"}}},"deep_credits":{"type":"object","properties":{"available":{"type":"integer"},"monthly":{"type":"integer"},"packs":{"type":"integer"},"held":{"type":"integer"},"monthly_expires_at":{"type":"string","format":"date-time"}}},"rate_limit":{"type":"object","properties":{"requests_per_minute":{"type":"integer"}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_api_key","invalid_json","invalid_request","deep_mode_unavailable","test_mode_requires_test_address","idempotency_key_reused","idempotency_key_in_progress","quota_exceeded","insufficient_credits","rate_limited","internal_error"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}}