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.
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.
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.
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:
1emails2test@exampledomain.com3test2@exampledomain.com4differentTest@differentexampledomain.com5lastEmail@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.
1const client = require('@sendgrid/client');2client.setApiKey(process.env.SENDGRID_API_KEY);34const data = {5"file_type": "csv"6};78const request = {9url: `/v3/validations/email/jobs`,10method: 'PUT',11body: data12}1314client.request(request)15.then(([response, body]) => {16console.log(response.statusCode);17console.log(response.body);18})19.catch(error => {20console.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.
./path/to/your/fileForUpload.csv
represents the relative path to your CSV or .zip file.https://example.com/the-unique-url-from-the-put-request
URL represents the upload_uri
in the response to the PUT
request.x-amx-server...
and content-type: txt/csv
represent the request_headers
provided in the response to the PUT
request.1curl --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
.