Recipe: Real-Time Email Verification in HubSpot

A Kickbox integration served two ways — on-demand for your sales team, automated for your marketing stack.

About This Recipe

Most CRM setups treat email verification as an afterthought — a bulk process run occasionally by an admin. This recipe takes a different approach: baking verification directly into HubSpot so that both individual sales reps and automated workflows can validate email quality exactly when it matters.

The result is a two-component integration: a CRM UI card for on-demand lookups, and a custom workflow action for automated verification at any point in your contact lifecycle.

Ingredients

Accounts & Keys

• 1× HubSpot account with admin access — production/sandbox (Enterprise or Ops Hub Pro tier required), or a free developer test account which bypasses tier gates entirely
• 1× Kickbox Account with an API key
• 1× Postman (or any API client) — for the UI card component only

Environment

• Node.js 18 or higher
• HubSpot CLI (npm install -g @hubspot/cli)
• A code editor (VS Code recommended)
• This repository: https://github.com/Suixcity/kickbox

From the pantry (provided in this repo)

• React 18 UI extension — the contact record card
• Two serverless functions — backend verification logic
• A complete HubSpot project config — ready to deploy

Method

Mise en Place — Get Your Station Ready

Before you touch the stove, prep your ingredients:

1. Choose your HubSpot account — you can deploy to a production account, a sandbox, or a free developer test account. A test account is the safest place to start if you haven't done this before
2. Enable CRM Development and generate a Personal Access Key for that account
3. Authenticate the HubSpot CLI with that key:

   hs account auth 

4. Add your two secrets — think of these as your mise en place, measured out and ready:

   hs secret add kickbox        # Your Kickbox API key hs secret add private_app    # Placeholder for now — you'll swap this shortly 

Chef's note: Secret names must be exact. kickbox and private_app are referenced directly in the code. A typo here will leave your dish under-seasoned.

Part One: The UI Card

A card embedded in the HubSpot contact record — one click, instant verification.

1. Clone and deploy

Pull the recipe from the repo and upload it to HubSpot in two commands:

git clone https://github.com/Suixcity/kickbox cd kickbox/Kickbox hs project upload 

HubSpot will build and deploy the project. When it finishes, a legacy app called kickbox-verification will appear in your HubSpot account — that's your dish coming out of the oven.

2. Glaze with the real access token

Grab the access token from the newly created legacy app (Development → Legacy Apps → kickbox-verification → Auth tab → Access Token) and update the placeholder secret:

hs secret update private_app 

3. Create the CRM properties

This step creates the 11 custom contact properties that verification results will be written into. Think of it as setting the table before the guests arrive.

First, create a property group in HubSpot named exactly kickbox:

Settings → Properties → Groups → Create group: kickbox

Then fire a batch POST request to the HubSpot properties API, authenticated with your legacy app token. The full JSON payload is available in the GitHub repo — it creates all properties in one shot and should return a 201 COMPLETE. Use Postman (web or desktop) or curl — either works fine.

4. Add the cards to contact records

Settings → Objects → Contacts → Record Customization → Default view → + → Card library

Two cards are available:

• Kickbox Card - Tab — full tab view on the contact record
• Email Verification Card - Side — compact sidebar version

Add one or both, save, and you're plated.

5. Taste test

Open any contact with an email address, click "Verify Email with Kickbox", and confirm the results appear. A success banner and populated properties mean the dish is ready to serve.

Part Two: The Workflow Action

A custom coded action for automated verification inside HubSpot workflows.

This component uses a separate secret named kickboxapi — note the different name from kickbox used in Part One. Both can coexist in the same HubSpot account.

1. Season with the secret

Add your Kickbox API key under the new secret name:

hs secret add kickboxapi 

Or add it directly inside the workflow action editor in the next step.

2. Build the action

In HubSpot, go to Automation → Workflows, open or create a contact-based workflow, and add a Custom Coded Action step:

• Runtime: Node.js 20.x
• Secret: kickboxapi
• Input: Email field → mapped to the contact's email property
• Code: Paste the full action code from the GitHub repo

3. Configure your outputs

The action returns 10 output fields — the full verification payload from Kickbox. These become data tokens usable in any downstream workflow step:

4. Build your branching logic

With the output in hand, add an If/Then branch after the action — for example:

result = "deliverable"  →  Enrol in sales sequence result = "risky"        →  Flag for manual review result = "undeliverable" → Add to suppression list 

This is where the flavour really comes through — email quality becomes an active signal in your automation, not a static field that gets checked once a quarter.

Plating Notes

• Both components write to the same set of HubSpot contact properties, so verification data is consistent whether it came from a sales rep clicking the card or an automated workflow running overnight
• The Kickbox API key is never exposed client-side — all calls pass through serverless backend functions and HubSpot's encrypted secrets store
• Properties are created once and persist on all contact records going forward

Serving Suggestion

A common pattern worth stealing:

New contact enters the CRM → Workflow action verifies email → Branch on result → Deliverable contacts route to sales → Everything else gets flagged or suppressed

This ensures your sales team only ever receives contacts with verified email addresses — and your marketing lists stay clean without anyone having to run a manual bulk check.

Shelf Life

This recipe is built on HubSpot project platform v2025.1 — and HubSpot's platform versioning has been, frankly, inconsistent. Features have been dropped and reintroduced between minor versions, and naming conventions have shifted mid-cycle (the CLI still calls the deployed app a [private app] in its output while the HubSpot UI lists it under Legacy Apps).

The current situation: v2025.1 is unsupported after 1 August 2026. The migration target is v2025.2 — but v2025.2 removes serverless functions, which this recipe depends on for its backend. Serverless is scheduled to return in v2026.03, available from ~30 March 2026.

The plan: skip v2025.2, wait for v2026.03, and update this recipe at that point. If you're reading this after March 2026 and the guides feel stale, that migration is likely the culprit — check the HubSpot developer changelog for the current state of play.

Full Recipe

The complete source code, detailed step-by-step setup guides, and the full Postman payload are available in the GitHub repository:

github.com/Suixcity/kickbox

Part of a professional portfolio — view the project brief