Skip to content

Best Practices

We have a few suggestions for people implementing our API.

Implement proper error handling

Even though we have multiple endpoints all over the world, network issues and delays can still occur.

  • Always check HTTP status codes before processing responses
  • Verify that the response contains the expected fields (like "valid", or "block")
  • Handle network timeouts gracefully (set reasonable connect/timeout values)
  • Soft fail if possible. Depending on how sensitive your serivce is, it might be better to allow the e-mail if you don't get a valid response from the API. You could possibly log it, and check it later.

Don't leak your API key

Don't use the API key directly in your mobile app, or in your frontend javascript. It would be easy for an attacker to steal your API key, and quickly eat up your request limits.

Instead, if necessary, you should do the API call from your backend, so that the user can't extract your API key.

Real-time vs. background validation

  • Use real-time validation for critical user flows (registration, checkout)
  • Use background validation for bulk operations (monthly check of all user emails)

User experience considerations

  • Provide clear feedback for invalid/disposable emails
  • Maybe allow it, but flag users as suspicious if they are using a disposable email