The Email Validation plugin for Flatfile provides a convenient way to validate email addresses in your data. It integrates into the Flatfile Listener as a record hook, automatically checking specified fields on each record. The plugin’s core functionalities include validating the email format, checking for required values, and blocking emails from disposable or temporary domains. It is highly configurable, allowing you to specify which fields and sheets to target, provide a custom list of disposable domains, and customize the error messages shown to the user for different validation failures. This is useful for ensuring data quality for contact lists, user sign-ups, and any dataset containing email addresses.

​
Installation

Install the plugin using npm: 
npm install @flatfile/plugin-validate-email

​
Configuration & Parameters

The plugin is configured with a single object passed to the validateEmail function.

​
sheetSlug

  • Type: string
  • Required: No
  • Default: '**'
  • Description: The slug of the sheet to apply the validation to. The default value '**' means the plugin will run on all sheets in the workspace.

​
emailFields

  • Type: string[]
  • Required: Yes
  • Description: An array of strings, where each string is the field key (or column name) that should be validated as an email.

​
disposableDomains

  • Type: string[]
  • Required: No
  • Default: [] (empty array)
  • Description: A custom list of email domains that should be considered disposable and rejected. The comparison is case-insensitive.

​
errorMessages

  • Type: object
  • Required: No
  • Description: An object to override the default error messages. The available keys are:
    • required: Message for a missing email value. Default: “Email is required”
    • invalid: Message for an improperly formatted email. Default: “Invalid email format”
    • disposable: Message for an email from a blocked domain. Default: “Disposable email addresses are not allowed”
    • domain: Not currently used by the plugin

​
Usage Examples

​
Basic Usage

This example validates the ‘email’ field in all sheets with default error messages. 
import { FlatfileListener } from '@flatfile/listener';
import { validateEmail } from '@flatfile/plugin-validate-email';

export default function (listener) {
  listener.use(validateEmail({
    emailFields: ['email']
  }));
}

​
Configuration with Custom Messages

This example validates two email fields, provides custom error messages, and applies the validation only to the ‘contacts’ sheet. 
import { FlatfileListener } from '@flatfile/listener';
import { validateEmail } from '@flatfile/plugin-validate-email';

export default function (listener) {
  listener.use(validateEmail({
    sheetSlug: 'contacts',
    emailFields: ['primary_email', 'secondary_email'],
    errorMessages: {
      required: 'Please enter an email.',
      invalid: 'The email you entered is not valid.',
      disposable: 'Temporary email addresses are not permitted.'
    }
  }));
}

​
Advanced Usage with Disposable Domain Blocking

This example demonstrates using a custom list of disposable domains to block. 
import { FlatfileListener } from '@flatfile/listener';
import { validateEmail } from '@flatfile/plugin-validate-email';

export default function (listener) {
  const blockedDomains = ['mailinator.com', 'temp-mail.org', '10minutemail.com'];

  listener.use(validateEmail({
    emailFields: ['email'],
    disposableDomains: blockedDomains,
    errorMessages: {
      disposable: 'This email provider is not allowed. Please use a permanent email address.'
    }
  }));
}

​
API Reference

​
validateEmail(config)

A factory function that creates a Flatfile record hook. The hook validates specified fields on a record to ensure they are properly formatted and non-disposable email addresses. Parameters:
  • config (object): A configuration object with the following properties:
    • sheetSlug (string, optional): The slug of the sheet to target. Defaults to '**' to target all sheets.
    • emailFields (string[], required): An array of field keys to validate.
    • disposableDomains (string[], optional): A list of domains to reject.
    • errorMessages (object, optional): An object for custom error messages.
Return Value: Returns a FlatfileListener instance configured with the record hook, which can be passed to listener.use().

​
Troubleshooting

  • Validation not triggering: Verify that the sheetSlug in the configuration correctly matches the slug of your target Sheet.
  • Fields not being validated: Ensure the strings in the emailFields array exactly match the field keys in your Sheet configuration.
  • Plugin not working: Confirm that the plugin is correctly registered with a Flatfile listener using listener.use().

​
Notes

​
Default Behavior

By default, the plugin applies to all sheets. If errorMessages are not provided, it uses its own internal messages for required, invalid, and disposable email errors. If disposableDomains is not provided, it will not perform any disposable domain checks, only format and presence validation.

​
Special Considerations

  • This plugin is a “Record Hook” type, meaning it runs on every record as it is processed.
  • The validation logic uses a regular expression for format checking. While robust, it may not cover 100% of all edge-case email address formats defined in RFCs.
  • The domain key within the errorMessages configuration object is defined in the type interface but is not currently used in the validation logic.
  • The domain check for disposable emails is case-insensitive.

​
Error Handling

  • The plugin does not throw errors or stop the import process.
  • Validation failures are handled by adding an error message to the specific field on the FlatfileRecord using the record.addError() method.
  • This approach allows users to see all data issues inline within the Flatfile interface and correct them before finalizing the import.