Advanced options

The email verification JavaScript widget is highly customisable to suit your needs. The installation instructions should allow you to get started quickly. Once this is done, you can further tweak the widget's behaviour using the options below.

Attributes

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"
  }
}

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):

Response	Default warn message	Default block message
disposable	"This is a disposable email address."	"Disposable email addresses are not permitted."
role	"This is a group email address."	"Group email addresses are not permitted."
public	"This is a public email address."	"Public email addresses are not permitted."
unverified	"This email address could not be verified. Check spelling and retry."	"This email address could not be verified. Check spelling and retry."

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"

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>

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
}