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 deferring server and an unreachable or too slow 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:

• No mail server could be reached, the connection dropped, or the server was too slow and the check used up its time budget before the server answered for the mailbox: unknown with sub_status connection_failure. If the server had already answered for the mailbox when the time ran out, the result follows that answer instead.
• The server deferred the check with a temporary error, or a DNS lookup failed transiently: unknown with sub_status temporary_failure. A server that greylisted the check is unknown with greylisted. Retrying later can settle both.

{
  "success": true,
  "data": {
    "email": "user@slow-server.com",
    "status": "unknown",
    "sub_status": "connection_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.