Bulk Email Address Validation in Node.js

Time to read: 4 minutes

May 07, 2024
Written by
Yukti Ahuja
Twilion
Reviewed by
Chris Kemnitzer
Twilion
Jesse Sumrak
Twilion
Shanelle Thadani
Twilion

Bulk Email Address Validation in Node.js

Email address validation helps identify email addresses in your marketing lists and customer base that are likely to produce a hard bounce and impact your sender score. The validation algorithm runs numerous checks to determine if an address is legitimate, such as if a domain is set up to receive email, if it’s disposable, if the name was likely button mashed, and more.

Email address validation is one meaningful component of building strong email sending practices and reaching your customers. This blog post will provide an in depth tutorial of how to integrate with Twilio SendGrid’s Bulk Email Address Validation using Node.js.

For more information on how to integrate, check out the Email Address Validation documentation.

Real Time Validation vs Bulk Email Address Validation

When it comes to validating email addresses, there are two main approaches: real time validation and Bulk Email Address Validation. Real time validation has been around for a while, and involves validating email addresses one by one. This method is best suited for scenarios where only a few email addresses need to be validated or when validation needs to be seamlessly integrated into a user-facing application, like during the sign-up process on a website

Bulk email address validation is a crucial process for businesses and organizations engaged in email marketing that need more confidence within large subscriber lists or customer databases. This method is particularly useful for managing extensive amounts of data, and SendGrid’s implementation enables the validation of up to a million email addresses in one go. By ensuring the accuracy and deliverability of email lists before launching campaigns, Bulk Email Address Validation helps maintain good email deliverability and ensures that messages reach real, active recipients.

How do I get access?

Bulk Email Address Validation is exclusively accessible to Email API Pro and Premier level accounts. Until your account is upgraded to Pro or Premier, the option to generate an email address validation API key will not be visible. The email address validation API key is distinct from your other keys, and is essential for both asynchronous bulk email address validations and real-time email address validations. Employing this Bulk Email Address Validation feature aids in purifying your current database; however, SendGrid advises verifying email addresses upon their entry into your customer funnel.

You can use this API to:

  • Validate a CSV of email addresses asynchronously in a single job
  • The CSV can contain up to 1M emails or 50MB of data

Results are sent to the email address linked with the SendGrid account.

Prerequisites

API keys setup in sendgrid

Let’s get started

Here are the basic steps of our build today:

  • Upload a CSV
  • Get job status list
  • Get job status

Upload a CSV

Set Environment Variables

Create an .env file to store your environment variables SENDGRID_API_KEY in the following format. Further details about your node environment variables can be found here. It is advisable not to include this file in version control.

SENDGRID_API_KEY=<"YOUR_SENDGRID_EMAIL_VALIDATION_KEY">

Request the presigned URL and headers

The bulk email address validation process takes place asynchronously. This endpoint returns a URL (upload_uri) and HTTP headers (upload_headers) which can subsequently be used to PUT a file of email addresses to be validated.

Uploaded CSV files can be in the following formats: .csv or .zip.

You must include the field file_type with the value csv or zip in your request body.

You can find the code repository here: https://github.com/yuktiahuja-twilio/EmailBulkValidationApi.git

Example Node.js code 

const client = require('@sendgrid/client');
require('dotenv').config();
client.setApiKey(process.env.SENDGRID_API_KEY);


const data = {
	"file_type": "csv"
};

const request = {
  url: `/v3/validations/email/jobs`,
  method: 'PUT',
  body: data
}

client.request(request)
  .then(([response, body]) => {
    console.log(response.statusCode);
    console.log(response.body);
  })
  .catch(error => {
    console.error(error);
  });

Example code output

The output of this script will return job_id, upload_uri, and upload_headers.

Please make a note of the output from this script, which will include `job_id`, `upload_uri`, and `upload_headers`.

Make a second API call

Once you receive the response body you can then initiate a second API call where you use the supplied URL and HTTP header to upload your file.

File Format

The uploaded file must be saved either as a CSV or ZIP, ensuring alignment with both the file type specified in the initial request and the expected headers in the response containing the URL. The file should have the header "emails" and exclusively contain the email addresses intended for validation.

For csv file sizes please refer here.

Example CSV Contents

emails
yahuja@twilio.com
sendgriddemo1@gmail.com
test@exampledomain.com
test2@exampledomain.com
eofjeh@mail.con
differentTest@differentexampledomain.com
lastEmail@lastexampledomain.net
AaBbCcDd@gmail.con
ajsiof@gmail.com

Example Node.js code 

const axios = require('axios');
const fs = require('fs');

// Replace these with your actual values

