website logo
⌘K
Email Verification API
API Overview
Authentication
Rate Limits
Response Headers
Response Codes
Reference
Code Examples
Data Privacy API
Data Privacy API Overview
Reference
Code Examples
Webhooks
Webhooks Overview
Retries and Errors
Managing Webhooks
Verifying Webhooks
Event Triggers
JavaScript Widget
JavaScript Widget Overview
Installing the Widget
Widget Configuration Options
Docs powered by
Archbee
JavaScript Widget

Widget Configuration Options

18min

The mailfloss widget allows you to verify emails in real-time, fast and easy.

Default values in settings

The widget comes with default settings, which you can choose to keep or customize. Below is a list of the default settings and their descriptions.

If you're happy with these defaults, you're all set to start using the widget.

Timing

  • rateLimitUserAttempts: This sets the maximum number of verification attempts that a user can perform within a specific time period. Default is: 10.
  • rateLimitStartsWithin: If the user exceeds rateLimitUserAttempts within rateLimitStartsWithin, the user will be rate-limited. The value of rateLimitStartsWithin is set in milliseconds. Default is: 10000.
  • rateLimitWaitTime: The time period a user must wait before verification will begin again. Once this period is over, the user can start verifying again, and the process repeats. The value of rateLimitWaitTime is set in milliseconds. Default is: 10000.
  • maxVerificationTime: sets the maximum time allowed for a verification process to complete. If the time exceeds this limit, the process will be aborted. The value of maxVerificationTime is set in milliseconds. Default is: 10000.
  • doneTypingTime: sets the time the widget waits after a user stops typing before starting the verification process. This delay allows the user to complete their input before the verification process begins. The value of doneTypingTime is set in milliseconds. Default is: 1500.
  • overlayDisplayTime: sets the time duration in milliseconds for which the dropdown overlay remains visible after it appears. Once the overlayDisplayTime has elapsed, the dropdown overlay disappears automatically. Default is: 2500.



Messages

  • validMessage: This message is displayed in the dropdown when the email entered by the user is valid. Default is: "Valid email".
  • invalidMessage: This message is displayed in the dropdown when the email entered by the user is invalid. Default is: "Invalid email".
  • verifyingMessage: This message is displayed in the dropdown when the widget is verifying the email entered by the user. Default is: "Verifying..."
  • suggestionMessage: This message is displayed in the dropdown when a suggestion is made to the user due to a potential misspelled domain. Default is: "Maybe you meant:".
  • regexFailMessage: This message is displayed when the user types something that is not a valid email address according to the specified regular expression. Default is: "Please enter a valid email".



Allowed Categories

  • statusAllowedValues: This is an array that lets you specify the allowed values for the status of the email. The possible values are valid, unknown, and risky. You can enter any combination of these values that you want to be allowed. Default is: ['passed', 'unknown', 'risky'].
  • reasonAllowedValues: This is an array object that lets you specify the allowed values for the reason of the email status. The possible values are valid, accept_all, and unverified. You can enter any combination of these values that you want to be allowed. Default is: ['valid', 'accept_all', 'unverified'].
  • blockRoleAddresses: This is a boolean that, when set to true, blocks all role-based email addresses. Default is: false.
  • blockFreeAddresses: This is a boolean that, when set to true, blocks all free email addresses such as Gmail, Yahoo, Hotmail, and AOL. Default is: false.
  • blockDisposableAddresses: This is a boolean that, when set to true, blocks all disposable email addresses. Default is: true.

CSS Settings

  • verifyingSpinnerColor: Sets the color of the loading spinner. Default is: #3498db.
  • boxshadowValid: Sets the box shadow for a valid email response. Default is: 0px 4px 5px 1px rgba(21, 157, 3, 0.2).
  • boxshadowInvalid: Sets the box shadow for an invalid email response. Default is: 0px 4px 5px 1px rgba(157, 3, 3, 0.2).
  • boxshadowDefault: Sets the box shadow for a default response. Default is: 0px 4px 5px 1px rgba(0, 0, 0, 0.1).
  • borderRadiusResponse: Sets the border radius for the response message box. Default is: 5px.
  • borderInputDefault: Sets the border for the input when no response has been given. Default is: 1px solid #e1e0e0.
  • borderInputValid: Sets the border for the input when a valid email response has been given. Default is: 1px solid green.
  • borderInputInvalid: Sets the border for the input when an invalid email response has been given. Default is: 1px solid red.
  • colorInvalid: Sets the color for the response message when the email is invalid. Default is: red.
  • colorValid: Sets the color for the response message when the email is valid. Default is: green.



