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.

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


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


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


Example - Using API Token

  curl -X GET 'https://api.clearout.io/v2/email_verify/getcredits' \
  -H 'Authorization: 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
  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 u[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

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
601Email is part of allowlistValid
602Email is part of blocklistInvalid
603Domain is part of allowlistValid
604Domain is part of blocklistInvalid
605Request cancelledUnknown
606Unsupported characterInvalidHard

Flatten Response Object

By adding "response=flat" as query parameter to any API will convert the nested object into flat object, this would be helpful where system does not support JSON nested object

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.

Monthly / Annual Subscription
CreditsInstant Email Verify (RPM)Instant Email Finder (RPM)
More than 5,000,000400240
CreditsInstant Email Verify (RPM)Instant Email Finder (RPM)
1 to 9999106
10000 to 99,9992512
100,000 to 249,9995535
250,000 to 499,9999050
500,000 to 999,99915080
More than 1,000,000240150


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

Test Email AddressDescription
[email protected]An invalid email address
[email protected]An valid email address
[email protected]Accept-all or Catch-all email address
[email protected]An unknown email address
[email protected]Safe to send email address
[email protected]Not a safe to send email address
[email protected]Risky email address
[email protected]Disposable email address
[email protected]Role or group based email address
[email protected]Free mail server provider email address
[email protected]Gibberish email address
[email protected]Hard bounce email address
[email protected]Soft bounce email address
[email protected]An auto-suggested email address
[email protected]Syntax error email address
[email protected]Greylisted email address
[email protected]Spamtrap email address
[email protected]Found part of blocklist email address
[email protected]Found part of allowlist email address
[email protected]Found part of blocklist domain
[email protected]Found part of allowlist domain
[email protected]Domain does not exist email address
[email protected]Not a mail server email address
[email protected]Mailbox not found email address
[email protected]Mail quota exceeded email address
[email protected]DNS query timeout email address
[email protected]Unroutable mail exchange server email address
[email protected]Dormant email address
[email protected]Receiving limit execeed email address