Email validation integration for Cloudflare Worker

ZeroBounce email validation allows you to identify valid, invalid, and high-risk emails rapidly. The new integration with Cloudflare Worker allows you to validate emails on any of your websites in real time with zero overhead or slowdown. The seamless integration allows for zero impact on the user experience.

To start the Cloudflare Worker integration, you only need to copy and paste the worker script to your site. You do not need to clone any Git projects, install Wrangler, or any additional tools.Copy the worker script from here

However, there are several prerequisites that you must configure before applying the worker script.

Follow these steps to use the integration:

Step 1 - Create storage for your email validation logs

  1. From your Cloudflare account, go to the left-side menu and click Workers KV.
  2. Click Create namespace.
    Step_1_altScreenshot of the Cloudflare Workers KV Namespace to store email validation logs
  3. Enter a name for your logs in the “Namespace Name” field. We recommend using the name ZEROBOUNCE_LOGS.
  4. Click Add.

Step 2 - Create the worker

  1. From the left-side menu, click on Workers.
  2. In the Create a Service menu, enter a name in the “Service name” field. You can name this anything you want or use the default name provided by Cloudflare.
    Step_2_altA screenshot of the Cloudflare Workers menu where you can create a service for the ZeroBounce Cloudflare Worker integration
  3. From the options, select HTTP handler.
  4. Click Create service.

Step 3 - Setting variables

After creating the service, you will automatically redirect to the service overview.

From here

  1. Click on the Settings tab.
  2. Click on Variables.
  3. Click Add variable. Create the following variable names and values,
    Step_3_altExample of how to create variables to use in the ZeroBounce Cloudflare Worker integration
    Variable nameValue
    API_KEY(Retrieve your API and apply here)
    API_TIMEOUT5000
    VALID_STATUS[‘valid’, ‘catch-all’, ‘unknown’]

    For more in-depth explanation:

    ● API_KEY - Your ZeroBounce API key - Retrieve it from your account

    ● API_TIMEOUT - Time in milliseconds

    ● VALID_STATUS - Your accepted validation status codes. You can find more available email validation status codes and learn about them here

  4. For added security, click Encrypt next to your API_KEY variable.
  5. Click Save and deploy. Your results should appear as they do in the image below.
    Step_3_alt_2Example of what environment variables look like in Cloudflare Worker

Step 4 - Add a binding

  1. On the Worker details navigate to the Settings tab -> Variables, find the section titled KV Namespace Bindings. Click Add binding.
    2. Step_4_alt_1Screenshot of how to add a binding for a namespace in Cloudflare Worker
  2. Under “Variable_name,” enter LOGS.
    3. Step_4_alt_2Example of how to create logs for the ZeroBounce Cloudflare Worker email validation integration
  3. Under “KV Namespace,” select the namespace you created in step 1.
  4. Click Save and deploy.

The result should appear like the example below

Step_4_alt_3Example of a new LOGS variable for the ZeroBounce Cloudflare Worker integration

Step 5 - Add the Worker Script

  1. Click on the Quick Edit button on the Worker details page.
  2. Copy the worker script from here and paste it on the left hand side of the page:
    Step_5_altCloudflare Worker page that shows where to add the worker script
  3. Click Save and deploy.
  4. Your worker script has now been updated and is ready to be used.

Step 6 - Triggers

  1. Click on the Triggers tab.
    2. Step_6_alt_1Cloudflare Worker menu that shows where to add triggers and routes for the ZeroBounce integration
  2. Under the section titled “Routes,” click Add route.
  3. In the “Route” field, enter the website URL where you want to run the worker.
  4. Use the “Zone” dropdown to select a zone that matches the entered URL.
    5. Step_6_alt_2Example of how to create a route and zone for your Cloudflare Worker when using ZeroBounce email validation

Example

Route - "example.com"

Zone - example.com

By specifying this pattern, you are telling the worker to

  • Match all subdomains of “example.com”
  • Match all URLs of “example.com”

This is the most straightforward method of applying the worker. However, if you already have an existing worker on this route, you can run the worker on /contact only, for example.

With this, the installation is complete. You can test the Cloudflare Worker integration by entering an email on one of your website forms. You can then check the logs in your Worker KV namespace for the results.

Since this is key-value storage, each Log entry is prefixed, so you can also list all the records starting with a particular prefix. For example, you might want to see the records from a specific date, email, or URL.

The below example is a log prefix with a temporary email on a contact form.

{2023-02-25}-{caligyje@brand-app.biz}-{/.testing/contact.php}-{07:49}-47.373

You can use the following method to list logs by a specific prefix, for example, to list all logs from the 25th of February 2023:

Step_6_alt_3A log of results after using the ZeroBounce Cloudflare Worker integration

And for example, to list by email (you also need a date):

Step_6_alt_4Example of how to search for specific email validation logs in Cloudflare Worker

Troubleshooting

If you find issues with the worker, please try the following troubleshooting steps.

Validation Issues

If email validation does not occur, check the following:

  1. Ensure that your form has an email input, preferably with the name/id: “email”.
  2. Double-check your environment variables.
  3. Ensure that you deployed the worker on the correct URL route.

If the above checks out, you may enable the logging of the worker by going to the Logs tab (next to Triggers) and enabling real-time logs. Afterward, go to your form and try again with an invalid email. Logs should be generated which can identify the issue.

Execution Issues

Another common problem is that the worker might break some API request or other functionality. While this is unlikely, a fix is available.

  1. Return to the Settings tab and click on Variables.
  2. Create a new variable called BYPASS_PATH.
  3. Enter the path you want to ignore. For example, you could disable validation on Login paths: ‘/login,’ ‘/logout,’ ‘/connect,’ ‘/signing’