Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Bulk Email Address Validation Overview


The Bulk Email Address Validation API allows you to asynchronously validate up to one million email addresses.

In contrast to the Email Address Validation Real Time API, which validates seven email addresses per second, the Bulk Email Address Validation API validates approximately 350 email addresses per second.

The Bulk Email Address Validation API is best used for cleaning up your existing email lists.


How it works

how-it-works page anchor

After sending a PUT request to the Bulk Email Address Validation API endpoint, you upload a CSV file containing up to one million addresses (or 50 MB of data), and SendGrid asynchronously validates them. Results are sent to the email address associated with your SendGrid Account.

The email validation results include validity status, email scores, and details on which checks the addresses passed and failed. These results can be used to help you determine which email addresses should no longer be included in your mailing lists.


Generate an Email Validation API key

generate-an-email-validation-api-key page anchor

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

(information)

Info

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.

  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 .
API Key Access Permissions List.
  1. Click Create & View .
  2. 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.

Validate a list of email addresses

validate-a-list-of-email-addresses page anchor

After you've created the Email Validation API Key, you can follow the steps outlined below to validate a list of email addresses using the Bulk Email Address Validation API.

Step 1: Prepare your CSV file

step-1-prepare-your-csv-file page anchor

The list of email addresses must be contained in a .csv file (or a .zip format, compressed .csv file).

There must be one column with the heading emails and contain only the email addresses to be validated.

The file must be less than 50MB and contain less than 1 million email addresses.

A sample CSV file is shown below:


_10
emails
_10
test@exampledomain.com
_10
test2@exampledomain.com
_10
differentTest@differentexampledomain.com
_10
lastEmail@lastexampledomain.net

Step 2: Request the presigned URL and headers

step-2-request-the-presigned-url-and-headers page anchor

Before you can upload your CSV file, you need to send a PUT request to the Bulk Email Address Validations endpoint. An example request is shown below. Remember to use the Email Validation API Key you created earlier.

Request a presigned URL and headers to upload a CSV file

request-a-presigned-url-and-headers-to-upload-a-csv-file page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
curl

_21
const client = require('@sendgrid/client');
_21
client.setApiKey(process.env.SENDGRID_API_KEY);
_21
_21
const data = {
_21
"file_type": "csv"
_21
};
_21
_21
const request = {
_21
url: `/v3/validations/email/jobs`,
_21
method: 'PUT',
_21
body: data
_21
}
_21
_21
client.request(request)
_21
.then(([response, body]) => {
_21
console.log(response.statusCode);
_21
console.log(response.body);
_21
})
_21
.catch(error => {
_21
console.error(error);
_21
});

The file_type provided in this request must match the file type you provide in step 3 below.

Optionally, you can save the job_id from the response so you can check the progress of the validation later in step 4.

Step 3: Upload the CSV file

step-3-upload-the-csv-file page anchor

Use the request_uri and request_headers to send an upload request with your CSV or .zip file.

An example request is shown below.

  • The ./path/to/your/fileForUpload.csv represents the relative path to your CSV or .zip file.
  • The https://example.com/the-unique-url-from-the-put-request URL represents the upload_uri in the response to the PUT request.
  • The x-amx-server... and content-type: txt/csv represent the request_headers provided in the response to the PUT request.

_10
curl --upload-file "./path/to/your/fileForUpload.csv" \
_10
"https://example.com/the-unique-url-from-the-put-request" \
_10
-H "x-amz-server-side-encryption: aws:kms" \
_10
-H "content-type: text/csv"

The response to a a successful upload request contains no response body.

Any failed upload receives an error from AWS (usually Signature Does Not Match), followed by references to authentication algorithms and blocks of encoded data. If you receive an error like this, the curl request's format is the cause.

Check header formatting and check that the copied URL does not include characters it shouldn't (like extra ``s or mismatched ""), check that header data hasn't been copied into the URL field by mistake, and check that headers used match the headers received in the upload_headers field from step 2.

Check on the progress of the validation process with a GET request for the specific job_id. If you don't have the job_id , you can GET a list of all Bulk Email Address Validation Jobs associated with your SendGrid Account.

Step 4: Download the results

step-4-download-the-results page anchor

If the Bulk Email Address Validation Job was successful, SendGrid sends the results in a CSV file to the email address associated with your SendGrid Account.

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

Verdict, score, and checks fields

verdict-score-and-checks-fields page anchor

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

suggestions-for-domain-typos page anchor

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.


Rate this page: