email_integrity

A production-ready Flutter and Dart package for comprehensive email validation, email normalization, disposable/temporary email detection, fake/test domain filtering, custom domain policies, standard public domain filtering, and DNS/MX record lookups via DNS-over-HTTPS (DoH).

Designed for real-world production applications with zero platform native code requirements, running seamlessly across Android, iOS, Web, Windows, macOS, and Linux.

---

Features

• RFC Syntax Validation: Accurate RFC 5322/5321 syntax validation (local-part, domain, TLD, quoted forms, consecutive dots, length limits).
• Safe Email Normalization: Normalizes whitespace and domain parts without altering local-part mailbox identity.
• Disposable & Temporary Email Detection: Built-in dataset of top temporary email providers (e.g. Mailinator, 10MinuteMail, GuerrillaMail, YopMail, TempMail).
• Fake & Test Address Detection: Identifies common test domains and example addresses (example.com, test@test.com, localhost).
• Standard Public Domains Filter: Restrict validation to recognized major public email providers (Google, Microsoft, Yahoo, Apple, Proton, AOL, Zoho, GMX, Yandex, Mail.ru, Fastmail, Tuta, Rediffmail, etc.) plus optional custom allowed domains.
• Custom Domain Rules & Policies: Configure allowlists (allowedDomains), blocklists (blockedDomains), and strict domain policies (DomainPolicy).
• DNS & MX Record Validation: Optional asynchronous domain existence and MX mail server checks powered by DNS-over-HTTPS (DoH).
• Cross-Platform & Web Ready: Pure Dart implementation working out-of-the-box on Web, iOS, Android, and Desktop without native code dependencies.
• Offline First: All syntax, normalization, disposable, fake, standard domains, and custom domain checks operate completely offline.
• Flutter Form Integration: Synchronous FormFieldValidator helper for direct use with TextFormField.
• Privacy Conscious: Zero third-party telemetry. Local checks remain 100% local, and sensitive email data is automatically redacted in logs.

---

Platform Support

Android	iOS	Web	Windows	macOS	Linux
✓	✓	✓	✓	✓	✓

---

Installation

Add email_integrity to your pubspec.yaml:

dependencies:
  email_integrity: ^0.1.0

Then run:

flutter pub get

---

Basic Usage

Asynchronous Validation (Full Check)

import 'package:email_integrity/email_integrity.dart';

void checkEmail() async {
  final result = await EmailIntegrity.validate(
    'user@company.com',
  );

  if (result.isValid) {
    print('Email accepted: ${result.normalizedEmail}');
  } else {
    print('Email rejected: ${result.reason}');
    print('Message: ${result.message}');
  }
}

Synchronous Validation (Offline Only)

For instant UI feedback or form validation:

final result = EmailIntegrity.validateSync(
  'user@example.com',
);

if (result.isValid) {
  print('Syntax and local rules passed');
}

---

Standard Public Email Domains Restriction

Restrict email signups to recognized standard public email providers (e.g. Gmail, Outlook, Yahoo, Apple, Proton, Rediffmail, etc.) while allowing custom enterprise domains:

final options = EmailValidationOptions(
  domainPolicy: DomainPolicy.standardPublicDomainsOnly, // or allowOnlyStandardDomains: true
  allowedDomains: {
    'mycustomcompany.com', // Custom user domain allowed alongside standard providers
  },
);

final result = EmailIntegrity.validateSync(
  'user@mycustomcompany.com',
  options: options,
);

---

Advanced Options

Configure validation modes, disposable detection, custom allowlists, and DNS/MX options:

final result = await EmailIntegrity.validate(
  'user@company.com',
  options: EmailValidationOptions(
    mode: EmailValidationMode.standard,
    checkDisposable: true,
    checkFakeDomains: true,
    checkDns: true,
    checkMx: true,
    domainPolicy: DomainPolicy.allowAny,
    blockedDomains: {
      'competitor.com',
      'badactor.org',
    },
    allowedDomains: {
      'company.com',
      'university.edu',
    },
    networkTimeout: Duration(seconds: 5),
  ),
);

---

Form Validation (TextFormField)

Use EmailIntegrity.formValidator() directly inside Flutter forms. Form validation runs synchronously and offline-safe to keep UI interactions fast and responsive.

TextFormField(
  decoration: const InputDecoration(
    labelText: 'Email Address',
  ),
  keyboardType: TextInputType.emailAddress,
  validator: EmailIntegrity.formValidator(
    requiredMessage: 'Email is required',
    invalidMessage: 'Please enter a valid email address',
  ),
);

---

Email Normalization

Normalize email addresses safely:

final normalized = EmailIntegrity.normalize(
  ' User.Name@Example.COM ',
);
// Result: 'User.Name@example.com'

Optional provider-specific normalization (e.g. Gmail tags/dots):

final normalizedGmail = EmailIntegrity.normalize(
  'John.Doe+newsletter@Gmail.COM',
  applyProviderNormalization: true,
);
// Result: 'johndoe@gmail.com'

---

DNS & MX Record Lookups

When checkDns: true or checkMx: true is set, email_integrity queries DNS-over-HTTPS endpoints (such as Cloudflare / Google DoH) to verify domain existence and MX mail server availability.

Note on Web Limitations: Browsers restrict raw socket DNS queries. Using DNS-over-HTTPS allows DNS/MX verification to work consistently across Web and all native platforms without requiring platform channels.

---

Privacy & Limitations

• email_integrity never transmits email addresses to external servers by default.
• Offline validation checks are performed 100% locally on the device.
• Log outputs automatically redact local-part identities (u***r@example.com).

---

Testing & Analysis

To analyze and run unit tests for the package:

flutter analyze
flutter test

---

License

This package is open-source and licensed under the MIT License.