# 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.

Date: 2026-09-03

- `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.

Reference: https://spaw.co/changelog/2026-09-03-freshness-controls