⚡ FadSync Email Validator for Flutter

The official Flutter & Dart SDK for FadSync MailCheck.

Protect your mobile & web apps from fake signups, disposable/burner emails, mistyped addresses, and fraudulent accounts in 1 single line of code.

---

✨ Features

• ⚡ Blazing Fast Validation (<50ms): Sub-second RFC syntax verification, MX lookup via DNS-over-HTTPS, and fraud score analysis.
• 🚫 40M+ Disposable Domains Blocked: Instant detection of temporary and burner mail services (10minutemail, GuerrillaMail, Mailinator, etc.) across 40M+ disposable domains.
• 💡 Smart Typo Autocorrect: Suggests fixes for common domain typos (e.g. user@gamil.com ➔ user@gmail.com) with 1-tap chip replacement.
• 🛡️ 1-Click Auth Guard: Pre-flight your signup & login flows before persisting users to Firebase, Supabase, Appwrite, or custom Postgres/MongoDB databases.
• 🎨 Drop-in UI Widgets: Includes EmailValidatorFormField with real-time async debounce, animated progress spinner, and friendly validation error messages.
• 🧠 In-Memory Smart Cache: Automatically caches repeated checks to save API quota and boost UI responsiveness.

---

🚀 Quickstart in 30 Seconds

1. Install the Package

Add fadsync_email_validator to your pubspec.yaml or run in terminal:

flutter pub add fadsync_email_validator

2. Get Your Free API Key

1. Sign up at mailcheck.fadsync.com.
2. Copy your API Key from your developer dashboard.

3. Verify an Email Address

import 'package:fadsync_email_validator/fadsync_email_validator.dart';

void main() async {
  // Initialize client with your API key
  final validator = FadSyncEmailValidator(apiKey: 'YOUR_API_KEY');

  // Verify any email address
  final result = await validator.verify('user@trashmail.com');

  if (result.isSafeToRegister) {
    print('✅ Safe to register: ${result.email}');
  } else {
    print('❌ Blocked: ${result.userFriendlyMessage}');
    // Output: "Temporary and disposable email addresses are not permitted. Please use a permanent email."
  }
}

---

🔒 1-Click Secure Signup & Login Flow

Use FadSyncAuthGuard to wrap your user registration flow. It blocks disposable emails and ensures that only valid, deliverable addresses reach your database.

import 'package:flutter/material.dart';
import 'package:fadsync_email_validator/fadsync_email_validator.dart';

final validator = FadSyncEmailValidator(apiKey: 'YOUR_API_KEY');

Future<void> handleUserSignUp(BuildContext context, String email, String password) async {
  await FadSyncAuthGuard.protect(
    client: validator,
    email: email,
    // Triggered only when the email is clean, deliverable, and safe
    onAllowed: (result) async {
      // 💾 Save user to Firebase / Supabase / Backend database
      await databaseService.createUser(
        email: result.email,
        password: password,
      );
      
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Account created successfully! 🎉')),
      );
    },
    // Triggered when email is disposable, invalid, or high-risk
    onBlocked: (errorMessage, result) {
      showDialog(
        context: context,
        builder: (ctx) => AlertDialog(
          title: const Text('Invalid Email'),
          content: Text(errorMessage), // e.g. "Temporary emails are not permitted."
          actions: [
            TextButton(
              onPressed: () => Navigator.pop(ctx),
              child: const Text('OK'),
            ),
          ],
        ),
      );
    },
    // Optional: Prompt user if they made a common domain typo (e.g. @gmai.com)
    onTypoFound: (suggestedEmail, result) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(
          content: Text('Did you mean $suggestedEmail?'),
          action: SnackBarAction(
            label: 'Fix',
            onPressed: () => emailController.text = suggestedEmail,
          ),
        ),
      );
    },
  );
}

---

🎨 Drop-in UI Widget: EmailValidatorFormField

Replace standard TextFormField with EmailValidatorFormField to get automatic debounced real-time validation, animated spinner, status checkmark, and autocorrect chip:

EmailValidatorFormField(
  client: validator,
  controller: emailController,
  triggerMode: ValidationTriggerMode.onChangedDebounced,
  debounceDuration: const Duration(milliseconds: 500),
  showTypoSuggestion: true,
  decoration: InputDecoration(
    labelText: 'Business Email',
    hintText: 'alex@company.com',
    border: OutlineInputBorder(borderRadius: BorderRadius.circular(12)),
  ),
  onValidated: (result) {
    print('Risk Score: ${result.riskScore}, Is Disposable: ${result.isDisposable}');
  },
)

---

⚙️ Custom Validation Strictness & Rules

You can adjust the strictness presets or customize individual scoring parameters:

// Strict preset for banking / payment apps
final result = await validator.verify(
  'sales@tempmail.com',
  options: ValidationOptions.strict, // Blocks disposable + role accounts + strict score < 50
);

// Custom criteria
final customOptions = ValidationOptions(
  strictness: StrictnessLevel.medium,
  maxAllowedRiskScore: 60,  // Block if risk score exceeds 60/100
  blockDisposable: true,    // Block 10minutemail, etc.
  blockRoleAccounts: false, // Allow info@, support@
  timeout: const Duration(seconds: 5),
);

---

📊 Result Model Reference (ValidationResult)

Property	Type	Description
isSafeToRegister	bool	true if valid syntax, active MX records, and not disposable.
isBlocked	bool	true if disposable, bad format, or recommendation is BLOCK.
isDisposable	bool	true if domain is in temporary/burner provider database.
isValidFormat	bool	true if RFC compliant format.
isFreeProvider	bool	true for Gmail, Yahoo, Outlook, ProtonMail, etc.
isRoleAccount	bool	true for generic accounts (admin@, support@, billing@).
riskScore	int	Fraud/deliverability risk score from 0 (clean) to 100 (fraud).
recommendation	enum	ValidationRecommendation.allow, flag, or block.
typoFix	String?	Auto-suggested domain correction if a spelling typo is detected.
userFriendlyMessage	String	Human-readable explanation ready to show directly in UI dialogs.
domainDetails.hasValidMx	bool	true if domain has active MX mail exchange servers.

---

🛡️ Exception Handling

try {
  final result = await validator.verify(email);
} on FadSyncAuthException {
  print('Invalid or expired FadSync API Key.');
} on FadSyncRateLimitException {
  print('Rate limit exceeded (HTTP 429).');
} on FadSyncNetworkException {
  print('Network timeout or offline.');
} on FadSyncApiException catch (e) {
  print('API error code: ${e.statusCode}');
}

---

📄 License

This SDK is open-source software licensed under the MIT License. Built with 💙 by the FadSync Team.