JavaScript Widget

The TrueMail JavaScript widget enables you to add our real-time email validation services to your online forms quickly and easily.

Getting Started

To get started, create a new JavaScript widget from the apps page here. Then give it a name. Moreover, you can add the authorized domains from which the form can be used.

Installing the Widget

When the app is created, you’ll see your public API key and an HTML snippet. In order to install the widget you simply copy the HTML snippet and paste it before the closing </body> tag on your website, as seen below:

...
<script type='text/javascript'>
  _TMSettings = {
  apiKey: 'public_000000...'
 };
</script>
<script type='text/javascript' src='https://cdn.truemail.io/tm-widget.js'></script>
</body>
</html>

When the snippet is added to your website, you can see that all the input elements with email type are detected by the widget. These following fields will be recognized by the widget:

<input type="email" name="email_field" />
<input type="text" name="email" />
<input id="your_id_from_TMSettings" />
<input name="your_name_from_TMSettings" />
<button id="your_prevent_submitting_element_id"> Submit </button>

Now when the fields are set up, you can see the TrueMail JavaScript widget doing its job when you start typing in these fields.

Compatibility with certain platforms

Some third-party services may need additional setup for the widget to work. If there's a certain platform you would like us to test please let us know.

Widget Settings

There are two kinds of Settings for the widget: security settings and behavior settings. Security settings can be accessed from your dashboard where you initially setup the widget. Behavior settings are managed from the HTML snippet placed on your site.

Security Settings

Authorized Domains

Authorized domains protect your public API key from being used by unauthorized sources. Only the requests come from the authorized domain will be accepted.

If you don’t select any authorized domains or IP addresses, all requests made with your key will be processed no matter which is location.

Google reCAPTCHA v3

Use Google reCAPTCHA v3 for more security. It protects you against spam and other types of automated abuse. Also reCAPTCHA v3 works in the background so users don’t need to read blurred text in an image or even tick the “I’m not a robot” checkbox.

Behavior Settings

When you install the widget with the HTML snippet, you may notice a line which reads _TMSettings. Here you specify the settings for the widget on your website. To make the widget work you only need the apiKey, so basically, the snippet contains just the apiKey. If more control is needed, you can set up the following settings in this snippet:

const _TMSettings = {
   /**
     * User's public api key; This is available from the apps page.
     */
   apiKey: undefined,
   /**
     * Your input id (if it is custom)
     */
   inputId: 'your_input_id',
   /**
     * Your input name (if it is custom)
     */
   inputName: 'your_input_name',
   /**
     * Request timeout in seconds
     * After this threshold is reached the result is assumed unknown. This is likely
     * a trouble host that will take extra time to resolve.
     */
   timeout: 30000,
   preventSubmittingElementId: null
   /**
     * Disable element click by id. The rejected status codes. Other status codes will be accepted. 
     * Default rejected codes are disposable(5), invalid(6) 
     */
   verificationMessageTime: 15000,
   /**
     * Emails with rejected codes status are allowed to submit
     */
   preventSubmittingForm: false,
   /**
     * The rejected status codes. Other status codes will be accepted.
     * Default rejected codes are disposable(5), invalid(6) 
     */
   rejectedCodes: [5, 6],
   /**
     * Message displayed in feedback div while waiting for an response
     */
   loadingMessage: "Loading...",
    /**
     * Message displayed in feedback div when email is rejected
     */
   rejectedMessage: "Invalid email",
       /**
     * Allows the blocking of freemail email addresses (e.g. Gmail, Hotmail, Yahoo...)
     */
   acceptFreeEmails: false
   /**
     * Message displayed in feedback div when a freemail is entered and rejected code contains disposable(5) 
     */
   freemailRejectMessage: "Enter a business email",
   /**
     * Message displayed in feedback div when email is acceptable
     */
   acceptedMessage: 'Valid Email',
   showSuggestedCorrection: true,
   syntaxErrorMessage: 'Syntax Error',
   errorMessageDelay: 600
}