2026-09-03

Freshness controls and a per-call handshake timeout

Ask for a fresh answer past the seven-day repeat window with refresh or max_age, and cap how long a mailbox handshake may wait.

POST /api/v1/email and POST /api/v1/email/batch accept refresh: true, which discards the answer from the seven-day repeat window and the shared mailbox answer, runs a real handshake again, and bills the lookup as fresh when it is answered.
max_age (seconds, 60 to 604800) does the same only when the previous answer is older than that, so a list can be re-checked at the cadence you choose without paying for answers that are still young.
The response says what happened: meta.refreshed is true whenever an earlier answer was discarded for the call.
timeout (seconds, 2 to 60) caps how long the mailbox handshake may wait for one call. A handshake that runs out of time answers unverified with smtp_reason: timeout instead of holding the request.
The Python, Node.js and PHP clients, the Zapier app and the Google Sheets functions expose the same options.