Widget

Install the embed code

Using our widget is the easiest way to get email verification integrated into your existing website. Just install our embed code and we’ll do the rest.

Click here to go to the API page. Click “New Key” and create a Public API key. After you select Public, you will see an input for Trusted Domains. Be sure to enter the domain(s) that you will be installing the embed code on.

For the security of your account, Public API Keys are restricted to 10 unique verifications per day per IP Address. All requests sent after the limit is reached will fail with a 429 status code response. If you need to do more extensive testing please make sure you use a Test Key which does not have this limit.

Once you have an API key, install the code and we’ll begin verifying any input with the type email.

<script>
  (function (w, d, ns) {
    w['EmailableObject'] = ns;
    w[ns] = w[ns] || function () { (w[ns].q = w[ns].q || []).push(arguments) },
    s = d.createElement('script'), fs = d.getElementsByTagName('script')[0];
    s.async = 1; s.src = 'https://js.emailable.com/v2/';
    fs.parentNode.insertBefore(s, fs)
  })(window, document, 'emailable');

  emailable('apiKey', 'YOUR_API_KEY'); // replace YOUR_API_KEY with your actual API key
</script>

Configuration options

Using our configuration options, you can customize the email attributes you’d like to allow, which inputs we’ll monitor, and more.

Set an option by calling emailable() with the option name and value:

Option	Type	Default	Description
`allow`	Object	See Allow	Types of emails that are allowed.
`verificationTimeout`	Integer	`5`	Maximum time, in seconds, to wait for the verification to respond. Some mail servers are slow and we don’t want to hold the user up for too long.
`verifyAfterDelay`	Integer	`1000`	How long, in milliseconds, to wait after a user stops typing to verify the email.
`formValidation`	Boolean	`true`	Enable form validation messages. This will also remove the `novalidate` attribute from forms with one.
`inputSelector`	String	`'input[type="email"]'`	The selector for the inputs we will monitor.
`ignoredForms`	Array	`[]`	Array of form names to ignore.
`ignoredInputs`	Array	`[]`	Array of input names to ignore.
`blockOnRateLimit`	Boolean	`false`	Users who enter 10+ emails will be rate-limited by our servers. When set to `true` the user will get the `rateLimited` message.
`statusAppendTo`	String or Element	`'body'`	The parent element to append the status element to. Can be an element or CSS identifier.
`style`	Object	See Style	Style overrides for the widget.
`messages`	Object	See Messages	Message overrides shown to the user.

Allow

Attribute	Type	Default	Description
`states`	Array	`['deliverable', 'risky', 'unknown']`	Verification states that are allowed.
`free`	Boolean	`true`	Allow free email addresses.
`role`	Boolean	`true`	Allow role or group email addresses.
`disposable`	Boolean	`false`	Allow disposable email addresses.

Style

Attribute	Type	Default	Description
`loadingIconColor`	String	`'rgba(0, 0, 0, 0.3)'`	Color of the loading icon.

Messages

Attribute	Default
`verifying`	`"Please wait a moment while we verify your email address."`
`invalid`	`"It looks like you've entered an invalid email address."`
`role`	`"It looks like you've entered a role or group email address."`
`free`	`"It looks like you've entered a free email address."`
`disposable`	`"It looks like you've entered a disposable email."`
`didYouMean`	`"It looks like you've entered an invalid email address. Did you mean [EMAIL]?"`
`rateLimited`	`"It looks like you've attempted to enter too many emails."`

<script>
  // types of emails that are allowed
  emailable('allow', {
    states: ['deliverable', 'risky', 'unknown'],
    free: true,
    role: true,
    disposable: false
  });

  // maximum time to wait for the verification to respond. some mail servers
  // are slow and we don't want to hold the user up for too long.
  emailable('verificationTimeout', 5);

  // how long to wait after a user stops typing to verify the email
  emailable('verifyAfterDelay', 1000);

  // enable form validation messages
  // this will also remove the novalidate attribute from forms with one
  emailable('formValidation', true);

  // this is the selector for the inputs we will monitor
  emailable('inputSelector', 'input[type=email]');

  // array of form names to ignore
  emailable('ignoredForms', []);

  // array of input names to ignore
  emailable('ignoredInputs', []);

  // users who enter 10+ emails will be rate-limited by our servers.
  // when set to true the user will get the rateLimited message.
  emailable('blockOnRateLimit', false);

  // the parent element to append the status element to. can be an element or
  // CSS identifier.
  emailable('statusAppendTo', 'body');

  // styles
  emailable('style', {
    loadingIconColor: 'rgba(0, 0, 0, 0.3)'
  });

  // messages
  emailable('messages', {
    verifying: "Please wait a moment while we verify your email address.",
    invalid: "It looks like you've entered an invalid email address.",
    role: "It looks like you've entered a role or group email address.",
    free: "It looks like you've entered a free email address.",
    disposable: "It looks like you've entered a disposable email.",
    didYouMean: "It looks like you've entered an invalid email address. Did you mean [EMAIL]?",
    rateLimited: "It looks like you've attempted to enter too many emails."
  });
</script>

Event listeners

Our event listeners will give you the ability to take specific actions once the verification has completed.

Verified event

Attribute	Type	Description
`accepted`	Boolean	Whether the email passed your `allow` configuration.
`message`	String	Message shown to the user when the email is not accepted.
`verificationData`	Object	Object containing the raw verification response. Includes `body` (JSON string of the verification response) and `status` (HTTP status code).

Error event

Attribute	Type	Description
`status`	Integer	HTTP status code returned by the verification request.
`message`	String	Description of the error.

Verified event

Verified event response example

{
  accepted: false,
  message: "It looks like you've entered an invalid email address.",
  verificationData: {
    body: "{\"accept_all\":false,\"did_you_mean\":null,\"disposable\":false,\"domain\":\"gmail.com\",...}", // JSON string
    status: 200
  }
}

Error event

<script>
  document
    .querySelector('input[type="email"]')
    .addEventListener('error', (event) => {
      console.error(event.detail);
      // { status: 429, message: 'Rate limit reached' }
    });
</script>

Widget

Install the embed code

Configuration options

Allow

Style

Messages

Event listeners

Verified event

Error event

Was this page helpful?

What went wrong?

Recently viewed

General help & guides

Need further help?

On this page

Install the embed code

Configuration options

Allow

Style

Messages

Event listeners

Verified event

Error event

Was this page helpful?

What went wrong?

Recently viewed