Email Verify SDK

A powerful and efficient Node.js SDK for verifying email addresses with support for both single and bulk validation. Validate email format, detect disposable emails, and verify domain MX records.

Features

✅ Single Email Verification - Validate individual email addresses
✅ Bulk Email Verification - Process hundreds or thousands of emails efficiently
✅ Format Validation - Check email syntax and structure
✅ Disposable Email Detection - Identify temporary/disposable email addresses
✅ MX Record Verification - Verify domain has valid mail servers
✅ Streaming Support - Process large datasets without memory issues
✅ Real-time Progress - Track validation progress with callbacks
✅ CSV Support - Validate emails from CSV files
✅ TypeScript Support - Full type definitions included

---

Installation

npm install email-verify-sdk

---

Quick Start

import { EmailVerify } from 'email-verify-sdk';

const emailVerifier = new EmailVerify();

// Verify a single email
const result = await emailVerifier.verifyEmail('user@example.com');
console.log(result);

// Verify bulk email
const bulkRes = await emailVerifier.verifyBulkEmail(["user1@example.com", "user2@example.com", "user3@example.com", "user4@example.com" ], {onProgress: (progress)=> console.log(progress), onComplete: (summary)=> console.log(summary, 'summary')});
console.log(bulkRes, 'result summary')

---

API Reference

verifyEmail(email: string)

Verify a single email address.

Parameters

Parameter	Type	Required	Description
email	string	Yes	The email address to verify

Returns

Promise<SingleEmailVerificationResponse>

{
  isValid: boolean;    // Whether the email is valid
  message: string;     // Descriptive message about the result
}

Example

const emailVerifier = new EmailVerify();

const result = await emailVerifier.verifyEmail('test@example.com');

if (result.isValid) {
  console.log('✅ Email is valid:', result.message);
} else {
  console.log('❌ Email is invalid:', result.message);
}

verifyBulkEmail(emails: BulkEmailType, options?: BulkEmailValidateOptions)

Verify multiple email addresses in bulk with support for streaming and progress tracking.

Parameters

BulkEmailType can be one of the following:

Type	Description	Example
string[]	Array of email addresses	['email1@test.com', 'email2@test.com']
string	File path to CSV file	'./emails.csv'
Buffer	CSV file buffer	fs.readFileSync('emails.csv')
ReadStream	CSV file stream	fs.createReadStream('emails.csv')

BulkEmailValidateOptions

{
  concurrencyLimit?: number;                             // Concurrent validations (default: 10)
  onProgress?: (progress: ValidationProgress) => void;  // Progress callback
  onResult?: (result: EmailValidationResult) => void;   // Result callback
  onComplete?: (summary: ValidationSummary) => void;    // Completion callback
  onError?: (error: Error, email: string, index: number) => void;  // Error callback
  stopOnError?: boolean;                            // Stop on first error (default: false)
}

Returns

Promise<BulkEmailVerificationResponse>

{
    total: number;        // Total emails processed
    valid: number;        // Number of valid emails
    invalid: number;      // Number of invalid emails
    duration: number;     // Processing time in milliseconds
    errors: Array<{       // List of errors encountered
      index: number;
      email: string;
      error: string;
    }>;
}

Type Definitions

// Progress callback data
type BulkEmailValidationProgress = {
  processed: number;    // Number of emails processed
  total: number;        // Total number of emails
  percentage: number;   // Completion percentage
  valid: number;        // Valid emails so far
  invalid: number;      // Invalid emails so far
};

// Individual result data
type EmailValidationResult = {
  email: string;        // Email address
  isValid: boolean;     // Validation result
  message: string;      // Descriptive message
  index: number;        // Position in the input list
  timestamp: string;    // ISO timestamp
};

// Final summary data
type BulkEmailVerificationResponse = {
  total: number;
  valid: number;
  invalid: number;
  duration: number;
  errors: Array<{ index: number; email: string; error: string }>;
};

---

Usage Examples

Example 1: Verify Array of Emails

import { EmailVerify } from 'email-verify-sdk';

const emailVerifier = new EmailVerify();

const emails = [
  'user1@example.com',
  'user2@example.com',
  'invalid-email',
  'disposable@tempmail.com'
];

const result = await emailVerifier.verifyBulkEmail(emails);

