Bulk Email Address Validation Overview

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.

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.

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.

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:

1
emails
2
test@exampledomain.com
3
test2@exampledomain.com
4
differentTest@differentexampledomain.com
5
lastEmail@lastexampledomain.net

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.

1
const client = require('@sendgrid/client');
2
client.setApiKey(process.env.SENDGRID_API_KEY);
3

4
const data = {
5
  "file_type": "csv"
6
};
7

8
const request = {
9
  url: `/v3/validations/email/jobs`,
10
  method: 'PUT',
11
  body: data
12
}
13

14
client.request(request)
15
  .then(([response, body]) => {
16
    console.log(response.statusCode);
17
    console.log(response.body);
18
  })
19
  .catch(error => {
20
    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.

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.

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

The response to 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.

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.

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.