Email validation widget for forms

The widget validates an address directly in a form, while it is being typed, with no integration code to write. It is added with a single tag, which contains no API key. It applies exactly the same checks as the API and suggests a correction when the domain typed looks like a known domain.

One tag to paste

Installation comes down to one tag, pasted before the closing of the page. The script finds the email address fields of the form on its own, reads its configuration from the server, and sets itself up. No integration code to write, no dependency to install, no secret in the page.

  1. Create the widget

    From the customer area, declaring the domain of the site that will host it.

  2. Paste the tag

    A single line, before the closing of the page. It carries only the widget identifier.

  3. Set the behaviour

    Messages, appearance, anti-bot challenge and SMTP verification are set without touching the page.

Code to paste
<script async src="https://api.yeswecheck.fr/widget/ywc-email-widget.js" data-ywc-widget="YOUR_WIDGET_ID"></script>
The script reads its configuration from the server, which checks the domain of the page and the scope of the key before replying. The page carries only the widget identifier, never a key.

The code to paste contains no API key. It carries the widget identifier and nothing else: the key is resolved on the server side, it never travels through the public page.

By default, the widget attaches to fields that declare input[type="email"]. A different selector can be configured when the form does not use this type of field.

What the person typing sees

The widget shows the state of the field while it is being typed and suggests a correction when the domain looks like a known domain. The messages are configurable, in English as in any other language. Nothing is blocked by force: the widget informs, and the form decides whether or not to refuse.

Typo correction

A misspelt domain is recognised and the correct spelling is suggested. It is the most immediate gain on a sign up form, and it costs no credit.

Configurable messages

Each state carries its own message, which can be edited: valid, risky, invalid or unknown address, or verification in progress.

Appearance

The display of the field state, of the status icon and of the check hints can each be switched on or off independently.

Read the definition of statuses and score

What protects a widget

A widget lives in a public page: its identifier is visible to everyone. What protects it is therefore not the secrecy of that identifier, but what the server agrees to do with it. Two safeguards apply together: the scope of the key, and the list of domains authorised to use it.

A key linked to a widget switches to the ‘widget’ scope and must declare at least one authorised domain. A request sent from any other domain is refused, and the ‘widget’ scope forbids this key any other use of the API.

The 2 public endpoints used by the widget.
CallRole
GET /v2/widget/configPublic configuration of a widget, read by the embedded script.
POST /v2/widget/validateValidation called by the widget from a customer site.

The detailed configuration of a widget, custom messages and thresholds included, is never exposed in the public page: the script reads it from the server.

Usage caps and anti-bot challenge

A public form attracts bots. Two complementary mechanisms respond: counters that cap usage per IP address, per device and per key, and a proof of work challenge that runs in the browser before validation. Enumeration detection also runs, with no configuration.

Protection against enumeration is active on the API, the widget, batch processing, with no configuration on the customer side.

Understand protection against bots

What a widget uses

The billing rules of the widget are those of the API, with no exception. A widget configured without SMTP verification never uses a credit, whatever the traffic on the form. With SMTP verification, one credit is charged per address for which the receiving server allowed a verdict.

A credit is charged if and only if SMTP verification was requested and the final status is not "unknown".

The 19 free checks apply to every entry, with no quota: typo correction, disposable address detection and the domain check cost nothing.

Frequently asked questions

Does the code to paste contain an API key?
The code to paste contains no API key. It carries the widget identifier and nothing else: the key is resolved on the server side, it never travels through the public page.
What happens if someone copies my widget identifier?
A key linked to a widget switches to the ‘widget’ scope and must declare at least one authorised domain. A request sent from any other domain is refused, and the ‘widget’ scope forbids this key any other use of the API.
Does the widget use credits on every keystroke?
A credit is charged if and only if SMTP verification was requested and the final status is not unknown. A widget configured without SMTP verification never uses a credit, whatever the number of entries.
Does the widget protect against bots?
Counters per IP address, per device and per key cap the use of the widget. Beyond the threshold, SMTP verification is switched off or the request refused, depending on the configuration. A proof of work challenge can also be required before every validation.

Going further

To drive each check from your own code, the API returns the same result with the full detail of every verification. And to clean a list of addresses already collected, batch processing applies exactly the same rules.