Skip to main content

​
Overview

The isEmail() function validates email addresses according to standard email format rules with extensive customization options. It can check for plus addressing, require top-level domains, block specific domains, and provide detailed validation feedback.

​
Common Use Cases

  • User registration and sign-up forms
  • Email input validation in authentication flows
  • Blocking disposable or temporary email domains
  • Extracting and validating email components

​
Function Signature

isEmail(email, options)

​
Parameters

​
email
string
required
The email address to validate.
​
options
object
Configuration options for email validation.
​
options.allowPlusAddressing
boolean
default:"true"
Whether to allow plus addressing (e.g., [email protected]). Useful for email filtering and organization.
​
options.requireTLD
boolean
default:"true"
Whether a top-level domain is required (e.g., .com, .org, .pl). Set to false to allow local email addresses.
​
options.blockedDomains
string[]
default:"[]"
List of blocked email domains. Useful for preventing disposable email services.
​
options.details
boolean
default:"false"
Whether to return detailed validation information instead of a boolean.

​
Return Value

​
result
boolean | object
When details is false: Returns true if valid, false otherwise.When details is true: Returns an object with the following properties:
​
valid
boolean
Whether the email address is valid.
​
errors
string[] | null
Array of validation error messages, or null if valid.
​
email
string
The trimmed email address that was validated.
​
localPart
string
The local part of the email (before the @ symbol).
​
domain
string
The domain part of the email (after the @ symbol).

​
Examples

​
Basic Email Validation

import { isEmail } from 'validauth';

// Valid emails
isEmail('[email protected]');
// Returns: true

isEmail('[email protected]');
// Returns: true

// Invalid emails
isEmail('invalid.email');
// Returns: false

isEmail('@example.com');
// Returns: false

isEmail('user@');
// Returns: false

​
Blocking Domains

import { isEmail } from 'validauth';

// Block disposable email services
const result = isEmail('[email protected]', {
  blockedDomains: ['tempmail.com', '10minutemail.com', 'guerrillamail.com']
});
// Returns: false

// Allow other domains
const result2 = isEmail('[email protected]', {
  blockedDomains: ['tempmail.com', '10minutemail.com']
});
// Returns: true

​
Detailed Validation

import { isEmail } from 'validauth';

// Get detailed validation results
const result = isEmail('[email protected]', {
  details: true
});

console.log(result);
/* Returns:
{
  valid: true,
  errors: null,
  email: '[email protected]',
  localPart: 'john.doe+work',
  domain: 'company.com'
}
*/

// Invalid email with details
const result2 = isEmail('invalid..email@domain', {
  requireTLD: true,
  details: true
});

console.log(result2);
/* Returns:
{
  valid: false,
  errors: [
    'Email local part cannot contain consecutive dots',
    'Domain must contain a top-level domain (e.g., .com, .org)'
  ],
  email: 'invalid..email@domain',
  localPart: 'invalid..email',
  domain: 'domain'
}
*/

​
Registration Form Example

import { isEmail } from 'validauth';

function validateRegistrationEmail(email) {
  const result = isEmail(email, {
    allowPlusAddressing: true,
    requireTLD: true,
    blockedDomains: [
      'tempmail.com',
      '10minutemail.com',
      'guerrillamail.com',
      'mailinator.com'
    ],
    details: true
  });

  if (!result.valid) {
    return {
      success: false,
      message: 'Invalid email address',
      errors: result.errors
    };
  }

  return {
    success: true,
    email: result.email,
    domain: result.domain
  };
}

// Usage
const validation = validateRegistrationEmail('[email protected]');
if (validation.success) {
  console.log('Email is valid:', validation.email);
} else {
  console.error('Validation errors:', validation.errors);
}

​
Validation Rules

The email validator checks the following:
Email Format Requirements
  • Maximum total length: 254 characters
  • Must contain exactly one @ symbol
  • Local part (before @): 1-64 characters
  • Domain (after @): 1-253 characters
Local Part Rules:
  • Cannot start or end with a dot (.)
  • Cannot contain consecutive dots (..)
  • Can contain: letters, numbers, and special characters like .!#$%&'*+/=?^_-
  • Plus addressing (+) is validated based on allowPlusAddressing option
Domain Rules:
  • Cannot start or end with a dot (.) or hyphen (-)
  • Cannot contain consecutive dots (..)
  • Must contain a top-level domain if requireTLD is true
  • Can only contain: letters, numbers, dots, and hyphens
  • Case-insensitive matching for blocked domains

​
Common Patterns

​
Corporate Email Validation

import { isEmail } from 'validauth';

function isValidCorporateEmail(email) {
  const result = isEmail(email, { details: true });
  
  if (!result.valid) {
    return false;
  }
  
  // Only allow specific corporate domains
  const allowedDomains = ['company.com', 'company.co.uk'];
  return allowedDomains.includes(result.domain.toLowerCase());
}

​
Email Extraction and Validation

import { isEmail } from 'validauth';

function extractAndValidateEmails(text) {
  // Simple email extraction regex
  const emailPattern = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
  const potentialEmails = text.match(emailPattern) || [];
  
  return potentialEmails
    .map(email => {
      const result = isEmail(email, { details: true });
      return result.valid ? result : null;
    })
    .filter(Boolean);
}

const text = 'Contact us at [email protected] or [email protected]';
const validEmails = extractAndValidateEmails(text);
console.log(validEmails);
// Returns array of validated email objects

​
Error Handling

Always handle validation errors appropriately in your application. The details option provides specific error messages for better user feedback.
import { isEmail } from 'validauth';

function handleEmailValidation(email) {
  try {
    const result = isEmail(email, { details: true });
    
    if (!result.valid) {
      // Log or display specific errors
      console.error('Email validation failed:');
      result.errors.forEach(error => console.error('- ' + error));
      return null;
    }
    
    return result;
  } catch (error) {
    console.error('Unexpected error during email validation:', error);
    return null;
  }
}

​
Best Practices

Recommended Settings
  • Enable details: true during development for better debugging
  • Use blockedDomains to prevent disposable email services
  • Keep allowPlusAddressing: true for better user flexibility
  • Always trim user input before validation (handled automatically)

​
Performance Considerations

  • The validator uses regex matching and string operations, which are fast for individual validations
  • For bulk email validation, consider batching or using async processing
  • The details option adds minimal overhead

​
Security Notes

  • Email validation does not guarantee deliverability
  • Always verify emails through confirmation links or OTP codes
  • Blocked domains list should be regularly updated
  • Be cautious with user-provided email addresses in your application

Build docs developers (and LLMs) love

Get started for freeTalk to us