verifalia-widget

Verifalia widget - Add real-time email verification to your page, with no coding required

Verifalia provides a powerful and super-fast service to validate email addresses in real-time and check whether they are deliverable or not; once included in a web page, this Javascript widget automatically binds to every input field of type email (or those with the email word in their names or IDs) it finds and prevents its containing form to be submitted, unless the field contains a valid email address pointing to an active and real mailbox. The widget comes as a lightweight (14KB gzipped) single Javascript file, with zero dependencies.

By default, the widget automatically blocks both invalid / unreachable email addresses as well as disposable and throw-away addresses but you can configure it very easily to exclude other ones (for example, those provided by free email service providers like Gmail or Yahoo).

While this widget is suitable for many integration scenarios, it only runs in the browser and its features are limited: check out the Verifalia SDK library for Javascript for a much more advanced solution with support for both Node (in addition to the browser), as well as a vastly extended set of features.

The Verifalia widget provides out-of-the-box support for:

• standard HTML5 forms (including mobile ones);
• Parsley form validation library;
• jQuery Validation Plugin.

Installing the widget on your page

To install the Verifalia widget on your page just add a script tag before the closing </body> tag and point it at the verifalia-widget.js, which can be grabbed from one of the CDNs which serve projects hosted on npm:

    ...

	<script defer
			src="https://unpkg.com/verifalia-widget@1.3.0/dist/verifalia-widget.js"
			integrity="sha512-GjFzFkgiZ5jou44x3UHFhTw5VwR9JqUyveSms0hkHmeyO6chhCxNNwM2Ftfw6AzNYXOZ/8v5/UkaXjvC4Z9wZg=="
			crossorigin="anonymous"></script>
  </body>
</html>

or

    ...

	<script defer
			src="https://cdn.jsdelivr.net/npm/verifalia-widget@1.3.0/dist/verifalia-widget.js"
			integrity="sha512-GjFzFkgiZ5jou44x3UHFhTw5VwR9JqUyveSms0hkHmeyO6chhCxNNwM2Ftfw6AzNYXOZ/8v5/UkaXjvC4Z9wZg=="
			crossorigin="anonymous"></script>
  </body>
</html>

CDNs courtesy of unpkg and jsDelivr.

Alternatively, you can host the Javascript file yourself: to do that, use npm to automatically download and install the required files. With npm installed, run the following from your project root:

$ npm install verifalia-widget

Once done, the verifalia-widget.js file will be available on the ./node_modules/verifalia-widget/dist/verifalia-widget.js folder.

Configuring the widget

First things first: using the Verifalia email verification service requires to have a Verifalia account: if you don't have one, just register for a free one. In addition to that, this widget requires a browser app key (a sequence of alphanumeric characters): create a browser app, if you don't have one already, and grab the provided app key.

Once you have your browser app key at hand, provide it to the widget using either Javascript or through special attributes applied to the body element of your HTML page, as explained in the next two sections.

Using Javascript

This method requires you to add a small configuration script before the inclusion of the verifalia-widget.js mentioned above, where you add a new property named VerifaliaWidgetConfig to the window object. This property will be read by the widget at its loading and allows to adjust its settings; modifying the VerifaliaWidgetConfig object after the widget is loaded won't have any effect.

Here is how to set your browser app key:

<script>
	window.VerifaliaWidgetConfig = {
		appKey: 'YOUR-APPKEY-HERE'
	};	
</script>

Using data-verifalia-* attributes

Alternatively, you can configure your widget by way of certain attributes whose names begin with data-verifalia-, which you can apply to the specific input field you wish the widget to bind to or to any of its ascendant elements, including the parent form or the document body (recommended option).

Here is, for example, how to set your browser app key at the body level:

<body data-verifalia-appkey="YOUR-APPKEY-HERE">
	...

For a complete list of the settings available to this widget, please see the Advanced settings section below.

How it works

While it does not have any dependency at all, the widget offers out-of-the-box support for standard HTML5 forms, Parsley form validation library and jQuery Validation Plugin. It eventually adapts its behavior depending on the presence of one of the mentioned Javascript libraries, in order to play nicely with the existing validation of the page.

HTML5 forms

At loading time, if no supported validation libraries are detected then the widget works using plain HTML5 forms methods and automatically binds itself to every input field of type email it finds in the page as well as to every input field whose name or ID contains the word email (see the autoWireup setting below to change this behavior). As soon as the containing form is submitted or while the user is typing into one of the bound fields, the widget performs an email verification on the typed value and eventually blocks the submission if the email address is invalid or points to an inactive mailbox or is disposable / throw-away (see the emailValidations setting to change the validation logic).

The widget automatically appends some hidden fields to the document to hold the response its gets from the Verifalia email verification service, including the job ID (a string representing the unique identifier for the job which Verifalia generates upon receiving an email validation request), the email validation classification and its status.

It names each added hidden field according to the original field name, appending one of these suffixes:

• -verifalia-id, where the hidden field contains the Verifalia job ID;
• -verifalia-classification, where the hidden field contains the result classification (Deliverable, Undeliverable, Risky and Unknown);
• -verifalia-status, where the hidden field contains the result status (Success, MailboxDoesNotExist, MailboxHasInsufficientStorage, etc. - see complete list);

