verifalia-widget

v1.14.1

Published

a month ago

A lightweight JavaScript widget with zero dependencies that performs real-time email address validation using the Verifalia email verification service. This widget integrates seamlessly with any web form to swiftly identify and eliminate invalid, undelive

Verifalia widget - Real-Time Email Verification for Your Web Pages

Verifalia provides a lightning-fast, powerful service for real-time email address validation and deliverability checks; drop this JavaScript widget into any web page, and it automatically binds to every input field of type email (or to fields with "email" in their name or ID - or any other fields matched by a configured XPath selector), preventing form submission unless the field contains a valid email address that points to an active, deliverable mailbox. The widget ships as a single, lightweight JavaScript file (9 KB gzipped), has no external dependencies, and offers a wide range of customization options.

By default, the widget blocks form submission for invalid, unreachable, disposable, and throw-away email addresses. You can easily change this to allow or exclude different address types - for example, addresses from free providers like Gmail or Yahoo. The widget works out of the box with all HTML5 forms, including mobile ones: just add it to a page, and it starts validating every email address in real time.

The widget also integrates with several CAPTCHA services - including Cloudflare Turnstile, hCaptcha, Google reCAPTCHA v2, and Google reCAPTCHA v3 - to make sure only real humans trigger email verifications.

If it detects any of the following validation libraries or form-building services on your page, the widget integrates with them automatically: Adobe Marketo Engage, FormSite, FormStack, FormValidation, Google Tag Manager (GTM), HubSpot, Instapage, jQuery Validation Plugin, Kendo UI for jQuery, KickoffLabs, Leadpages, Pardot, Parsley, SamCart, Unbounce, Validate.js, and Zoho Sites. Other form validation libraries may also work with the widget, but they aren't officially supported.

This widget is a great fit for many integration scenarios, but it only runs in the browser and has a limited set of extension points: for a more powerful, Node.js-compatible solution with a much richer feature set, check out the Verifalia SDK for JavaScript.

Installing the widget on your page

Using the Verifalia email verification service requires a Verifalia account - if you don't have one, sign up for free. You'll also need a browser app key (a short alphanumeric string). To create one, go to Team → Users & Browser Apps in the Verifalia client area and click Create: select Browser app as the user type and click Create to save.

Once you have a browser app, head to its Embeddable widget tab to generate the embedding code - it'll include the HTML snippet with your browser app key already filled in. Paste it into your page or form and you're good to go! For instructions specific to the validation libraries and form-building services we support, see the relevant sections below.

Manual installation

Instead of using the dashboard's code generator, you can manually copy the HTML block below and place it just before the closing </body> tag. Set the data-verifalia-appkey attribute to your browser app key (available in the Verifalia dashboard), or set it via JavaScript as described in the next section.

  ...

  <script defer
    src="https://unpkg.com/[email protected]/dist/verifalia-widget.js"
    data-verifalia-appkey="YOUR BROWSER APP KEY HERE"
    integrity="sha512-FmYZDXdfPJA66WfnM8PYo+T/epRUdbVzigcc9bpVD8xLvI2V2VRx4S6lWGdVHjfUpaIr4YrNhv6EZmc3wWsBDg=="
    crossorigin="anonymous"></script>

</body>
</html>

  ...

  <script defer
    src="https://cdn.jsdelivr.net/npm/[email protected]/dist/verifalia-widget.js"
    data-verifalia-appkey="YOUR BROWSER APP KEY HERE"
    integrity="sha512-FmYZDXdfPJA66WfnM8PYo+T/epRUdbVzigcc9bpVD8xLvI2V2VRx4S6lWGdVHjfUpaIr4YrNhv6EZmc3wWsBDg=="
    crossorigin="anonymous"></script>

</body>
</html>

CDNs courtesy of unpkg and jsDelivr.

Alternatively, you can also self-host the JavaScript file. Use npm to download it:

$ npm install verifalia-widget

After installation, the file is available at ./node_modules/verifalia-widget/dist/verifalia-widget.js.

How it works

