Understanding and handling verification timeouts.
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
| Check | Timeout |
|---|---|
| DNS lookup | 5 seconds per attempt, up to 2 attempts |
| SMTP conversation | 10 seconds (5 seconds to connect) |
| Extended checks | Deployment-dependent |
| Total request | 60 seconds |
Handling timeouts
- Retry the verification after a few minutes
- Use async/batch endpoints for large volumes
- Check the status field - "unknown" often indicates timeout
Timeout response
A timeout is a successful API call that could not reach a verdict, not an error response — success is still true. The address comes back as unknown, and sub_status says why.
{
"success": true,
"data": {
"email": "user@slow-server.com",
"status": "unknown",
"sub_status": "connection_failure",
"quality_score": 40,
"verification": {
"syntax_valid": true,
"domain_exists": true,
"mx_found": true
}
}
}Other sub-statuses in this family are temporary_failure (the server asked us to retry later) and greylisted.