const filePath = '/Users/yahuja/Demo/sgEmailValidation/spreadsheet/emailvalidation.csv'; // The path to the file you want to upload
const uploadUri = 'https://evbulkupload-prod-us-east-2-emails-csv.s3.us-east-2.amazonaws.com/25810133_01HNPW0EA2XWEH0C0TZ6ARYRZD?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAS4765TJFFO7HTIDY%2F20240203%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Date=20240203T065530Z&X-Amz-Expires=3600&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEKf%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMiJIMEYCIQDNXDJaL3Tta8VgH1X6vU%2FkNTjHFdC1M5mBox2Lc%2BkJFAIhALAhfKW4X2cfaVRXSM9T3NXr4KsxmTz3J%2FGhnqEUWRRLKosDCHAQBBoMMTk5NzEzNzI1MDAyIgxpw6miFKHjiWtMO5Qq6AKLuccBukE8Oec89Hyv6XWhgMA3VkbxA%2FGoB6WmG38fp%2BN5%2Blf2%2BP7sYn0P7jGd3S3GEbwP%2FKa2p4jVKrGw802Nvo%2BlXSlmaFlsl9t2I3Dzsh%2F63wcmc%2FrpZO6PB6bZbNsuvNrjS9s3Mp0Sj7d0v6pv7C4CSxZvS8Z56I%2BbdV7KVz5DQnSw%2Fn4%2BpIZ0xi62HFry4yGzhfoUBqedpdm5mRTeCJmqLFX0wJQRlrpEMdu3%2FaasPOOSd6E6dUYDDcKdWuGOLveTcxzqfIEvM84kp1uv2lM%2BL0ZpqY1CMpGaldjrITLaIE9PjtL7Au%2BxJR5f%2FYrG2nqmseR4LGLewOLykFoc2s7xPO1LrWbOoXav6nfzJHZMgff4Vw6QRr6auCikPDpupLzojD%2BdXsLFycPga70SuISrsT05GM8wOpYXqciacCrBUvhAmxmARzETFQOUEq6kQcKXCWhdzlCsim2FT3UcxTy%2BxRLyaVUw7cX3rQY6nAE1UydxDZ96d3oSwG%2BXBmC0jSiJkvzQkiMx0CL00NMhd%2BeISnevMT%2BCwCt5NQ9g6th6Kj97KuaO9xLHjsiwChViTZjvMasmI769jDgSErxYjz9jhAU4PWRIx1IQVexKUvD17O%2FMT7Bn%2FkRGuZxFgwdcpHlYoBU%2BWe15RYTMrlvpN8IbgKOxMMuxcDVdAtrJU%2FsGxtvbhn3A3TQtghE%3D&X-Amz-SignedHeaders=content-type%3Bhost%3Bx-amz-server-side-encryption&X-Amz-Signature=d7228a5b141f4fb2694fa63d4af93f7269f815dca78a5e0f6810c3136fbdc720'; // The URI you received from the previous request

const fileSize = fs.statSync(filePath).size;

const uploadFile = async (filePath, uploadUri) => {
  try {
    const fileStream = fs.createReadStream(filePath);

    const response = await axios.put(uploadUri, fileStream, {
      headers: {
        'x-amz-server-side-encryption': 'aws:kms',
        'content-type': 'text/csv',
        'Content-Length': fileSize
      },
    });

    console.log('File uploaded successfully', response.data);
  } catch (error) {
    console.error('Error uploading file', error.response ? error.response.data : error.message);
  }
};
uploadFile(filePath, uploadUri);

Example code output

The upload is successful!

The csv file is uploaded successfully.

Get Job Status List

This endpoint retrieves information on all bulk email address validation operations associated with a user.

Example Node.js code 

const client = require('@sendgrid/client');
require('dotenv').config();
client.setApiKey(process.env.SENDGRID_API_KEY);

const request = {
  url: `/v3/validations/email/jobs`,
  method: 'GET'
}

client.request(request)
  .then(([response, body]) => {
    console.log(response.statusCode);
    console.log(response.body);
  })
  .catch(error => {
    console.error(error);
  });

Example code output

All the bulk email validation endpoints for the user. Please take note of the id and the status parameter.

Get Job Status

This endpoint gives you all the details about a specific bulk email address validation job. Take note of the id parameter mentioned earlier and substitute it in the following code snippet.

Example Node.js Code

 

const client = require('@sendgrid/client');
require('dotenv').config();
client.setApiKey(process.env.SENDGRID_API_KEY);

const request = {
  url: `/v3/validations/email/jobs/01HN16FEFV9SDQQ2AYVX65VPKX`, //replace the job_id here
  method: 'GET'
}

client.request(request)
  .then(([response, body]) => {
    console.log(response.statusCode);
    console.log(response.body);
  })
  .catch(error => {
    console.error(error);
  });

Example code output

Successful result of bulk validation api call via node.js

Final Results

Once the job is finished, you'll receive an email in your inbox with a link to download the output CSV. If there's an error during the job processing, you'll also get an email notification in your inbox.

Snapshot of the email from SendGrid when the email validation export is ready

When you click the Download option, the file opens in your SendGrid portal and should initiate an automatic download.

Download the export of bulk email address validation results

Here is a sample output for my csv:

CSV output example

You can use a mix of these fields to refine your search for what you consider a valid address. Verdict section provides one of three classifications: "Valid," "Risky," or "Invalid." These categories are based on the detailed results. Score is the value ranging from 0 to 1, indicating the probability that the email address is valid, expressed as a percentage. For example, a score of 0.94 could be interpreted as a 94% likelihood that the email is valid.

The API returns a verdict of VALID, RISKY, or INVALID. The score is also returned to provide more fine grain details. A score of 0 maps to INVALID. A score > 0 but < 0.66 maps to RISKY. A score >= 0.66 maps to VALID.

Additional details on interpreting the results can be found here.

Conclusion

Conducting an email address validation check is a proactive measure that positively impacts your long-term email marketing efforts. This not only reduces the risk of emails bouncing but also plays a crucial role in building a positive sender reputation, ultimately boosting the success of your email campaigns. For more information on Single vs Bulk Email Address Validation API please visit the technical documentation here .

Now that you have the capability to programmatically utilize the Bulk email address validation API, I'm excited to see what you build! Don't hesitate to reach out to sendgrid support to share your experiences, or ask any questions .

Related Posts

Related Resources

A newspaper article

Twilio Docs

From APIs to SDKs to sample apps

API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.
An Open book

Resource Center

The latest ebooks, industry reports, and webinars

Learn from customer engagement experts to improve your own communication.
User group reactions

Ahoy

Twilio's developer community hub

Best practices, code samples, and inspiration to build communications and digital engagement experiences.