Verifying emails with node.js

Prerequisites

To follow along with this tutorial, you'll need:

• Basic knowledge of Node.js

• A Mailgun account; to use bulk email validation, you must have a paid account

How to verify emails with Node.js and the Mailgun API

To verify emails with Node.js using the Mailgun API, you have to create a mailing list and add the emails you want to validate. You can then start a validation job on the mailing list and retrieve the results. But, before you can make requests to the Mailgun API, you need your authentication details from your dashboard. You also need to set up and verify a custom domain to create a mailing list.

Getting API keys and setting up a custom domain

The Mailgun API authorizes requests using HTTP Basic Auth, which requires that you include a username and password in your Authorization header. To obtain the required details, log in to your Mailgun account, click the dropdown icon at the top right of your screen, and click API Security in the menu:

On the API Security page, click the Add new key button to reveal a modal with a form. Fill out the description on the form, click Create Key, copy the API key, and store it securely; this is your password, and you can only see it once:

Next, you can choose to add a custom domain to your Mailgun account and verify it. This step is optional and is only required in production environments. For this tutorial, you'll use the default domain provided by Mailgun, which you can find by navigating to Send > Sending > Domains:

Note the default domain name; you'll need it to create a mailing list. After retrieving your authentication details and adding a custom domain (or noting the default), it's time to set up a Node.js development environment where you'll make requests to the Mailgun API.

Setting up your development environment

To set up a Node.js development environment, first create a new project directory and cd into it by running the following command:

The installed dependencies include the following:

• Axios: This is a library that allows you to send requests and receive responses from an API. You'll use Axios to communicate with the Mailgun API.

• Dotenv: This is a library that loads environmental variables to process.env. You'll use it to manage your authentication details securely.

• Form-Data: This is a library that creates readable multipart/form-data streams. The Mailgun API only accepts data in multipart/form-data, so you need this library to submit forms to the API.

After installing these dependencies, create an index.js file and a .env file. In your .env file, store the following variables and replace the placeholder values with their actual values:

This code block imports the dependencies required to make requests to the Mailgun API. In addition to the packages you installed earlier, the imports include the Node.js fs module, which you need to create a readable stream to the file containing your email list. Now that your development environment is ready, you can validate email addresses in a mailing list.

Validating emails in a mailing list

As mentioned in the prerequisites, to use the bulk email validation service with Mailgun, you must have a paid account.

To create a validation job with the Mailgun API, you need to make a POST request to https://api.mailgun.net/v4/address/validate/bulk/${listId}, where listId is any arbitrary value you assign to the validation job.

This endpoint accepts a form with a CSV file containing the email addresses you want to validate. The CSV file's column header for emails needs to be either email or email_address, and the format must be either raw CSV or gzip. You can include an unlimited number of email addresses in the file; however, the file size cannot exceed 25 MB.

The form key for the CSV file must be file, and the value must be a readable stream to the file path of your CSV file.

You can add the code block below to your index.js file to implement a function to create a bulk validation job:

Validating a mailing list takes time; to get the validation results, you have to make a request to the API with the id of your validation job.

Fetching validation results

To fetch the results of a validation job, you need to make a GET request to https://api.mailgun.net/v4/address/validate/bulk/${listId}, where the listId is the id you assigned to your validation job.

Add the following code block to your index.js file to implement a function to fetch your validation results:

Here's a breakdown of the results:

• created_at: A timestamp of when the job was completed (1728170695).

• download_url: Links to download the results in CSV and JSON formats.

• Quantity: The total number of emails processed (10).

• Status: The validation job status (uploaded).

• Result: The outcome of email validation:

• catch_all: No addresses are from catch-all domains.

  • deliverable: Three addresses are valid and deliverable.

  • do_not_send: No addresses are flagged as "do not send."

  • undeliverable: One address is invalid or undeliverable.

  • unknown: Six addresses couldn't be verified.

• Risk: A breakdown of email addresses by risk:

  • high: One address is high-risk and likely undeliverable or problematic.

  • low: Three addresses are considered low-risk and safe to use.

  • medium: No addresses are medium-risk and might require caution.

  • unknown: Six addresses couldn't be classified.

Error handling and debugging

When using the Mailgun API for bulk email validation, you may encounter a few common errors. Here's a breakdown of these errors and tips on how to troubleshoot them:

• List already exists: This 409 status code error indicates a validation job with the same listId as the one you're trying to create already exists. You can fix this error by changing the listId and retrying your request.

• List CSV file missing: This 400 status code error indicates that the API couldn't find the CSV file in your request because you're using the wrong file key. Make sure your file key is set to file, then try again.

• CSV File must contain the key email or email_address: This 400 status code error indicates that your CSV file is missing an email or email_address column header. You can fix this error by editing your CSV file to contain either of these headers.

• CSV file is malformed: This 400 status code error indicates that your file is in an unsupported format. Make sure that the file containing your emails is in CSV or gzip format.

• unauthorized: This 401 status code error indicates an issue with your authentication credentials. You can fix this by ensuring your API keys are valid.

Best practices for bulk email validation

To ensure your bulk validation jobs work as expected, here are a few best practices you can follow:

• Respect API limits: Make sure you adhere to the limits imposed by the Mailgun API to ensure that all your requests are processed. For instance, CSV files must not exceed 25 MB; files larger than this will trigger a 400 response. Additionally, the maximum number of validation jobs that can run in parallel is five. Exceeding this limit will result in a 400 response.

• Use batching to avoid API limits: If you're validating a large data set of emails, batch them into groups to manage the file size, but watch out for parallel processing limits.

• Check for specific status codes: Different errors require different handling strategies. For instance, a 400 Bad Request likely indicates an issue with the request format; do not retry. Instead, log the error and fix the request. A 500 Internal Server Error indicates a server-side issue, and you can retry after a backoff period.

Wrapping up

In this tutorial, you explored how to verify emails using Node.js and the Mailgun API. You learned how to create mailing lists, add members to those lists, and validate the email addresses in bulk.

Regular bulk email validation can significantly improve your email deliverability rates, maintain a clean, effective mailing list, ensure your messages reach their intended recipients, and help you maintain a good sender reputation.