API Overview - Version 2.0

Clearout's Advanced Email Validation and Verification Services are available through simple REST API to verify 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.

Looking for older versions

API version 2.0 is the latest version Click here if you are looking for the older version.

What does 'Default App' mean?

If your API token has been generated before the Clearout Apps support, it will be found as part of the system created app called "Default App". Btw, you are free to edit the app

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

Clearout

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

Clearout

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

Clearout

Example - Using API Token

              
  curl -X GET 'https://api.clearout.io/v2/email_verify/getcredits' \
  -H 'Authorization: Bearer:3ec7egp34f992762fb5cf6a3479e7e34:d43d2e605e94a8c4s9b72be13b37c19c74b41610c3560484e5c422ccb4fb4074'  
              

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
                    

Verify Response Status Values

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

ValueDescription
ValidSpecified email address has been verified as valid and safe to send
InvalidSpecified email address has been verified as a bad recipient address that does not exist or is not accepting mail
Catch-AllSpecified email address accepts all emails and then simply discards the mail or bounces it back to the sender
UnknownSpecified email address returns an unknown result as it was unable to get a response from the recipient's mail server

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

CodeDescriptionStatusHard / Soft Bounce?
200Specified email address is valid and safe to send emailsValid
400Specified email address is not a valid email address syntaxInvalidHard
401Specified email address is a spam trap or honeypotInvalidSoft
402Mail server connection timeoutUnknown
403Domain doesn't have any records in DNS or have incomplete DNS RecordsInvalidHard
404Domain is not configured to a Mail ServerInvalidHard
405SMTP server was unavailable to process the requestUnknown
406Mailbox not found for the specified email addressInvalidHard
407Domain IP of the specified email address is greylistedUnknown
411Specified email address belongs to a Catch-All mail serverCatch-all
412Unable to determine; retry later after an hour or soUnknown
413Mailbox quota exceeded for the specified email addressInvalidSoft
414Domain of specified email address is rDnsBlacklisted (Retry later after an hour or contact support )Unknown
415API call limit is exceeded for the particular instance (Retry later after an hour or contact support)Unknown
416No Answer Received From Authoritative Server for the domainInvalidHard
417Domain name server timed outUnknown
418Domain name server returned with an errorUnknown
419Insufficient System Resource (disk/memory)InvalidSoft
420Mail server command timeoutUnknown
500An unexpected error has occurred while validatingUnknown

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 Verify 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. Note - the maximum rate limit once assigned will be retained even when plan is downgraded or low credits purchased

Monthly / Annual Subscription
CreditsRequests Per Minute (RPM)
500025
10,00055
50,00090
100,000135
250,000185
500,000240
1,000,000300
More than 5,000,000400
Pay-as-you-go
CreditsRequests Per Minute (RPM)
0 to 499910
5000 to 99,99925
100,000 to 249,99955
250,000 to 499,99990
500,000 to 999,999150
More than 1,000,000240