Building a Bulk DNS Email Validation Service using Cloudflare Workers and ApyHub API

Use case: An application requires a mechanism to validate a list of emails provided by the user in a CSV file format. The goal is to filter out emails that do not pass the DNS validation process, separating them between valid and invalid ones. This can ensure that the application only processes or uses email addresses that are likely to be active and properly configured according to DNS records.

Approach: Creating a serverless function that validates email addresses using Cloudflare Workers and ApyHub's DNS Email Validation API

What the serverless function will do:

Receive and parse the CSV file of email addresses
Validate the email address and assign it to a category. ( validEmails and invalidEmails)
After all, emails are processed, the function generates and returns a new output CSV file that contains valid and invalid email addresses.

This tutorial will guide you through setting up your development environment, writing the serverless function in TypeScript, testing its functionality, and deploying the function with Cloudflare Workers.

Prerequisites:

Standard IDE ( VSCode/Sublime)
Node.js installed on your computer.
An account with Cloudflare Workers.
An API key from ApyHub after signing up for their DNS Email Validation API.

PART 1: Setting Up Your Project

Step 1: Create a new directory for your project and navigate into it:

cloudflare-email-validator
cd cloudflare-email-validator

Step 2: Install the Wrangler package

To install the Wrangler package in the directory, run the following command in the terminal:

npm install wrangler --save-dev

Step 3: Create a new Worker project

To start creating your Worker project, run the following command:

npm create cloudflare@latest

This command will prompt you to answer a few questions. Here are the answers you should provide:

In which directory do you want to create your application? Write email-validation-worker and press Enter.
What type of application do you want to create? Select Hello World worker and press Enter.
Do you want to use TypeScript? Select Yes and press Enter.
Do you want to deploy your application? Select Yes, you will be asked to authenticate using your Cloudflare account (if not logged in already)

Once you've answered all the questions, Wrangler will create a new directory with the name email-validation-worker. In the src/ folder of your new project, you will find the index.ts file. This is where you will write your email validation function.

Note: Feel free to delete the existing template code, as we will start writing from scratch.

PART 2: Writing a Serverless Function

Step 1: Handling the Incoming Request

The function starts by checking if the incoming request is a POST request. If not, it returns a 405 status code, indicating that the method is not allowed.

export default {

    async fetch(request: Request, env: any, ctx: any): Promise<Response> {
        if (request.method !== 'POST') {
            return new Response('Expected POST',{ status: 405 });
   }

Step 2: Parsing the Uploaded CSV File

It then attempts to parse the uploaded file from the request's form data. If no file is found, or the file is not a valid File object, it returns a 400 status code, indicating a bad request.

const formData = await request.formData();
const file = formData.get('file');
if (!file || !(file instanceof File)) {
    return new Response('No file uploaded', { status: 400 });
}

// The content of the file is read as text, and each line is split into individual email addresses. 

// Empty lines are filtered out.

const text = await file.text();
const emails = text.split('\n').map(email => email.trim()).filter(email => email !== '');

Step 3: Validating Emails in Batches

The function then processes the list of emails. For each email, it validates the email by calling the validateEmail function and waits for the result. This is done sequentially, with a 1-second delay between each email validation.

for (let i = 0; i < emails.length; i++) {
            const email = emails[i];
            const result : any = await this.validateEmail(email);
            if (result.data) {
                validEmails.push(email);
            } else {
                invalidEmails.push(email);
            }
            // Wait for 1 second before processing the next email
            await new Promise(resolve => setTimeout(resolve, 1000))
}

After receiving the validation results, emails are categorised into validEmails and invalidEmails based on the response from the validateEmail function.

Step 5: Generating a New CSV File

Once all emails are processed and categorised, the function generates a new CSV content string. It iterates over the original list of emails and matches them with their validation status. The CSV string is constructed by combining both valid and invalid emails, ensuring that undefined values are replaced with an empty string.

let csvContent = 'Emails,Invalid Emails\n';
emails.forEach((email, index) => {
    csvContent += `${email},${invalidEmails[index]}\n`;
});

//`csvContent` is then returned as a response with the appropriate headers to indicate the content type as CSV and to prompt the user to download the file named `email_validation_result.csv.`

return new Response(csvContent.replaceAll('undefined', ''), {
    headers: {
        'Content-Type': 'text/csv',
        'Content-Disposition': 'attachment; filename="email_validation_result.csv"'
    }
});

Step 6: Validating an Email with ApyHub's API

The validateEmail function performs the actual validation by sending a POST request to ApyHub's API endpoint with the email address to be validated. The API key is included in the request headers.

const apiResponse = await fetch('https://api.apyhub.com/validate/email/dns', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'apy-token': 'YOUR_SECRET_API_KEY' //provide your secret-token-here
    },
    body: JSON.stringify({email})
});

Note: It checks if the API response is successful. If not, it logs an error and returns false. If the response is successful, it returns the JSON-parsed response, which includes the validation result.

Step 7: Testing Your Function

After deploying, you can test your serverless function by sending a POST request with a CSV file of email addresses to your Cloudflare Worker's URL. Use tools like Fusion or cURL for this purpose.

Testing function using Fusion API Client

Testing function using Fusion API Client

Step 8: Deploy your function to Cloudflare Workers.

If you did not deploy your Worker during Step 1 of setting up your project, deploy your function via this command.

npx wrangler deploy

That's it! 👏

You have successfully created and tested the email validation worker. Now it's time to celebrate with a drink. Cheers 🥂

References:

For detailed documentation on Cloudflare Workers and ApyHub's API, visit their official websites.

The complete code and additional resources for this project are available in this GitHub repository.