The widget has no external dependencies. It works out of the box with standard HTML5 forms - including mobile ones - and integrates automatically with popular form validation libraries and form-building services, including Adobe Marketo Engage, FormSite, FormStack, FormValidation, HubSpot, Google Tag Manager (GTM), Instapage, jQuery Validation Plugin, Kendo UI for jQuery, KickoffLabs, Leadpages, Pardot, Parsley, SamCart, Unbounce, Validate.js, and Zoho Sites.

When one of these libraries or services is detected on the page, the widget adjusts its behavior to work alongside the existing validation logic and styles. You can further customize this behavior using the settings described below.

HTML5 forms

On load, if no supported validation libraries are detected, the widget uses plain HTML5 form methods. It automatically binds to every input field of type email, as well as to every input field whose name or id contains the word "email" (see autoWireup to disable this behavior, and selector to control which fields are bound). When the containing form is submitted - or while the user is typing - the widget verifies the email address and blocks submission if the address is invalid, points to an inactive mailbox, or is disposable or throw-away (see emailValidations to change the validation logic, and events to change which events trigger verification).

The widget automatically appends hidden fields to the form to store the Verifalia verification results, including the job ID, classification, and status. Each hidden field is named after the original field's name attribute, with one of these suffixes:

-verifalia-id - the Verifalia job ID (a unique identifier for the verification job);
-verifalia-classification - the result classification: Deliverable, Undeliverable, Risky, or Unknown;
-verifalia-status - the result status: Success, MailboxDoesNotExist, MailboxHasInsufficientStorage, etc. (see the complete list).

Security note: Don't rely solely on client-side data. Always double-check the submitted values on your back end: use the job ID to retrieve the full verification result via the Verifalia API, and confirm the email address, classification, and status match what was submitted. Check out the developer documentation for details on the API and the available open-source SDKs.

Visual feedback

When the widget binds to an input field, it adds the CSS class verifalia-field to it. During validation, it adds verifalia-field-processing, and once validation completes, it adds either verifalia-field-valid or verifalia-field-invalid. If the request is throttled, it adds verifalia-field-throttled. You can change any of these class names using the classNames setting.

The widget also shows these user-facing messages during the standard HTML5 form validation process:

Please hold on for a second, until we verify this email address... - while validation is in progress;
Please enter a valid email address. - if the address is invalid;
Too many attempts, please try again later. - if the request is throttled.

To customize these messages, use the messages setting.

For a better user experience, the widget also shows error squiggles after validation completes, to highlight typos or other issues:

You can turn off squiggles using the squiggles setting. Note the limitations around squiggles on <input type="email" /> fields with non-ASCII characters.

Directionality

The widget automatically detects the directionality of each bound input element and adapts its visual feedback accordingly. Its default CSS classes show a validity indicator on the right for left-to-right languages (Latin, Cyrillic, Greek, Indic, etc.) and on the left for right-to-left languages (Arabic, Hebrew, Persian, Urdu, Sindhi, etc.). Error squiggles follow the same directionality logic.

Because the widget reads the computed dir value, it automatically inherits the closest dir set on any ancestor element. The most common case is setting dir once on the root html element:

<html dir="rtl">
  ...
  <div>
    ...
    <input type="email" ...>

If a field needs to accept both left-to-right and right-to-left addresses - for example, when the direction isn't known in advance - set dir="auto" directly on the input field:

<html>
  ...
  <div>
    ...
    <input type="email" dir="auto" ...>

In this case, the widget adjusts the directionality of its visual feedback dynamically as the user types:

For advanced customization, the widget also sets a verifalia-field-dir attribute on each bound input element, reflecting its computed directionality (ltr or rtl). You can use this to write directionality-specific CSS rules:

.verifalia-field-invalid[verifalia-field-dir=rtl] {
  background-color: #f00;
}

Bot detection / CAPTCHA

The widget integrates with CAPTCHA services to ensure only real humans trigger email verifications, protecting your Verifalia credits and preventing throttling; you can run multiple widget instances on the same page, each with a different CAPTCHA service or different CAPTCHA settings.

The supported CAPTCHA services are: