Verifalia widget - Add real-time email verification to your page, with no coding required
input field of type
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).
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:
$ npm install verifalia-widget
Once done, the
verifalia-widget.js file will be available on the
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.
body element of your HTML page, as explained in the next two sections.
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>windowVerifaliaWidgetConfig =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
For a complete list of the settings available to this widget, please see the Advanced settings section below.
How it works
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
input field whose name or ID contains the word
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 (
-verifalia-status, where the hidden field contains the result status (
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-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.
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
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.
In addition to the required browser app key mentioned above, the widget recognizes and can accept several configuration settings, which override the default ones.
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:autoWireup: booleanpreventSubmission: stringappendHiddenFields: booleandebounceTime: numberclassNames:base: stringprocessing: stringvalid: stringinvalid: stringthrottled: stringexception: string
See below for details about each setting.
true enables the automatic binding of
input fields at load time as described above. Defaults to
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.
true appends the hidden
input fields to the form upon completing an email validation, with the validation outcome. Defaults to
The time we allow between keystrokes before attempting to verify the input value for the field, expressed in milliseconds. Defaults to
The CSS class names to add to the fields, according to the logic explained above:
basecontains the CSS class name to apply to each field the Verifalia widget attaches to, defaults to
processingcontains the CSS class name to apply while the email validation is in progress, defaults to
validcontains the CSS class name to apply for fields containing a valid email address, defaults to
invalidcontains the CSS class name to apply for fields containing an invalid email address, defaults to
throttledcontains the CSS class name to apply if the email validation request has been throttled, defaults to
exceptioncontains the CSS class name to apply in the event of a network or code error, defaults to
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: stringblock: stringmessages:processing: stringinvalid: stringthrottled: string;
The widget only allows the email addresses which pass the
allow rule and do not pass the
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
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
Unknown classification as well as role accounts and catch-all mailboxes:
allow: 'deliverable, unknown, @role, status:ServerIsCatchAll'
allow rule has a default value of
deliverable, risky, unknown.
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 rule has a default value of
The texts for the messages the widget uses to provide feedback to the underlying form validation system:
Please hold on for a second, until we verify this email address...;
Please enter a valid email address.;
Too many attempts, please try again later.;