Client side integration

ZingVerify is designed to be integrated into website forms that have email fields, to help determine whether or not they are valid. It also detects mistyped email addresses and shows suggested corrections.

Adding ZingVerify to your website is simple.

You will need access to your HTML code or your CMS (Content Management System).

Step 1:

Copy your unique script tag once signed up or signed in.

Step 2:

Paste the script tag just before the </head> tag in your HTML code or CMS.

That's it! The script tag loads an external JavaScript file asynchronously so will not impact the load time of your page. It will look something like this:

Time to Test

You are now ready to test the client side integration. Once the script tag is on your page, you will then be able to see the validation in action. As you type in the email field you should see the validation icon appear. Stop typing and you should see the result. It should behave similar to this:

See the Pen Simple email verification by Zing Verify (zingverify) on CodePen.

Server side integration

Server side integration is optional but allows you to collect the verification results via an API. Please make sure you have followed the Client side integration instructions before trying to fetch results.

Request


https://v1.fetch.zingverify.app/email

Query string parameters
publickeyRequired Sign in to access your Public Key which is unique to your website.
privatekeyRequired Sign in to access your Private Key which is unique to your website. Do not share.
emailRequired Email address from the form submit.

Response


Code
200 OKVerification result as JSON.
400 BadRequestError is indicated in the response message.
401 UnauthorizedCheck your public and private keys.
429 TooManyRequestsAbnormal amount of requests from your IP address.
This service should be used straight after the form submit.
Body
200
400 401 429
Fields
successtrue
false
Result successfully fetched.
If false, look in message for error description.
messagestring
null
Error message if success is false.
emailAddressstringEmail address for fetched verification result.
validtrue
false
null
Email address can receive mail.
null if recipients mail server was unable to respond in a reasonable timeframe.
resultCodeintIndicates the meaning for verification result.
See Result codes.
resultMeaningstring
possibleMistypetrue
false
null
Email address is detected as a possible mistype.
null if it can't be determined.
suggestedtrue
false
null
Email address was suggested to the user due to a mistype.
null if it can't be determined.
verifiedDateTimedatetimeWhen the verification result was processed.
ISO 8601 standard format. Always in UTC.
timeStampdatetimeWhen the response was created.
ISO 8601 standard format. Always in UTC.

Settings

Some styling and functionality settings are available once signed in. These can be found when editing the website.

  • Show verification icon - Show the verification icon to let people know the validity of the email address.
  • Show mistype suggestions - Show email address suggestions to people when they have mistyped their email address. The suggestion will appear below the email input box.
  • Prevent form submit - Prevent people from submitting the form if they enter an invalid email address. It works on all modern browsers using HTML5 form validation or the jQuery Validate plugin.

Styling it up (using CSS)

By default the verification icon will indicate the result which is usually sufficient for most websites. You can easily add additional styling to the input box based on the verification result using these CSS classes:

  • zv__valid - set when email address is valid
  • zv__invalid - set when email address is invalid
  • zv__suggestion - set when there is a suggested email address. Note: There will also be one of the above CSS class on the field

See the Pen Simple input element style by Zing Verify (zingverify) on CodePen.

Session Tracking

To allow for detailed reporting, you can optionally add some session tracking parameters. The parameters available are:

  • campaign - Name of the marketing campaign for the website traffic, e.g. "Free Trial".
  • source - Source of the website traffic, e.g. "Facebook".
  • subsource - Sub-source of the website traffic, e.g. "Banner A".

To set the session tracking values, add an event listener to the ZingVerifyLoaded event on the document, then call the zingverify function with "track", parameter name and parameter value.

"it's a kinda magic" (field binding)

By default the script will look for all input fields on the page with a type of "email" i.e.

If you have email address fields that are not input fields of type email, or they are dynamically added after page load, then you may need to manually bind to them. This can be done by calling the zingverify function with parameters "bind" and element, respectively.

See the Pen Simple manual binding by Zing Verify (zingverify) on CodePen.

More functionality? (using Javascript)

By using Javascript, a web developer can make customisation to the form and make decisions based on the verification result. ZingVerify exposes the verification and suggestion results on the bound input fields via two objects:

  • zingVerifyVerificationResult - the result of the email verification.
    • .EmailAddress - associated email address for the verification result
    • .Valid - if emails can be sent to this address
    • .ResultCode - Code indicating result. See below.
    • .ResultMeaning - Friendly explanation for the result. See below.
  • zingVerifySuggestionResult - the suggestion which will be displayed to the user.
    • .EmailAddress - suggested email address due to mistype
See result codes and their meanings.

Custom events

So that web developers do not need to keep querying to see if the results have been updated, ZingVerify triggers Javascript events. You can listen to these events and act on them using standard event listeners.

The three events which can be triggered on the input field are;

  • ZingVerifyLoaded - triggers when the integration has loaded and is ready for commands such as bind or track; it's always after the document DOMContentLoaded event
  • ZingVerifyVerificationResult - triggers when a verification result is changed
  • ZingVerifySuggestionResult - triggers when a mistyped email is suggested

Combining the events and objects properties allows huge flexibility.

See the Pen Simple validation result by Zing Verify (zingverify) on CodePen.

Result codes

Result codes and their means are exposed in the JavaScript and Server side integration.

Result CodeResult Meaning
-3Invalid API key
-2API key not allowed from this web page
-1Error - please contact support
0Unknown
1Valid
2No Server
3No Mailbox
4Verification aborted due to taking too long
5Blocked by mailbox provider's server
6Invalid email address
7No MX Records
8Disposable email address
9Verification aborted due to Greylisting by the mailbox provider's server
10Mailbox is full so cannot accept emails
11The email has been blocked by a configuration setting
12Catch-all - Server accepts mail even if mailbox doesn't exist

Any questions?

We are here to help! Contact us