Real Time Email Address Validation Overview

Before you can use any of the Email Address Validation API endpoints, you need an API key with Email Address Validation permissions.

1. Navigate to Settings, and then select API Keys. Click Create API Key in the upper right-hand corner.
2. Name your new key and select the Email Address Validation Access permission.
3. Select Full Access to the left of Validation.

Expand image

4. Click Create & View.
5. 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.

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 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 source parameter 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.

This section describes the fields in SendGrid's response to an Email Address Validation request.

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.

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.

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.

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.

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.

Expand image

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.

Expand image

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.