Others

  • autoDetect: This is a boolean object that, when set to true, enables the widget to automatically detect the input field for email verification. If set to false, the widget will not automatically detect the input field and an inputSelector should be specified, instead. Default is: true.
  • inputSelector: If autoDetect is set to false, this object should be set with a string value containing the class or ID of the input field that the user wants to use for email verification, written like this: "#inputIdName"/ ".inputClassName". The widget will use this selector to target and verify the email entered in the specified input field. If left undefined and autoDetect is disabled, the widget will not work. Default is: "".
  • offerSuggestion: This is a boolean object that, when set to true, enables the widget to offer suggestions in case the email entered by the user is potentially a typo. If set to false, the widget will not ask the user if they meant to type the suggested email. Default is: true.
  • poweredBy: This is a boolean object that, when set to true, displays the mailfloss logo in the widget. This option may not be available depending on your subscription plan. Default is: true.
  • showDropdownBox: This is a boolean object that, when set to true, displays the dropdown box in the widget. If set to false, the widget will not display the dropdown box. Default is: true.
  • borderHighlight: This is a boolean object that, when set to true, highlights the border of the input field with a color that indicates whether the email entered is valid or invalid. By default, the border is green for valid emails and red for invalid emails. Default is: true.
  • ignoreInputs: is an array where you can enter the name, class or id of the inputs that you want the widget to ignore. When the widget is scanning the page for inputs to verify, it will skip any input whose name, id, or class matches the names specified in this array. This can be useful if you have inputs that you don't want to be verified by the widget and autoDetect is disabled. It must be in an array. e.g: ['emailClass']. Default is: undefined.
  • publicKey: This is a string where you must put your API key so that the widget can work. This is a required parameter, and without it, the widget will not function.
  • debugMode: This is a boolean that, when set to true, activates the debug mode of the widget. This mode is used for debugging purposes and provides additional information about the widget's behavior. Default is: false.
  • afterVerification: This setting works as a callback. In case you want to use the API response in one of your functions, you can assign the name of your function as the value of afterVer. Every time you make a verification, your function will be returned with the API response as string. To use it as an object you can use JSON.parse(response). You can see an example of this at the bottom of this page. Widget Setup Examples / Example 4. Note: If you want to console.log the response, remember to enable the debugMode on the settings.

Customizing your widget

In order to customize your widget, you need to pass the custom settings into the window.mf_settings object with the modified value. Initially, only the publicKey is set in this object.

Inside this object, there will be every setting that you want to change.

JS
|
// It will look like this:

window.mf_settings = {
  // name of the setting : value,
  "publicKey": "<your public key>",
  "validMessage": "this email is valid"
}


Here's a list of things you can change and how:

Text
|
The values below are the default values, feel free to changed them to your preference.

TIMING
  * rateLimitUserAttempts: 10, 
  * rateLimitStartsWithin: 10000,
  * rateLimitWaitTime: 10000,  
  * maxVerificationTime: 10000,
  * doneTypingTime: 1500,
  * overlayDisplayTime: 2500,

MESSAGES 
  * validMessage: 'Valid email',
  * invalidMessage: 'Invalid email',
  * verifyingMessage: 'Verifying...', 
  * suggestionMessage: 'Maybe you meant: ',  
  * regexFailMessage: 'Please enter a valid email',
  
ALLOWED CATEGORIES
  * statusAllowedValues: ['passed', 'unknown', 'risky'],
  * reasonAllowedValues: ['valid', 'accept_all', 'unverified'], 
  * blockRoleAddresses: false,
  * blockFreeAddresses : false,
  * blockDisposableAddresses: true,
    
CSS
  * verifyingSpinnerColor: '#3498db',
  * boxshadowValid: '0px 4px 5px 1px rgba(21, 157, 3, 0.2)',
  * boxshadowInvalid: '0px 4px 5px 1px rgba(157, 3, 3, 0.2)', 
  * boxshadowDefault: '0px 4px 5px 1px rgba(0, 0, 0, 0.1)', 
  * borderRadiusResponse: '5px', 
  * borderInputDefault: '1px solid #e1e0e0', 
  * borderInputValid: '1px solid green',
  * borderInputInvalid: '1px solid red',
  * colorInvalid: 'red',
  * colorValid: 'green'

OTHERS
  * autoDetect: true,
  * inputSelector: "",
  * poweredBy: true,  
  * showDropdownBox: true,
  * borderHighlight: true,
  * ignoreInputs: [],     
  * debugMode : true,
  * publicKey : ""




Widget Setup Examples

Here are some common scenarios to give you some ideas on how to setup your widget.

Example 1: Basic setup

