Our Real-Time API is a simple JSON based REST Web Service that allows developers to verify individual email addresses on demand as a user enters them in a web form or mobile application.
It is a simple POST request with two parameters:
- address: the email address to be verified.
- api key: the confidential API key for your BriteVerify account. NOTE: Each account has a frontend and a backend API key. For server side implementations use the Backend API Key.
Here is an example request:
There are only 4 statuses for an email in BriteVerify.
- Valid: The email represents a real account / inbox available at the given domain
- Invalid: Not a real email
- Unknown: For some reason we cannot verify valid or invalid. Most of the time a domain did not respond quickly enough.
- Accept All: These are domains that respond to every verification request in the affirmative, and therefore cannot be fully verified.
Unless something goes wrong, the HTTP status code will always be 200, regardless if the email is valid or invalid. The above request would yield the following response.
Now if I pass an invalid email I will get not only a status of "invalid", I will also get an error and and error code explaining why the email is invalid.
"error": "Email account invalid",
- address: the email that was passed
- account: the inbox or account parsed from the email
- domain: the domain parsed from the email
- status: the status of the given email address
- error: the error message if the email is invalid
- error_code: a code representation of error
- disposable: is the email a temporary or "disposable" email address
- role_address: the email is a role address such as sales or admin.
- duration: the time it took to process your request
Error & Error Codes
The error is really just a humanized version of the error code. So that an error_code of "email_account_invalid" will have an error of "Email account invalid." The error in this sense is really the "error message," something intended to be displayed in a Web Form or application UI.
- email_address_invalid: the email is not formatted correctly
- email_domain_invalid: the domain does not exist or is not capable of receiving email
- email_account_invalid: the email account does not exist on the domain
A temporary or "disposable" email address is one that a user has set up to live for only a short period of time for a variety of reasons. Usually you don't want to accept these types of emails, but we leave that up to how you wish to implement your own applications. These emails are just like any other emails and the "status" will reflect that. However, the disposable flag will be present if the email is from a known temporary email provider.
Role address are email address that are set aside for functions, not people. They’re often forwarded to a group or department inside a company, and they can change owners frequently. Sending to a role address can quickly lead to spam complaints. Also, unused role accounts are often converted to spam traps, which will also get you into a ton of trouble. Either way, it’s a darn good idea to toss these aside. However, technically speaking, they can be "deliverable" addresses. So BriteVerify does not mark them as invalid. Instead we have a role_address flag to let you know to sending to the address is not advisable, but ultimately up to you.
Some examples of role addresses are postmaster, sales, admin, info, webmaster, etc. One role address in particular that is extremely risky is the postmaster address. Sending an email to that one is like driving drunk to a police station... not that brite ;-)
- Protect your Frontend API Key: You are responsible for the cost of all verifications processed with it. If you have not already reviewed this article of Security Considerations for using the server-side (REST) API in a form please do so prior to promoting it to production.
- Exponential Backoff Algorithm: We recommend implementing exponential backoff algorithm which is commonly available in most test libraries for situations where you may receive server (500-series) errors. The idea behind exponential backoff is to use progressively longer waits between retries for consecutive error responses. Ideally, implement a maximum delay interval, as well as a maximum number of retries in order to increase reliability and to reduce any operational cost.