disposable_email_validator 0.0.1

A Dart/Flutter package for validating disposable email addresses by checking against a regularly updated list of 4000+ disposable email domains.

Disposable Email Validator

A Dart package for validating disposable/temporary email addresses by checking against a regularly updated list of disposable email domains.

Features

• ✅ Validates emails against 4000+ disposable domains
• 🚀 Automatic caching with configurable duration
• ⚡ Synchronous validation when cache is available
• 🔄 Automatic retry with exponential backoff
• 🛡️ Custom exceptions for better error handling
• ⚙️ Configurable timeout and retry settings

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  disposable_email_validator: ^1.0.0
  http: ^1.1.0

Then run:

dart pub get

Usage

Basic Example

import 'package:disposable_email_validator/disposable_email_validator.dart';

void main() async {
  final validator = DisposableEmailValidator();

  // Check if email is disposable
  final isDisposable = await validator.isDisposable('[e-mail]');

  if (isDisposable) {
    print('⚠️ Disposable email detected!');
  } else {
    print('✅ Valid email');
  }

  validator.dispose();
}

Form Validation Example

String? validateEmail(String? email) async {
  if (email == null || email.isEmpty) {
    return 'Email is required';
  }

  final validator = DisposableEmailValidator();

  try {
    final isDisposable = await validator.isDisposable(
      email,
      throwOnInvalidFormat: true,
    );

    if (isDisposable) {
      return 'Please use a permanent email address';
    }
  } on InvalidEmailFormatException {
    return 'Invalid email format';
  } catch (e) {
    return 'Unable to validate email';
  } finally {
    validator.dispose();
  }

  return null;
}

Custom Configuration

final validator = DisposableEmailValidator(
  cacheDuration: Duration(hours: 12),  // Cache for 12 hours
  timeout: Duration(seconds: 5),        // 5 second timeout
  maxRetries: 3,                        // Retry 3 times on failure
);

Synchronous Validation

final validator = DisposableEmailValidator();

// Ensure cache is loaded
await validator.fetchDisposableDomains();

// Now use sync validation
if (validator.isCacheValid) {
  final result = validator.isDisposableSync('[e-mail]');
  print('Is disposable: $result');
}

validator.dispose();

Error Handling

final validator = DisposableEmailValidator();

try {
  final result = await validator.isDisposable('[e-mail]');
  print('Result: $result');
} on InvalidEmailFormatException catch (e) {
  print('Invalid email: $e');
} on NetworkTimeoutException catch (e) {
  print('Request timed out: $e');
} on DisposableDomainsException catch (e) {
  print('Failed to fetch domains: $e');
} finally {
  validator.dispose();
}

Cache Management

final validator = DisposableEmailValidator();

// Check cache status
print('Cached domains: ${validator.cachedDomainsCount}');
print('Last fetched: ${validator.lastFetchTime}');
print('Cache valid: ${validator.isCacheValid}');

// Manually refresh cache
await validator.fetchDisposableDomains();

// Clear cache
validator.clearCache();

validator.dispose();

Using with Custom HTTP Client

final customClient = http.Client();
final validator = DisposableEmailValidator(httpClient: customClient);

await validator.isDisposable('[e-mail]');

// Validator won't close the custom client on dispose
validator.dispose();
customClient.close(); // You manage the lifecycle

API Reference

DisposableEmailValidator

Constructor

DisposableEmailValidator({
  Duration cacheDuration = const Duration(hours: 24),
  Duration timeout = const Duration(seconds: 10),
  int maxRetries = 2,
  http.Client? httpClient,
})

Methods

• Future<bool> isDisposable(String email, {bool throwOnInvalidFormat = false}) - Validates if email is disposable
• bool? isDisposableSync(String email) - Synchronous validation (requires valid cache)
• Future<void> fetchDisposableDomains() - Manually fetch/refresh domains list
• void clearCache() - Clear cached domains
• void dispose() - Clean up resources

Properties

• int? cachedDomainsCount - Number of cached domains
• DateTime? lastFetchTime - When cache was last updated
• bool isCacheValid - Whether cache is currently valid

Exceptions

• DisposableDomainsException - Failed to fetch domains
• InvalidEmailFormatException - Invalid email format
• NetworkTimeoutException - Request timed out

Data Source

This package uses the community-maintained list from: https://disposable.github.io/disposable-email-domains/

The list is updated regularly and contains 4000+ disposable email domains.

License

MIT License - see LICENSE file for details