Advanced options for the email verification widget

In this page

The email verification widget can be customised to suit your needs. The integration instructions should allow you to set up quickly, and once this is done, you can tweak the behaviour.

There are four attributes that can be customised. These are: disposable, role, public and unverified. For each of these, you are able to set a rule and a message. See the API docs for a definition for these attributes.

There are three rules you can pick from:

• allow will trigger the widget to show a green tick, and no error message.
• warn will trigger the widget to show an orange warning icon, and an error message.
• block will trigger the widget to show a red cross, and an error message. It will also prevent the user from submitting the form.

When using warn or block you can also provide a customised message.

Custom rules and messages

Below is an example of the rules that can be used to customise the widget:

    
rules: {
  disposable: {
    rule: "block",
    message: "We do not accept disposable email addresses, please enter a different email to continue"
  },
  role: {
    rule: "warn",
    message: "We prefer it if you provide your own email address instead of a shared inbox. You can still sign up with this one if you want."
  },
  public: {
    rule: "allow"
  },
  unverified: {
    rule: "warn",
    message: "We are not able to verify that this is a correct email address. You can sign up with it, but please check you don't have any spelling mistakes."
  }
}
    
  

Optional rules and messages

The rule and the message are both optional, here is an example of a partial customisation:

    
rules: {
  disposable: {
    rule: "block",
    message: "We do not accept disposable email addresses, please enter a different email to continue"
  },
  role: {
    rule: "warn",
  },
  public: {
    rule: "allow"
  },
  unverified: {
    message: "We are not able to verify that this is a correct email address. You can sign up with it, but please check you don't have any spelling mistakes."
  }
}
    
  

Default rules

In the absence of a specified rule, the following defaults are applied:

    
{
  disposable: {
    rule: "block"
  },
  role: {
    rule: "allow"
  },
  public: {
    rule: "allow"
  },
  unverified: {
    rule: "block"
  }
}
    
  

Check options

Controls the methods of verification to be completed.

domain is a check to verify that the domain of the email address has the expected DNS records.

    
check: "domain"
    
  

connection is a check to verify that the email account exists at the provided domain. This will impact the query processing time and data returned in the response.

    
check: "connection"
    
  

In the absence of a specified check value the following defaults are used.

    
check: "domain,connection"
    
  

Default responses

In the absence of a supplied message, the following default messages will be returned when the response matches the rules (supplied or default):

Custom Styling

Our Javascript widget includes a stylesheet that defines the visual aspects of the icons and messages that are displayed. You may decide to adjust the colours or fonts used to more closely match the branding of the page in which the widget is embedded. This can be done easily by overriding the default styles that are included in the file.

You can inspect the styles here (tip: use an online beautifier to make it easier to read) and then define your own CSS rules to override the default styles.

View a code example, where we use the Email widget with a different colour for the message.

Here is an example of the html elements that are included in the DOM:

    
<span class="af-ev-icon-block af-ev-icon" style="top: 768.943px; left: 632.458px; height: 26.5px; width: 26.5px;"></span>
<span class="af-ev-message" aria-live="polite" style="left: 270px; top: 811.484px; width: 400px; display: inline-block;">It looks like there could be a problem with this email address. You must enter a correct email address</span>
    
  

Collection of email metadata using the widget events

The widget can be configured to collect metadata from the Email Verification API response and populate this into fields of your form (hidden or visible to the user). The widget returns two events that can be used for this purpose. To view the full list of the metadata attributes available for collection, see the javascript docs.

View this code example demonstrating the use of the widget events.

Working inside a modal

Because modals are usually static in the context of the page, it is recommended when initialising the widget to provide a Node to the container option. This option takes an HTML Node that will be used as a basis for the HTML injected by the widget. As such, positioning of our loading indicator and feedback message to the user will still work as expected. An example of how to use the container option can be found here.

    
var conf = {
  // update the container property to the modal's parent container
  container: document.getElementById("modal-content").parentNode
}