Real Time Email Address Validation Overview
Email Address Validation provides detailed information on the validity of email addresses. Validating email addresses allows you to remove invalid email addresses from your lists, which helps to decrease your bounce rate, clean up your subscriber list, and ultimately improve your sender reputation.
The Email Address Validation Real Time API endpoint provides real-time detailed information on the validity of email addresses. This API validates one address at a time. SendGrid provides the validation information in the response to your API request. You can use this API to:
- Indicate to users that the address they have entered into a form is invalid.
- Prevent invalid email addresses from entering your database
This page covers:
- How to create the required API key.
- How to interpret the results.
- Best practices for integration.
- Options for integration.
Need to validate many email addresses at one time? Check out the Bulk Email Address Validation Overview page.
Generate an Email Validation API key
Before you can use any of the Email Address Validation API endpoints, you need an API key with Email Address Validation permissions.
Email Address Validation is available to Email API Pro and Premier level accounts only.
Prior to upgrading your account to Pro or Premier, you will not see the option to create an Email Validation API key.
An Email Validation API key is separate from and in addition to your other keys, including a Full Access API key. If you do not have one, API creation guide is below.
- Navigate to Settings, and then select API Keys. Click Create API Key in the upper right-hand corner.
- Name your new key and select the Email Address Validation Access permission.
- Select Full Access to the left of Validation.
- Click Create & View.
- Copy and save your new API key somewhere safe. This will be the only time you will be able to see it in its entirety due to security reasons.
Integration best practices
The Real Time Email Address Validation API endpoint takes a single email address in a POST request, and returns a verdict with detailed data in a JSON response. Complete documentation of the endpoint, including details of the response, are available on the API reference page.
When integrating with the Real Time Email Address Validation API endpoint, keep the following things in mind:
- Do not call the API endpoint from client side code such as JavaScript. Doing so would allow anyone to find your API key and use it to validate their own email addresses on your account. You should instead call the API from your application's back end, for instance, after the user submits a form.
- The Real Time Email Address Validation API endpoint only accepts one email address at a time.
- If you choose to integrate into a signup form, make sure that the the Email Validation API is not a blocker for your form submissions.
- The Real Time Email Address Validation API endpoint's rate limit is seven requests per second.
- You can provide the optional
sourceparameter in the request to identify where the email address came from. This is returned in the response from SendGrid so that you can use this to track results from different sources.
Interpret the results
This section describes the fields in SendGrid's response to an Email Address Validation request.
Verdict, score, and checks fields
To prevent accidentally blocking or removing legitimate customers from your mailing lists, SendGrid's Email Validation APIs are calibrated to provide a low number of false negatives (i.e., a real address classified as an invalid address).
You can filter out or remove an email address based on the values of the verdict, score, and checks fields listed below. Use the information provided to determine your use case's threshold for removing or rejecting an email address.
Verdict
This field contains one of three categories: “Valid”, “Risky”, or “Invalid”. These are generic classifications based off of the detailed results.
Score
This number from 0 to 1 represents the likelihood the email address is valid, expressed as a percentage. So for instance, a score of 0.96 could be interpreted as a 96% likelihood the email is valid. If you want finer grained control than the generic categories of the “result” field, you could set a threshold based off this score.
Checks
This field will contain a list of all the checks that ran on the email address. You could use these results to fine tune your email list based on specific feedback mechanisms. For instance, an email address that is a role address (e.g. admin@examplecompany.com) will come back with a “Risky” result and a score of 50%. A disposable email address from mailinator.com would also come back with a “Risky” result and a score of 50%. You might decide that you only want to send to email addresses with a score of 80% or higher, but are also willing to send email to addresses that are disposable (and therefore have a score of 50%). You could use this field to gain the info you need to filter at that level. Here are a list of all the checks and what they mean:
has_valid_address_syntax- If true, then the address is a properly formatted email address (e.g. it has an @ sign and a top level domain). If false, then it’s a malformed address.has_mx_or_a_record- If true, the domain on the address has all the necessary DNS records to deliver a message somewhere. If false, the domain is missing the required DNS records and will result in a bounce if delivered to.is_suspected_disposable_address- If true, the domain part of the email address appears to be from a disposable email address service, in which the addresses are only good for a short period of time.is_suspected_role_address- If true, the local part of the email address (before the @ sign) appears to be a group email address such as “hr” or “admin”.has_known_bounces- If true, the email address has previously been sent to through a SendGrid Account and has resulted in a bounce.has_suspected_bounces- If true, our machine learning model suspects that the email address might bounce.
Suggestions for domain typos
SendGrid checks for typos in an email address in addition to evaluating its validity. If a possible typo is detected, the suggestion field in the response contains a suggestion for the correct domain.
For example, when validating john.doe@gmial.com, the result might contain a suggestion field with a value of gmail.com. You can programmatically combine this suggestion with the local field (john.doe) to create the intended email address of john.doe@gmail.com.
Options for Integration
The Email Validation API allows flexibility for integrating in multiple ways, but for simplicity we'll focus on validating emails in a signup form. A signup form is anywhere you are capturing email addresses. This could be a lead capture signup form like requesting a content piece or an account signup.
Once you identify the signup form you want to integrate with the Real Time Email Address Validation API, next you need to decide if you want to use validation results to surface possible typos to form visitors while they're still in the form or capture the results after the form submission to inform sending decisions.
The first option is to provide user feedback by returning to the sign up form and showing an inline error, letting the user know that they need to check the email address.
Be careful not to create a block in your sign up form if you provide user feedback. It’s possible that a user’s actual email address doesn’t meet your criteria for a good address, and will never be able to successfully submit your form. You should consider alerting the user only once, and then allowing the same address if they submit it again a second time.
The second option is to validate the email address after submission and not provide any user feedback. You can then use the Email Validation results to decide what email addresses you feel comfortable sending email to.
Depending on your business needs and how you prefer to integrate, both of these approaches are great options. The upside of providing user feedback in the signup form is that you’ll catch visitor typos before they leave the form, however the downside is that you’ll still have some friction points in the signup form in the event that the address they provide doesn’t meet your criteria. The upside of dropping bad addresses in the backend is that you have a frictionless signup form, while the downside is you lose the opportunity to save contact with visitors who may have accidentally mistyped their email address.
Email Validation API Dashboard
The last way you can evaluate your validation results is in the Email Validation API dashboard within the SendGrid UI. (The dashboard only appears in the SendGrid UI after you've created the Email Validation API key.) This Validation dashboard gives you access to all the Real Time Email Address Validation results from the past 30 days, and allows you to filter down to what you consider a good address. You can filter by the verdict result, the source the validation was performed at, as well as the score.
Detailed validation results
You can select a specific email address within the Email Validation API dashboard in order to view the detailed validation results for that email address.
Export your results
Once you’ve filtered down to your desired list of results, you can click the Export CSV button to get a CSV list of your results. This can then be used to upload your good contacts and validation results to Marketing Campaigns, or your database or CRM of choice.
Need some help?
We all do sometimes. Get help now from the Twilio SendGrid Support Team.
Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.
