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.
-
Create the widget
From the customer area, declaring the domain of the site that will host it.
-
Paste the tag
A single line, before the closing of the page. It carries only the widget identifier.
-
Set the behaviour
Messages, appearance, anti-bot challenge and SMTP verification are set without touching the page.
<script async src="https://api.yeswecheck.fr/widget/ywc-email-widget.js" data-ywc-widget="YOUR_WIDGET_ID"></script> 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.
- [email protected]
validAddress verified - [email protected]
riskyThis address looks risky - [email protected]
invalidThis address cannot receive messages - [email protected]
unknownThis address could not be confirmed
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.
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.
| Call | Role |
|---|---|
| GET /v2/widget/config | Public configuration of a widget, read by the embedded script. |
| POST /v2/widget/validate | Validation 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.
- Caps. 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.
- Proof of work challenge. A proof of work challenge can be required before every validation, or only when SMTP verification is requested. It runs in the browser, with no image to decipher and no third party service.
- Enumeration detection. Detection is silent: no block is returned to the caller, so the attacker never learns they have been spotted. The organisation receives an email alert, with concrete examples and one-click blocking. The block therefore falls when the organisation decides, not at a moment the attacker could notice.
Protection against enumeration is active on the API, the widget, batch processing, with no configuration on the customer side.
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.