API Overview - Version 2.0

Clearout's Advanced Email Validation, Verification, Discovery Services are available through simple REST API to verify or discover millions+ of email addresses in real time. With the use of the instant verification API, the deliverability status of any email address can be determined proactively. Both instant and bulk validation allows you to maintain a clean list of email addresses with 98%+ guaranteed deliverability rate, at scale bulk validation support verifying list containing millions of email addresses in a single bulk request.

Getting Started with API

Clearout Email Validation API allows to create custom integrations to add email verification to any part of your software application. It starts with creating a Clearout Apps of run type "Server".

Each signup comes with 100 free credits verification to give users a fair chance for free trial. If you need more, check out our decent pricing for additional verifications. If you don’t have an account yet create a free account

API Base URL

Clearout APIs have a base URL to which all the endpoint paths are appended, since base URL might vary based on the type of accounts API users are advised to check their base URL by logging into Clearout app and by navigating to Account->API tab

Generating an API Token

Once signed up and logged in, click on Apps tab available on top-right and then click "Create App" choosing run type "Server", all successful apps will listed under Apps with an API token, use this token as a bearer value in all the API requests. Token can be reset anytime clicking the 'Reset Token' icon

Response Status Codes

These are the HTTP response codes that Clearout API uses to indicate the success or failure of a request:

                  
  200   Success
  400   Bad Request
  401   Unauthorized
  402   Payment Required
  403   Forbidden
  415   Invalid Content Type. Must be application/json
  429   Rate Limit Exceeded
  500   Internal Server Error
  503   Service unavailable
  524   Request Timeout  

  

These are the Clearout error codes that Clearout API uses as part of error response object:

    
  1000  Invalid API Token, please generate new token
  1001  You have reached the maximum number of bulk verify requests, please try after the existing request completes or contact [email protected]
  1002  You have exhausted your credits, please add additional credits to continue
  1004  Oops!!! Unable to determine email address in your list, please ensure email addresses are present or explicitly specified in a header row with one of the column value either as "Email" or "Emails" or "Email address" or "Emailaddress"
  1007  Result file got expired, contact [email protected]
  1008  You are not authorized to access this resource
  1017  You have reached daily verify limit, please try next day or contact [email protected]
  1027  Email address not found
  1028  Your available credit is AVAILABLE_CREDITS which is not enough to verify NUMBER_OF_EMAILS emails
  1029  List is not available
  1030  You have reached API rate limit, try calling after [CURRENT TIMESTAMP + 60 Seconds] GMT+0000 (UTC) or to increase limit upgrade plan or reach [email protected]
  1074  Invalid origin
                    
      
    

Verify Response Status Values

After the successful email verification, every email address status is primarily categorized as either Valid, Invalid, Unknown or Catch-All

Verify Response Sub-Status Values

Apart from the email verification status mentioned above, the generated response will contain the sub-status code for the given status results. The definition of each sub-status code is explained below

Cross-Origin Resource Sharing (CORS)

Clearout does not support API request directly from the Web Browser/App. This means Clearout APIs are allowed to be used only on your server-side application

Limits and Quotas on API Requests

Clearout's real-time Instant API request comes with a rate limit to decide how many requests are allowed per minute (RPM) for an user account. Currently the rate limit is assigned based on the credits purchased. Please refer the table below to know the rate limit for the credits purchased either through Pay-as-you-go or Subscription. Maximum rate limit once assigned will be retained even when the plan is downgraded or lesser credits are purchased

Rate limited API requests will respond with the following x-ratelimit-* header field in successful responses. Clients can understand their current usage, shape the request policy to prevent being throttled out by using these data.

x-ratelimit-limit: containing the requests quota in a 60 seconds interval window;
x-ratelimit-remaining: containing the remaining requests quota in a 60 seconds interval window;
x-rateLimit-reset: containing the time remaining in the current interval window, specified in seconds.

Testing

To confirm that your integration works as intended without incurring credits, use the test email addresses listed below for all possible email verification results.