temp_mail_blocker 1.1.1

Official Flutter/Dart SDK for TempMailBlocker email validation service. Validate emails with syntax checking, domain verification, MX records, SMTP validation, disposable email detection, and risk assessment.

TempMailBlocker SDK for Flutter/Dart

Official Flutter/Dart SDK for the TempMailBlocker email validation service.

🎁 Get Started with Free Credits

New users get 100 free credits when you sign up! No credit card required.

1. Sign up at https://tempmailblocker.com/
2. Get your API key from the dashboard
3. Start validating emails immediately with your free credits

Visit https://tempmailblocker.com/ to create your account and get started.

Installation

Add this to your pubspec.yaml:

dependencies:
  temp_mail_blocker: ^1.1.1

Then run:

flutter pub get

Or install directly using:

flutter pub add temp_mail_blocker

Quick Start

Get your API key from the dashboard after signing up (new users get 100 free credits!).

import 'package:temp_mail_blocker/temp_mail_blocker.dart';

void main() async {
  // Initialize the SDK with your API key
  // Get your API key from: https://tempmailblocker.com/
  final client = MailValidationClient(
    apiKey: 'your-api-key', // Get this from your dashboard
    baseUrl: 'https://tempmailblocker.com',
  );

  // Validate a single email
  try {
    final result = await client.validateEmail('[e-mail]');
    print('Email: ${result.email}');
    print('Valid: ${result.isValid}');
    print('Score: ${result.score}');
    print('Deliverable: ${result.deliverable}');
    
    // Check remaining credits
    if (result.creditsRemaining != null) {
      print('Credits remaining: ${result.creditsRemaining}');
    }
  } catch (e) {
    if (e is ApiException) {
      print('Error: ${e.message} (${e.statusCode})');
      if (e.statusCode == 402) {
        print('Insufficient credits. Visit https://tempmailblocker.com/ to purchase more.');
      }
    } else {
      print('Error: $e');
    }
  }
}

Getting Your API Key

1. Sign up at https://tempmailblocker.com/
2. Get 100 free credits automatically when you sign up
3. Navigate to API Keys section in your dashboard
4. Create a new API key or use the default one
5. Copy your API key and use it in the SDK

💡 Tip: New users receive 100 free credits upon signup, perfect for testing and getting started!

API Reference

Constructor

MailValidationClient({
  required String apiKey,
  required String baseUrl,
  Duration timeout = const Duration(seconds: 30),
})

Parameters:

