# Widget

The easiest way to add email verification to your website.

## 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](https://app.emailable.com/api?utm_source=api-docs&utm_medium=web&utm_campaign=widget)
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.

```html
<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](#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)    | Style overrides for the widget.
`messages`            | Object  | See [Messages](#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."`

```html
<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

```html
<script>
  document
    .querySelector('input[type="email"]')
    .addEventListener('verified', (event) => {
      // ...
    });
</script>
```

> Verified event response example

```javascript
{
  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

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