{"openapi":"3.1.0","info":{"title":"emailverifier.dev API","version":"1.6.0","description":"Verify email address quality with a technical status, recommended action, and the signals behind the result. Authenticated verification consumes one project credit."},"servers":[{"url":"https://emailverifier.dev"}],"tags":[{"name":"Verification","description":"Verify complete email addresses."},{"name":"Domains","description":"Classify email domains."},{"name":"Usage","description":"Monitor project credit usage."}],"paths":{"/api/v1/verify":{"post":{"tags":["Verification"],"operationId":"verifyEmailAddress","summary":"Verify one email address","description":"Send only an email address. With a project API key, one successful call consumes one project credit. Without a key, the public demo allows 10 requests per hour. Project IDs are resolved from API keys and are never accepted from clients.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"additionalProperties":false,"properties":{"email":{"type":"string","maxLength":254,"example":"hello@example.com"}}}}}},"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationResult"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"ISO timestamp when the current window resets.","schema":{"type":"string","format":"date-time"}}}},"400":{"description":"Invalid request body or email field","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyAuthError"}}}},"402":{"description":"Project has no credits remaining","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditBalanceExceeded"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitExceeded"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"ISO timestamp when the current window resets.","schema":{"type":"string","format":"date-time"}}}}}}},"/api/v1/domains/{domain}":{"get":{"tags":["Domains"],"operationId":"classifyEmailDomain","summary":"Classify one email domain","description":"Returns the provider classification, risk level, and whether the domain appears able to receive email. Every authenticated domain check consumes one project credit, regardless of classification. Without a key, the public demo allows 10 requests per hour. It does not confirm a specific mailbox or message delivery.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]},{}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"mailinator.com"}}],"responses":{"200":{"description":"Domain classification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainClassification"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"ISO timestamp when the current window resets.","schema":{"type":"string","format":"date-time"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyAuthError"}}}},"402":{"description":"Project has no credits remaining","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditBalanceExceeded"}}}},"404":{"description":"Invalid domain path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidDomainPathError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitExceeded"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"ISO timestamp when the current window resets.","schema":{"type":"string","format":"date-time"}}}}}}},"/api/v1/usage":{"get":{"tags":["Usage"],"operationId":"getApiUsage","summary":"Get API usage and remaining credits","description":"Returns lifetime completed checks and the current credit balance for the project associated with the API key. This request does not use a credit.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Project usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSummary"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"ISO timestamp when the current window resets.","schema":{"type":"string","format":"date-time"}}}},"401":{"description":"API key required or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyAuthError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitExceeded"}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"ISO timestamp when the current window resets.","schema":{"type":"string","format":"date-time"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"},"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"VerificationResult":{"type":"object","example":{"email":"hello@example.com","status":"undeliverable","action":"block","flagged":true,"signals":["no_mail_server"],"suggestion":null},"required":["email","status","action","flagged","signals","suggestion"],"additionalProperties":false,"properties":{"email":{"type":"string","example":"hello@example.com"},"status":{"type":"string","enum":["deliverable","risky","undeliverable","unknown"],"description":"Deliverable means the server accepted the recipient, not guaranteed delivery or proof the mailbox exists. Catch-all acceptance remains deliverable/review with the catch_all_domain signal. Risky includes disposable addresses. Unknown means evidence is incomplete or conflicting."},"action":{"type":"string","enum":["block","allow","review"],"description":"Recommended default handling. Allow can accompany an unknown status when the available evidence supports accepting the address; it does not confirm current delivery or ownership. Review preserves uncertain addresses such as catch-all domains without blocking them."},"flagged":{"type":"boolean","example":false,"description":"True when the recommended action is block; false when it is allow or review."},"signals":{"type":"array","description":"invalid_syntax: The address format is invalid.\n\ninvalid_domain: The domain format is invalid.\n\nno_mail_server: The domain has no usable mail routing.\n\ndisposable_address: This domain provides disposable email addresses.\n\nfree_provider: This is a personal email provider.\n\nrole_address: This is a shared role address, such as support or sales.\n\nmailbox_accepts_mail: The mail server accepted this recipient during the check. Delivery is not guaranteed.\n\nmailbox_rejected: The mail server explicitly rejected this recipient as nonexistent.\n\ncatch_all_domain: The server also accepted a random address. This mailbox could not be confirmed.\n\npossible_typo: The domain may contain a typo. Check the suggested address.\n\nverification_inconclusive: The available evidence could not confirm or reject this mailbox.\n\ncatch_all_check_inconclusive: The server accepted the recipient, but the catch-all check could not finish conclusively.\n\ndns_unavailable: The mail-routing DNS lookup could not finish. Try again later.\n\nsmtp_timeout: The mail server did not respond in time. Try again later.\n\nsmtp_connection_failed: The connection to the mail server could not finish. Try again later.\n\nsmtp_temporary_failure: The mail server temporarily deferred the check. Try again later.\n\nsmtp_policy_block: The mail server restricted the check. This does not mean the address is invalid.\n\nsmtp_cannot_verify: The mail server could not confirm this recipient.\n\nsmtp_conflict: The mail servers returned conflicting evidence. This mailbox could not be confirmed.\n\nverification_unavailable: Mailbox verification is temporarily unavailable. Try again later.","items":{"type":"string","enum":["invalid_syntax","invalid_domain","no_mail_server","disposable_address","free_provider","role_address","mailbox_accepts_mail","mailbox_rejected","catch_all_domain","possible_typo","verification_inconclusive","catch_all_check_inconclusive","dns_unavailable","smtp_timeout","smtp_connection_failed","smtp_temporary_failure","smtp_policy_block","smtp_cannot_verify","smtp_conflict","verification_unavailable"]}},"suggestion":{"type":["string","null"],"example":null,"description":"Corrected address for a recognized provider typo."}}},"DomainClassification":{"type":"object","required":["domain","classification","risk","mail_routing"],"additionalProperties":false,"properties":{"domain":{"type":"string","example":"mailinator.com"},"classification":{"type":"string","enum":["disposable","free_provider","unknown"]},"risk":{"type":"string","enum":["high","medium","unknown"]},"mail_routing":{"type":"string","enum":["available","unavailable","unknown"],"description":"Whether the domain appears able to receive email. This does not confirm a specific mailbox."}}},"UsageSummary":{"type":"object","required":["project","credits_used","credits_remaining","last_used_at"],"additionalProperties":false,"properties":{"project":{"type":"string","example":"Production"},"credits_used":{"type":"integer","minimum":0,"example":124},"credits_remaining":{"type":"integer","minimum":0,"example":876},"last_used_at":{"type":["string","null"],"format":"date-time","example":"2026-08-11T12:00:00.000Z"}}},"ValidationError":{"type":"object","required":["statusCode","statusMessage","data"],"properties":{"statusCode":{"type":"integer","example":400},"statusMessage":{"type":"string","example":"Email is required."},"data":{"type":"object","required":["field"],"properties":{"field":{"type":"string","example":"email"}}}}},"ApiKeyAuthError":{"type":"object","required":["statusCode","statusMessage"],"properties":{"statusCode":{"type":"integer","example":401},"statusMessage":{"type":"string","example":"Invalid API key."}}},"CreditBalanceExceeded":{"type":"object","required":["statusCode","statusMessage","data"],"properties":{"statusCode":{"type":"integer","example":402},"statusMessage":{"type":"string","example":"Project has no credits remaining."},"data":{"type":"object","required":["remaining"],"properties":{"remaining":{"type":"integer","example":0}}}}},"RateLimitExceeded":{"type":"object","required":["statusCode","statusMessage","data"],"properties":{"statusCode":{"type":"integer","example":429},"statusMessage":{"type":"string","example":"Rate limit exceeded."},"data":{"type":"object","required":["limit","resetAt"],"properties":{"limit":{"type":"integer","example":10},"resetAt":{"type":"string","format":"date-time"}}}}},"InvalidDomainPathError":{"type":"object","required":["statusCode","statusMessage"],"properties":{"statusCode":{"type":"integer","example":404},"statusMessage":{"type":"string","example":"Invalid domain path"}}}}}}