Authentication

All calls made to the Bouncer API have to be made using HTTPS.

In order to generate your API Key go here or:

  • sign up for a Bouncer account here,
  • click on the API on the left-site menu,
  • click Generate API Key button.

Bouncer API supports 2 methods of authentication:

x-api-key in header

bash
curl https://api.usebouncer.com/v1.1/email/verify?email=john@usebouncer.com -H 'x-api-key: API-KEY'

“Basic” authentication with api key as password

bash
curl https://api.usebouncer.com/v1.1/email/verify?email=john@usebouncer.com -u :API-KEY

Error Handling

The API makes use of standard HTTP errors to indicate the success or failure of a request. The 2xx series of response codes indicate a success, 4xx indicates an error from the client side, and a 5xx error indicates a server-side error. Here are the HTTP response codes the API utilises:

  • 200 Success
  • 400 Bad Request
  • 401 Unauthorized
  • 402 Payment Required
  • 403 Forbidden
  • 404 Not Found
  • 429 Too Many Requests
  • 503 Service Unavailable

Cases to handle while implementing integration:

  • Status code 402 - Account does not have enough credits to handle request. Purchase is required. Other way to handle this is to configure email alerts or auto-refill available with subscription.
  • Status code 429 - Request have been rate limited. Too many requests have been sent.
  • Status code 503 - In some edge cases it’s possible that response with status code 503 will be returned. In that case retry should solve the problem.