For security reasons, it is strongly advisable to avoid relying only on the data you get from the client and, instead, always double-check the input values on your back-end: you may want to retrieve the validation on the server side using the aforementioned job ID and check whether the input email address, its classification and status matches the ones you have received along with your posted form. Verifalia comes with free and open source SDKs for the most common development platforms and programming languages, check them out here.

Upon loading, the widget adds the CSS class verifalia-field to the input fields it binds to; while the email validation is in progress it also adds the CSS class verifalia-field-processing and adds either the CSS class verifalia-field-valid or verifalia-field-invalid according to the validation outcome. In the event the request is throttled, it adds the CSS class verifalia-field-throttled to the field. These CSS classes offer a basic visual feedback for the email validation process and can be changed by way of the classNames setting mentioned below.

The widget automatically displays these feedback texts in response to the standard HTML5 form validation process:

• Please hold on for a second, until we verify this email address..., during the validation process;
• Please enter a valid email address., if the email address is invalid;
• Too many attempts, please try again later., if the request gets throttled.

To change these texts, use the messages setting described below.

Parsley

The Verifalia widget supports the Parsley form validation library out of the box. If it detects Parsley is loaded on the page, it automatically participates to the Parsley validation process and binds to input fields according to the HTML5 forms scaffolding logic mentioned above.

Under this mode, the widget does not add any CSS class to the fields, in order to play nicely with the existing Parsley visual feedback.

jQuery Validation Plugin

The widget supports jQuery Validation Plugin out of the box. If it detects jQuery Validation Plugin is loaded on the page, it automatically overrides the default email validation logic. Also no additional binding is done for input fields, in order to comply with the existing jQuery Validation Plugin configuration.

Under this mode, the widget does not add any CSS class to the fields, in order to play nicely with the existing jQuery Validation Plugin visual feedback.

Advanced settings

In addition to the required browser app key mentioned above, the widget recognizes and can accept several configuration settings, which override the default ones.

inputBindings

You can configure how the widget binds to the input fields through the inputBindings property. Here is the object structure and a type definition of the available properties:

inputBindings: {
	appendHiddenFields: boolean,
	autoWireup: boolean,
	classNames: {
		base: string,
		exception: string,
		invalid: string,
		valid: string,
		throttled: string,
		processing: string
	},
	debounceTime: number,
	events: string,
	preventSubmission: string,
}

See below for details about each setting.

appendHiddenFields

If true appends the hidden input fields to the form upon completing an email validation, with the validation outcome. Defaults to true.

autoWireup

If true enables the automatic binding of input fields at load time as described above. Defaults to true.

classNames

The CSS class names to add to the fields, according to the logic explained above:

• base contains the CSS class name to apply to each field the Verifalia widget attaches to, defaults to verifalia-field;
• processing contains the CSS class name to apply while the email validation is in progress, defaults to verifalia-field-processing;
• valid contains the CSS class name to apply for fields containing a valid email address, defaults to verifalia-field-valid;
• invalid contains the CSS class name to apply for fields containing an invalid email address, defaults to verifalia-field-invalid;
• throttled contains the CSS class name to apply if the email validation request has been throttled, defaults to verifalia-field-throttled;
• exception contains the CSS class name to apply in the event of a network or code error, defaults to verifalia-field-exception.

debounceTime

The time we allow between keystrokes before attempting to verify the input value for the field, expressed in milliseconds. Defaults to 500.

events

Zero or more input field events the widget binds to and triggers the email verification for, separated by a comma (,). Defaults to input.

preventSubmission

A string with the condition(s) which must prevent a form to be submitted, separated by a comma (,); the allowed conditions are:

• invalid, which means a field containing an invalid email address should not allow the parent form to be submitted;
• throttled, meaning an email validation request which exceeds the maximum limit (as configured in the Verifalia clients area) should prevent the form submission;
• exception, which causes email validation requests resulting in an error (such as a network error because of no connectivity to the Internet, for example) to prevent the form submission.

Defaults to invalid, throttled.

emailValidations

Defines the email validation logic and preferences for the Verifalia widget. Here is the object structure and a type definition of the available properties:

emailValidations: {
	allow: string,
	block: string,
	messages: {
		processing: string,
		invalid: string,
		throttled: string
	},
};

The widget only allows the email addresses which pass the allow rule and do not pass the block rule.

allow

A string with one or more classifications, status codes or attributes (free and role) the widget will allow to pass the form validation, separated by a comma (,). Classifications must appear using their names, status codes must use the prefix status: plus the actual status code value and attributes must use the @ prefix and either the free, role or disposable values. All the string is processed in a case-insensitive way.

Here is, for example, how to define the allow rule for a widget which allows Deliverable and Unknown classification as well as role accounts and catch-all mailboxes:

allow: 'deliverable, unknown, @role, status:ServerIsCatchAll'

The allow rule has a default value of deliverable, risky, unknown.

block

A string with the same format of the allow rule mentioned above.

Here is, for example, how to define the block rule for a widget which does not allow free email addresses (like those provided by Gmail and Yahoo):

block: '@free'

The block rule has a default value of @disposable.

messages

The texts for the messages the widget uses to provide feedback to the underlying form validation system:

• processing defaults to Please hold on for a second, until we verify this email address...;
• invalid defaults to Please enter a valid email address.;
• throttled defaults to Too many attempts, please try again later.;