• apiKey (String): Your email validation API key (get it from dashboard - new users get 100 free credits!)
• baseUrl (String): The base URL of the email validation API (e.g., https://tempmailblocker.com)
• timeout (Duration): Request timeout duration (default: 30 seconds)

Single Email Validation

Future<SingleValidationResponse> validateEmail(String email)

Validates a single email address and returns detailed validation results.

Example:

final result = await client.validateEmail('[e-mail]');

print(result.isValid);        // true/false
print(result.score);          // 0-100 validation score
print(result.deliverable);    // true/false
print(result.disposable);     // true/false
print(result.risk);           // 'LOW', 'MEDIUM', or 'HIGH'
print(result.provider);       // 'Gmail', 'Yahoo', etc.

// Get mocking message for disposable emails
if (result.disposable) {
  final message = result.getMockingMessage();
  print(message); // Random mocking message
}

Bulk Email Validation

Create Bulk Job

Future<BulkValidationJob> createBulkJob({
  required List<String> emails,
  String? name,
})

Creates a bulk validation job for multiple emails.

Example:

final job = await client.createBulkJob(
  emails: [
    '[e-mail]',
    '[e-mail]',
    '[e-mail]',
  ],
  name: 'My Email List', // optional
);

print(job.id); // Use this to check status and get results

Check Job Status

Future<BulkValidationJob> getJobStatus(String jobId)

Example:

final status = await client.getJobStatus(job.id);
print(status.status); // 'PENDING', 'PROCESSING', 'COMPLETED', or 'FAILED'
print('${status.processedEmails}/${status.totalEmails} processed');

Get Job Results

Future<BulkValidationResult> getJobResults(String jobId)

Example:

// Only call this when job status is 'COMPLETED'
final results = await client.getJobResults(job.id);

print(results.summary.total);    // Total emails
print(results.summary.valid);     // Valid emails
print(results.summary.invalid);   // Invalid emails

results.results.forEach((result) {
  print('${result.email}: ${result.isValid ? 'Valid' : 'Invalid'}');
});

Wait for Job Completion

Future<BulkValidationResult> waitForJobCompletion(
  String jobId, {
  Duration pollInterval = const Duration(seconds: 5),
  Duration timeout = const Duration(minutes: 5),
})

Convenience method that polls for job completion and returns results automatically.

Example:

// Create job and wait for completion
final job = await client.createBulkJob(
  emails: ['[e-mail]', '[e-mail]'],
);

try {
  final results = await client.waitForJobCompletion(
    job.id,
    pollInterval: const Duration(seconds: 5),
    timeout: const Duration(minutes: 5),
  );

  print('Job completed: ${results.summary.valid} valid, ${results.summary.invalid} invalid');
} catch (e) {
  if (e is ApiException) {
    print('Job failed or timed out: ${e.message}');
  }
}

Job Management

List Jobs

Future<List<BulkValidationJob>> listJobs({
  int limit = 10,
  int page = 1,
})

Example:

final jobs = await client.listJobs(limit: 10, page: 1);
jobs.forEach((job) {
  print('Job ${job.id}: ${job.status}');
});

Delete Job

Future<void> deleteJob(String jobId)

Example:

await client.deleteJob(job.id);
print('Job deleted successfully');

Response Types

SingleValidationResponse

class SingleValidationResponse {
  final String email;
  final bool isValid;
  final int score;              // 0-100 validation score
  final bool deliverable;
  final bool syntaxValid;
  final bool domainValid;
  final bool mxRecords;
  final bool smtpValid;
  final bool? catchAll;
  final bool disposable;
  final bool generic;
  final String? provider;
  final String risk;            // 'LOW' | 'MEDIUM' | 'HIGH'
  final String? confidence;
  final String? suggestion;
  final int? creditsRemaining;
  final bool? cached;
  final String? timestamp;

  /// Gets a random mocking message if email is disposable.
  /// Returns null if email is not disposable.
  String? getMockingMessage();
}

BulkValidationJob

class BulkValidationJob {
  final String id;
  final String status;          // 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED'
  final int totalEmails;
  final int processedEmails;
  final int? validEmails;
  final int? invalidEmails;
  final String createdAt;
  final String? completedAt;
  final String? errorMessage;

  // Convenience getters
  bool get isCompleted;
  bool get isFailed;
  bool get isProcessing;
  bool get isPending;
}

BulkValidationResult

class BulkValidationResult {
  final String jobId;
  final String status;
  final List<SingleValidationResponse> results;
  final BulkSummary summary;
}

class BulkSummary {
  final int total;
  final int valid;
  final int invalid;
  final int processed;
}

Error Handling

The SDK throws ApiException for API errors that you can catch and handle:

try {
  final result = await client.validateEmail('invalid-email');
} on ApiException catch (e) {
  // API error
  print('API Error ${e.statusCode}: ${e.message}');
  if (e.code != null) {
    print('Error Code: ${e.code}');
  }
} catch (e) {
  // Network or other error
  print('Error: $e');
}

Complete Example

import 'package:temp_mail_blocker/temp_mail_blocker.dart';

Future<void> main() async {
  // Get your API key from: https://tempmailblocker.com/
  // New users get 100 free credits when they sign up!
  final client = MailValidationClient(
    apiKey: 'your-api-key', // Get this from your dashboard
    baseUrl: 'https://tempmailblocker.com',
  );

  try {
    // Single validation
    print('=== Single Validation ===');
    final singleResult = await client.validateEmail('[e-mail]');
    print('Single validation result:');
    print('  Email: ${singleResult.email}');
    print('  Valid: ${singleResult.isValid}');
    print('  Score: ${singleResult.score}');
    print('  Deliverable: ${singleResult.deliverable}');
    print('  Risk: ${singleResult.risk}');
    print('  Provider: ${singleResult.provider ?? 'Unknown'}');
    
    // Check remaining credits
    if (singleResult.creditsRemaining != null) {
      print('  Credits Remaining: ${singleResult.creditsRemaining}');
    }

    // Bulk validation
    print('\n=== Bulk Validation ===');
    final bulkJob = await client.createBulkJob(
      emails: [
        '[e-mail]',
        '[e-mail]',
        'invalid@email',
      ],
      name: 'Test Validation',
    );

    print('Bulk job created: ${bulkJob.id}');

    // Wait for completion
    final bulkResults = await client.waitForJobCompletion(bulkJob.id);
    print('Bulk validation completed:');
    print('  Total: ${bulkResults.summary.total}');
    print('  Valid: ${bulkResults.summary.valid}');
    print('  Invalid: ${bulkResults.summary.invalid}');

    // Print individual results
    bulkResults.results.forEach((result) {
      print('  ${result.email}: ${result.isValid ? '✓' : '✗'} (Score: ${result.score})');
    });

  } on ApiException catch (e) {
    print('API Error: ${e.message} (${e.statusCode})');
    if (e.statusCode == 402) {
      print('💡 Insufficient credits. Visit https://tempmailblocker.com/ to purchase more.');
      print('   New users get 100 free credits when they sign up!');
    } else if (e.statusCode == 401) {
      print('💡 Invalid API key. Get your API key from: https://tempmailblocker.com/');
    }
  } catch (e) {
    print('Error: $e');
  }
}

License

MIT

Support

For questions and support, please visit our documentation or contact [e-mail].