Kickbox Email Verification in HubSpot Workflows

What is Kickbox?

Kickbox is an email verification service that helps you maintain a clean, healthy email list. Instead of verifying your entire database at once (which can be expensive), we'll verify emails one at a time as contacts enter your workflows. Smart, right?

The star of the show is the Sendex score — a quality rating from 0 to 1 that tells you how likely an email is to be deliverable. The higher the score, the safer it is to email that contact.

Before You Start

You'll need a few things set up in HubSpot before we dive into the code:

1. A Kickbox API key — Sign up at kickbox.com and grab your API key
2. A HubSpot Private App — Create one with crm.objects.contacts.write scope
3. Two secrets in your workflow:
   • academy_secret — Your HubSpot Private App token
   • KickboxKey — Your Kickbox API key
4. A custom contact property called kickbox_sendex (Number type)

Don't worry if you're not sure how to set these up — HubSpot's documentation walks you through each step.

Step 1: The Basic Structure

Let's start with the skeleton of our custom coded action. Every workflow action needs to import libraries, connect to HubSpot, and grab the contact's email. Here's what that looks like:

Notice how we're using async on our main function? That's because we'll be making API calls, and we want to wait for them to complete. The event.inputFields['email'] gives us the contact's email — you'll need to add "email" as an input field when configuring your workflow action.

Step 2: Add Error Handling

Things don't always go according to plan. APIs can be slow, networks can hiccup, and rate limits can kick in. Let's wrap our code in a try-catch block so HubSpot knows to retry if something goes wrong:

Step 3: Call the Kickbox API

Now for the fun part! We'll call Kickbox's verify endpoint with the contact's email. We use encodeURIComponent to handle any special characters in email addresses (like + signs):

Kickbox returns a ton of useful data — including the sendex score we're after. The response also includes things like whether the email is disposable, a role address, or has obvious typos. You could store all of these if you wanted!

Step 4: Store the Result in HubSpot

We've got the sendex score — now let's save it to the contact record. We use the HubSpot client's basicApi.update method to patch the contact properties:

The Complete Code

Here's the final version with everything put together. Notice we also use the callback function to return the sendex score as an output. This means you can use it in subsequent workflow actions — like branching based on the score!

Using the Output in Your Workflow

After your custom coded action runs, the sendex_score output becomes available to the rest of your workflow. Here are some ideas for what to do with it:

• Score ≥ 0.7: Safe to email — continue with your regular workflow
• Score 0.4 - 0.7: Proceed with caution — maybe send to a re-engagement campaign first
• Score < 0.4: High risk — consider removing from marketing emails

You can create an if/then branch in your workflow that checks the sendex score and routes contacts accordingly. Clean data, happy marketing team!

Ready to Build Your Own?

Custom coded actions open up a world of possibilities in HubSpot. Whether it's email verification, data enrichment, or connecting to any API — you've got the power.