JS
|
<script>
    let mailfloss = window.mailfloss = window.mailfloss || [],
    mf_settings = {
        publicKey : "<your public key>",      
      };
      mailfloss.push([mf_settings]),
      (function() {
          first_script = document.getElementsByTagName('script')[0], script =   document.createElement('script');
          script.type = "text/javascript", script.async = !0,
          script.src = "https://cdn.mailfloss.io/v1/index.min.js", 
          first_script.parentNode.insertBefore(script, first_script)
      })();
  </script>


Example 2: Rate limit setup

The user will have 5 attempts per day. In this case, the widget setup looks like:

JS
|
<script>
    let mailfloss = window.mailfloss = window.mailfloss || [],
    mf_settings = {
        rateLimitUserAttempts: 5, 
        rateLimitStartsWithin: 86400000, //a day in miliseconds
        rateLimitWaitTime: 86400000,
        publicKey : "<your public key>"       
      };
      mailfloss.push([mf_settings]),
      (function() {
          first_script = document.getElementsByTagName('script')[0], script = document.createElement('script');
          script.type = "text/javascript", script.async = !0,
          script.src = "https://cdn.mailfloss.io/v1/index.min.js", 
          first_script.parentNode.insertBefore(script, first_script)
      })();
  </script>


We want to limit the user to only 5 attempts (rateLimitUserAttempts), per day (rateLimitStartsWithin will be 86400000 miliseconds = a day). And the time we want the user to be rate limited will also be a day (rateLimitWaitTime). The user will need to come back tomorrow once 5 attempts have been used for the day.



A more common setup to keep bots and abusers away might look like this:

JS
|
<script>
    let mailfloss = window.mailfloss = window.mailfloss || [],
    mf_settings = {
        rateLimitUserAttempts: 5, 
        rateLimitStartsWithin: 10000, 
        rateLimitWaitTime: 30000,
        publicKey : "<your public key>"
      };
      mailfloss.push([mf_settings]),
      (function() {
          first_script = document.getElementsByTagName('script')[0], script = document.createElement('script');
          script.type = "text/javascript", script.async = !0,
          script.src = "https://cdn.mailfloss.io/v1/index.min.js", 
          first_script.parentNode.insertBefore(script, first_script)
      })();
  </script>


We want to limit the user to 5 attempts (rateLimitUserAttempts) every 10 seconds (rateLimitStartsWithin). If the user reaches the 5 attempts within 10 seconds, then the rate limit will be activated and the user will need to wait for 30 seconds (rateLimitWaitTime) before they can try again.

Example 3:  How to setup the widget to match your brand colors

JS
|
<script>
    let mailfloss = window.mailfloss = window.mailfloss || [],
    mf_settings = {
        boxshadowValid: '0px 4px 5px 1px rgba(245, 40, 145, 0.8)', 
		borderInputValid: '5px solid green', 
		colorValid: 'rgba(236, 187, 30, 0.8)', 
        boxshadowInvalid: '0px 4px 5px 1px rgba(0, 187, 231, 0.8)', 
        borderInputInvalid: '5px solid red', 
        colorInvalid: 'rgba(236, 187, 231, 0.8)', 
        colorValid: 'rgba(236, 187, 30, 0.8)',
        publicKey : "<your public key>"  
      };
      mailfloss.push([mf_settings]),
      (function() {
          first_script = document.getElementsByTagName('script')[0], script = document.createElement('script');
          script.type = "text/javascript", script.async = !0,
         script.src = "https://cdn.mailfloss.io/v1/index.min.js", 
          first_script.parentNode.insertBefore(script, first_script)
      })();
  </script>


Example 4:  How to use the afterVerification (callback) setting

JS
|
<script>
  function callback(response) {
    const responseObject = JSON.parse(response);
    console.log(responseObject);
    //code where you are using the response here
  }
</script>
<script>
    let mailfloss = window.mailfloss = window.mailfloss || [],
    mf_settings = {
        debugMode: true, // to print console.log messages in the callback
        afterVerification: callback, //name of your callback function    
        publicKey : "<your public key>"
      };
      mailfloss.push([mf_settings]),
      (function() {
          first_script = document.getElementsByTagName('script')[0], script = document.createElement('script');
          script.type = "text/javascript", script.async = !0,
         script.src = "https://cdn.mailfloss.io/v1/index.min.js", 
          first_script.parentNode.insertBefore(script, first_script)
      })();
  </script>




Updated 08 Sep 2023
Did this page help you?
PREVIOUS
Installing the Widget
Docs powered by
Archbee
TABLE OF CONTENTS
Default values in settings
Timing
Messages
Allowed Categories
CSS Settings
Others
Customizing your widget
Widget Setup Examples
Example 1: Basic setup
Example 2: Rate limit setup
Example 3:  How to setup the widget to match your brand colors
Example 4:  How to use the afterVerification (callback) setting
Docs powered by
Archbee