console.log(`Total: ${result.total}`);
console.log(`Valid: ${result.valid}`);
console.log(`Invalid: ${result.invalid}`);
console.log(`Duration: ${result.duration}ms`);

---

Example 2: Verify Emails from CSV File

const result = await emailVerifier.verifyBulkEmail('./emails.csv');

console.log(result);

CSV Format:

email
user1@example.com
user2@example.com
user3@example.com

---

Example 3: Real-time Progress Tracking

const result = await emailVerifier.verifyBulkEmail({
  emails: './large-email-list.csv',
  concurrency: 20,
  onProgress: (progress) => {
    console.log(`Progress: ${progress.percentage}%`);
    console.log(`Processed: ${progress.processed}/${progress.total}`);
    console.log(`Valid: ${progress.valid}, Invalid: ${progress.invalid}`);
  }
});

---

Example 4: Process Results as They Come

const validEmails = [];
const invalidEmails = [];

await emailVerifier.verifyBulkEmail({
  emails: ['email1@test.com', 'email2@test.com', 'invalid@email'],
  onResult: (result) => {
    if (result.isValid) {
      validEmails.push(result.email);
      console.log(`✅ ${result.email}`);
    } else {
      invalidEmails.push({ email: result.email, reason: result.message });
      console.log(`❌ ${result.email}: ${result.message}`);
    }
  },
  onComplete: (summary) => {
    console.log('Validation complete!');
    console.log(`Total valid: ${validEmails.length}`);
    console.log(`Total invalid: ${invalidEmails.length}`);
  }
});

---

Example 5: Save Results to Database

import { EmailVerify } from 'email-verify-sdk';
import { database } from './database';

const emailVerifier = new EmailVerify();

await emailVerifier.verifyBulkEmail({
  emails: './customer-emails.csv',
  concurrency: 50,
  onResult: async (result) => {
    // Save each result to database immediately
    await database.emailValidations.create({
      email: result.email,
      isValid: result.isValid,
      message: result.message,
      reason: result.reason,
      validatedAt: result.timestamp
    });
  },
  onProgress: (progress) => {
    console.log(`Saved ${progress.processed} results to database`);
  }
});

---

Example 6: Handle Errors Gracefully

const errors = [];

const result = await emailVerifier.verifyBulkEmail({
  emails: './emails.csv',
  onError: (error, email, index) => {
    console.error(`Error at index ${index} for ${email}:`, error.message);
    errors.push({ index, email, error: error.message });
  },
  stopOnError: false  // Continue processing even if some emails fail
});

console.log(`Completed with ${errors.length} errors`);
console.log(result.errors);

---

Example 7: Using ReadStream for Large Files

import fs from 'fs';

const stream = fs.createReadStream('./large-email-list.csv');

const result = await emailVerifier.verifyBulkEmail({
  emails: stream,
  concurrency: 100,
  onProgress: (progress) => {
    console.log(`${progress.percentage}% complete`);
  }
});

console.log(`Processed ${result.total} emails in ${result.duration}ms`);

---

Example 8: Using Buffer

import fs from 'fs';

const buffer = fs.readFileSync('./emails.csv');

const result = await emailVerifier.verifyBulkEmail(buffer);
console.log(result);

---

Validation Process

The SDK performs validation in the following order:

1. Format Validation - Checks if the email matches a valid email pattern
2. Disposable Email Detection - Checks if the email is from a disposable/temporary email provider
3. MX Record Verification - Verifies the domain has valid mail exchange (MX) records

If any step fails, validation stops and returns the failure reason.

---

Error Handling

Single Email Verification

try {
  const result = await emailVerifier.verifyEmail('test@example.com');
  console.log(result);
} catch (error) {
  console.error('Validation failed:', error.message);
}

Bulk Email Verification

const result = await emailVerifier.verifyBulkEmail({
  emails: './emails.csv',
  onError: (error, email, index) => {
    // Handle individual email errors
    console.error(`Failed to validate ${email}:`, error.message);
  }
});

// Check result for any errors
if (result.errors.length > 0) {
  console.log('Some emails failed validation:');
  result.errors.forEach(err => {
    console.log(`- ${err.email}: ${err.error}`);
  });
}

---

Performance Tips

Optimize Concurrency

Adjust the concurrency parameter based on your use case:

