Verification timeouts

Why a verification can time out, the timeouts Kawaa applies to DNS and SMTP checks, and how to handle a timeout response.

Why timeouts occur

• Mail server is slow to respond
• Server is temporarily unavailable
• Network issues between Kawaa and mail server
• Greylisting or anti-spam delays

Default timeouts

Handling timeouts

• Retry the verification after a few minutes. Checking the address again is a fresh check at 1 credit: an unknown result is charged like any other and is never answered from the result cache
• Use async/batch endpoints for large volumes
• Read status and sub_status together: a slow or deferring server and an unreachable one are reported differently (below)

Timeout response

A timeout is a successful API call that could not reach a verdict, not an error response: success is still true. What comes back depends on where the time ran out:

• The check used up its time budget, or the server deferred it with a temporary error: unknown with sub_status temporary_failure. A server that greylisted the check is unknown with greylisted. Retrying later can settle both.
• No mail server could be reached, or the connection dropped: unknown with sub_status connection_failure.

{
  "success": true,
  "data": {
    "email": "user@slow-server.com",
    "status": "unknown",
    "sub_status": "temporary_failure",
    "quality_score": 50,
    "verification": {
      "syntax_valid": true,
      "domain_exists": true,
      "mx_found": true,
      "smtp_check": false,
      "greylisted": false
    }
  }
}

An unknown result is never served from cache, so the retry runs a fresh check. Its quality_score is capped at 50.