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
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
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.
Validate a list of email addresses
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
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:
emails
test@exampledomain.com
test2@exampledomain.com
differentTest@differentexampledomain.com
lastEmail@lastexampledomain.net
Step 2: Request the presigned URL and headers
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.
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
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.csvrepresents the relative path to your CSV or .zip file. - The
https://example.com/the-unique-url-from-the-put-requestURL represents theupload_uriin the response to thePUTrequest. - The
x-amx-server...andcontent-type: txt/csvrepresent therequest_headersrovided in the response to thePUTrequest.
curl --upload-file "./path/to/your/fileForUpload.csv" \
"https://example.com/the-unique-url-from-the-put-request" \
-H "x-amz-server-side-encryption: aws:kms" \
-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
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.
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.
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.