// Conservative (good for rate-limited APIs)
await emailVerifier.verifyBulkEmail({
  emails: './emails.csv',
  concurrency: 5
});

// Balanced (default)
await emailVerifier.verifyBulkEmail({
  emails: './emails.csv',
  concurrency: 10
});

// Aggressive (for large datasets, ensure your system can handle it)
await emailVerifier.verifyBulkEmail({
  emails: './emails.csv',
  concurrency: 50
});

Memory Optimization

For very large datasets (5,000+ emails), use callbacks to process results immediately instead of storing them:

// ✅ Good - Process results immediately
await emailVerifier.verifyBulkEmail({
  emails: './huge-list.csv',
  onResult: (result) => {
    database.save(result);  // Save immediately
  }
});

// ❌ Bad - Storing all results in memory
const allResults = [];
await emailVerifier.verifyBulkEmail({
  emails: './huge-list.csv',
  onResult: (result) => {
    allResults.push(result);  // Memory grows with dataset size
  }
});

---

CSV File Format

The SDK supports CSV files with the following formats:

Option 1: With Header

email
user1@example.com
user2@example.com
user3@example.com

Option 2: First Column (No Header)

user1@example.com
user2@example.com
user3@example.com

Option 3: Multiple Columns (Uses 'email' or 'Email' or 'EMAIL' column or first column)

name,email,company
John Doe,john@example.com,Acme Inc
Jane Smith,jane@example.com,Tech Co

---

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import { 
  EmailVerify,
  SingleEmailVerificationResponse,
  BulkEmailVerificationResponse,
  EmailValidationResult,
  BulkEmailValidationProgress
} from 'email-verify-sdk';

const emailVerifier: EmailVerify = new EmailVerify();

const result: SingleEmailVerificationResponse = 
  await emailVerifier.verifyEmail('test@example.com');

const bulkResult: BulkEmailVerificationResponse = 
  await emailVerifier.verifyBulkEmail(['email1@test.com', 'email2@test.com']);

---

Common Use Cases

Use Case 1: Clean Email List Before Marketing Campaign

const validEmails = [];

await emailVerifier.verifyBulkEmail({
  emails: './marketing-list.csv',
  concurrency: 30,
  onResult: (result) => {
    if (result.isValid) {
      validEmails.push(result.email);
    }
  }
});

// Use validEmails for your campaign
console.log(`Ready to send to ${validEmails.length} verified emails`);

Use Case 2: User Registration Validation

app.post('/register', async (req, res) => {
  const { email } = req.body;
  
  const result = await emailVerifier.verifyEmail(email);
  
  if (!result.isValid) {
    return res.status(400).json({ 
      error: result.message 
    });
  }
  
  // Proceed with registration
  await createUser(email);
  res.json({ success: true });
});

Use Case 3: Periodic Email List Cleanup

import { CronJob } from 'cron';

// Run every Sunday at midnight
new CronJob('0 0 * * 0', async () => {
  const users = await database.users.findAll();
  
  await emailVerifier.verifyBulkEmail({
    emails: users.map(u => u.email),
    concurrency: 20,
    onResult: async (result) => {
      if (!result.isValid) {
        await database.users.update(
          { emailInvalid: true, invalidReason: result.message },
          { where: { email: result.email } }
        );
      }
    }
  });
  
  console.log('Email cleanup complete');
}).start();

---

Troubleshooting

Issue: Verification is slow

Solution: Increase the concurrency parameter:

await emailVerifier.verifyBulkEmail({
  emails: './emails.csv',
  concurrency: 50  // Increase from default 10
});

Issue: Out of memory errors

Solution: Use callbacks to process results immediately instead of storing them:

await emailVerifier.verifyBulkEmail({
  emails: './huge-list.csv',
  onResult: (result) => {
    // Process immediately, don't store
    saveToDatabase(result);
  }
});

Issue: CSV parsing errors

Solution: Ensure your CSV file:

• Has an 'email' or 'Email' or 'EMAIL' column header, OR
• Has emails in the first column
• Uses standard CSV format (comma-separated)
• Contains valid text data (not binary files)

---

License

MIT

---

Support

For issues, questions, or contributions, please visit our GitHub repository or contact support.

---

Changelog

v1.0.0

• Initial release
• Single email verification
• Bulk email verification
• CSV support
• Progress tracking
• TypeScript support