Best Practices

Check each email

Keep individual checks on Gmail, Outlook, and iCloud. Two addresses at the same provider can have different plus-alias verdicts, so a domain result must not replace an email check. Preserve plus tags and Gmail dots when sending the address.

Use the API verdict

Use disposable as the final detection verdict. whitelist: true describes the provider and does not override it. Treat a custom confidence threshold as a deliberate product policy, not a required integration step.

Distinguish failures from validation results

Check HTTP status and response types first. A format: false result may omit later checks; a valid-format result with missing disposable or dns is unexpected. Optional fields can be absent. See Response Fields.

The dns_indeterminate signal means DNS was inconclusive. Do not treat it as confirmed absence of mail servers. Decide how the application handles unavailable checks, and retain email ownership verification where required.

Bound requests and retries

Use backend POST requests with proper form encoding, a timeout, and server-only API keys. Check at submission rather than every keystroke. Respect Retry-After on per-minute limits and reset_at on quota exhaustion. Use bounded retries with jitter for temporary failures. See Error Handling.

Cache and batch deliberately

If caching email results, key by the full input and requested features, set an expiry, and exclude errors and inconclusive results. Detection data can change.

For large lists, use bulk validation and handle both synchronous and queued responses. Test integrations with mocked responses; the agent guide lists useful cases.

---

Questions or issues? Open a support ticket from your account and we'll help you out.