Email Validation Plugin
Validate email addresses in Flatfile data imports with format checking, required field validation, and disposable domain blocking
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:
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.
Configuration with Custom Messages
This example validates two email fields, provides custom error messages, and applies the validation only to the ‘contacts’ sheet.
Advanced Usage with Disposable Domain Blocking
This example demonstrates using a custom list of disposable domains to block.
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 theerrorMessages
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 therecord.addError()
method. - This approach allows users to see all data issues inline within the Flatfile interface and correct them before finalizing the import.