Home / Reference / Email Validation

Email Validation Platform

Temp Mail Blocker helps you validate emails in real-time, process bulk lists, and integrate verification into your applications via powerful APIs and SDKs.

Reliable

Accurate checks for syntax, domain, MX, disposable, role, and more.

Scalable

Bulk validation for large lists with job tracking and summaries.

Developer-first

Clean REST API and official Node.js SDK with TypeScript types.

Getting Started

1. Create an account

2. Generate an API key

Create and manage keys from your dashboard settings.

3. Make your first request

Use the REST API or our Node.js SDK to validate emails.

Authentication

Include your API key in the request headers as shown below.

HTTP Header

x-mails-api-key: your_api_key_here

Single Email Validation

Validate a single email address and receive deliverability and risk details.

POST /api/v1/validate

POST /api/v1/validate

Request Body:
{
  "email": "test@example.com"
}

Response:
{
  "email": "test@example.com",
  "deliverable": true,
  "risk": "LOW",
  "reason": "valid_mailbox",
  "mx_found": true,
  "catch_all": false,
  "role_account": false,
  "disposable": false,
  "free_email": false,
  "timestamp": "2024-01-01T12:00:00Z"
}

Bulk Email Validation

Submit a batch of emails and track the job until completion.

POST /api/v1/batch

POST /api/v1/batch

Request Body:
{
  "emails": [
    "user1@example.com",
    "user2@test.com",
    "user3@domain.org"
  ]
}

Response:
{
  "jobId": "job_123456789",
  "status": "processing",
  "totalEmails": 3,
  "estimatedTime": "2-5 minutes",
  "createdAt": "2024-01-01T12:00:00Z"
}

Job Results

Retrieve the results when the job status is completed.

GET /api/v1/jobs/{jobId}/results

GET /api/v1/jobs/{jobId}/results

Response:
{
  "jobId": "job_123456789",
  "status": "completed",
  "results": [
    {
      "email": "user1@example.com",
      "deliverable": true,
      "risk": "LOW",
      "reason": "valid_mailbox"
    }
  ],
  "summary": {
    "total": 3,
    "valid": 2,
    "invalid": 1,
    "risky": 0
  }
}

Node.js SDK

Official Node.js SDK for the TempMailBlocker email validation service. Visit https://tempmailblocker.com/ to purchase credits and get started.

Installation

npm install @webnoxdigital/tempmail-blocker
# or
yarn add @webnoxdigital/tempmail-blocker
# or
pnpm add @webnoxdigital/tempmail-blocker

Quick Start (CommonJS)

const { TempMailBlocker } = require('@webnoxdigital/tempmail-blocker');

// Initialize the SDK
const tempMailBlocker = new TempMailBlocker({
  apiKey: "your-api-key",
  baseUrl: "https://tempmailblocker.com"
});

// Validate a single email
async function validateEmail() {
  try {
    const result = await tempMailBlocker.singleValidation({
      email: "test@example.com"
    });
    console.log(result);
  } catch (error) {
    console.error('Validation failed:', error.message);
  }
}

validateEmail();

Quick Start (TypeScript / ESM)

import { TempMailBlocker, SingleValidationResponse } from '@webnoxdigital/tempmail-blocker';

const tempMailBlocker = new TempMailBlocker({
  apiKey: "your-api-key",
  baseUrl: "https://tempmailblocker.com"
});

const result: SingleValidationResponse = await tempMailBlocker.singleValidation({
  email: "test@example.com"
});

console.log(result);

Single Email Validation

const result = await tempMailBlocker.singleValidation({
  email: "user@domain.com"
});

console.log(result);
// {
//   email: "user@domain.com",
//   valid: true,
//   score: 95,
//   details: {
//     syntax: true,
//     domain: true,
//     mx: true,
//     disposable: false,
//     role: false,
//     free: false
//   }
// }

Bulk Validation Workflow

const tempMailBlocker = new TempMailBlocker({
  apiKey: process.env.TEMPMAILBLOCKER_API_KEY,
  baseUrl: "https://tempmailblocker.com"
});

// Create bulk job
const job = await tempMailBlocker.createBulkJob({
  emails: [
    "user1@domain.com",
    "user2@domain.com",
    "user3@domain.com"
  ],
  name: "My Email List" // optional
});

console.log('Job ID:', job.jobId);

// Wait for completion (polls automatically)
try {
  const results = await tempMailBlocker.waitForJobCompletion(
    job.jobId,
    5000,  // Poll every 5 seconds
    300000 // Timeout after 5 minutes
  );

  console.log('Summary:', results.summary);
  // {
  //   total: 3,
  //   valid: 2,
  //   invalid: 1,
  //   processed: 3
  // }

  results.results.forEach(result => {
    console.log(`${result.email}: ${result.valid ? 'Valid' : 'Invalid'} (Score: ${result.score})`);
  });
} catch (error) {
  console.error('Job failed or timed out:', error.message);
}

Check Job Status

const status = await tempMailBlocker.getJobStatus(job.jobId);
console.log(status.status); // 'pending', 'processing', 'completed', or 'failed'
console.log(`${status.processedEmails}/${status.totalEmails} processed`);

// Get results when completed
if (status.status === 'completed') {
  const results = await tempMailBlocker.getJobResults(job.jobId);
  console.log(results.summary);
}

Job Management

// List all jobs
const jobs = await tempMailBlocker.listJobs(10, 0); // Get first 10 jobs
jobs.forEach(job => {
  console.log(`Job ${job.jobId}: ${job.status}`);
});

// Delete a job
await tempMailBlocker.deleteJob(job.jobId);
console.log('Job deleted successfully');

Error Handling

try {
  const result = await tempMailBlocker.singleValidation({
    email: "invalid-email"
  });
} catch (error) {
  if (error.statusCode) {
    // API error
    console.error(`API Error ${error.statusCode}: ${error.message}`);
    console.error('Error Code:', error.code);
  } else {
    // Network or other error
    console.error('Error:', error.message);
  }
}

Flutter/Dart SDK

Official Flutter/Dart SDK for the TempMailBlocker email validation service. Available on pub.dev/packages/temp_mail_blocker with 140+ pub points.

Package Published

Install from pub.dev/packages/temp_mail_blocker • 140+ pub points • MIT License

Installation

# Add to pubspec.yaml
dependencies:
  temp_mail_blocker: ^1.0.0

# Then run
flutter pub get

# Or install directly from pub.dev
# Visit: https://pub.dev/packages/temp_mail_blocker

Quick Start

import 'package:temp_mail_blocker/temp_mail_blocker.dart';

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

  // Validate a single email
  try {
    final result = await client.validateEmail('test@example.com');
    print('Email: ${result.email}');
    print('Valid: ${result.isValid}');
    print('Score: ${result.score}');
    print('Deliverable: ${result.deliverable}');
    print('Risk: ${result.risk}');
  } on ApiException catch (e) {
    print('Error: ${e.message} (${e.statusCode})');
  }
}

Single Email Validation

final result = await client.validateEmail('user@domain.com');

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.

Bulk Validation Workflow

// Create bulk job
final job = await client.createBulkJob(
  emails: [
    'user1@domain.com',
    'user2@domain.com',
    'user3@domain.com',
  ],
  name: 'My Email List', // optional
);

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

// Wait for completion (polls automatically)
try {
  final results = await client.waitForJobCompletion(
    job.id,
    pollInterval: const Duration(seconds: 5),
    timeout: const Duration(minutes: 5),
  );

  print('Summary:');
  print('  Total: ${results.summary.total}');
  print('  Valid: ${results.summary.valid}');
  print('  Invalid: ${results.summary.invalid}');

  // Print individual results
  results.results.forEach((result) {
    print('${result.email}: ${result.isValid ? "Valid" : "Invalid"} (Score: ${result.score})');
  });
} on ApiException catch (e) {
  print('Job failed or timed out: ${e.message}');
}

Check Job Status

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

// Get results when completed
if (status.isCompleted) {
  final results = await client.getJobResults(job.id);
  print('Valid: ${results.summary.valid}');
  print('Invalid: ${results.summary.invalid}');
}

Error Handling

try {
  final result = await client.validateEmail('test@example.com');
} on ApiException catch (e) {
  if (e.statusCode == 401) {
    print('Invalid API key');
  } else if (e.statusCode == 402) {
    print('Insufficient credits');
  } else {
    print('API Error: ${e.message}');
  }
} catch (e) {
  print('Network error: $e');
}

Flutter Widget Example

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

class EmailValidationWidget extends StatefulWidget {
  @override
  _EmailValidationWidgetState createState() => _EmailValidationWidgetState();
}

class _EmailValidationWidgetState extends State<EmailValidationWidget> {
  final _client = MailValidationClient(
    apiKey: 'your-api-key',
    baseUrl: 'https://tempmailblocker.com',
  );
  
  final _emailController = TextEditingController();
  bool _isValidating = false;
  SingleValidationResponse? _result;

  Future<void> _validateEmail() async {
    setState(() => _isValidating = true);
    
    try {
      final result = await _client.validateEmail(_emailController.text);
      setState(() {
        _result = result;
        _isValidating = false;
      });
    } on ApiException catch (e) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('Error: ${e.message}')),
      );
      setState(() => _isValidating = false);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        TextField(
          controller: _emailController,
          decoration: InputDecoration(labelText: 'Email'),
        ),
        ElevatedButton(
          onPressed: _isValidating ? null : _validateEmail,
          child: _isValidating 
            ? CircularProgressIndicator() 
            : Text('Validate'),
        ),
        if (_result != null)
          Text('Valid: ${_result!.isValid}, Score: ${_result!.score}'),
      ],
    );
  }
}

TypeScript Types

The SDK is written in TypeScript and includes full type definitions for requests and responses.

Response Types

interface SingleValidationResponse {
  email: string;
  valid: boolean;
  score: number;          // 0-100 validation score
  reason?: string;        // Reason if invalid
  details?: {
    syntax: boolean;      // Email syntax is valid
    domain: boolean;      // Domain exists
    mx: boolean;          // MX record exists
    disposable: boolean;  // Is disposable email
    role: boolean;        // Is role-based email
    free: boolean;        // Is free email provider
  };
}

interface BulkValidationJob {
  jobId: string;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  totalEmails: number;
  processedEmails: number;
  createdAt: string;
  completedAt?: string;
}

interface BulkValidationResult {
  jobId: string;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  results: SingleValidationResponse[];
  summary: {
    total: number;
    valid: number;
    invalid: number;
    processed: number;
  };
}

Python Example

Python

import requests

# Single email validation
response = requests.post(
    'https://tempmailblocker.com/api/v1/validate',
    headers={'x-mails-api-key': 'your_api_key'},
    json={'email': 'test@example.com'}
)

result = response.json()
print(f"Valid: {result['deliverable']}")
print(f"Risk: {result['risk']}")

# Bulk validation
bulk_response = requests.post(
    'https://tempmailblocker.com/api/v1/batch',
    headers={'x-mails-api-key': 'your_api_key'},
    json={'emails': ['user1@example.com', 'user2@test.com']}
)

job = bulk_response.json()
print(f"Job ID: {job['jobId']}")

JavaScript Example

JavaScript (fetch)

// Single email validation
const validateEmail = async (email) => {
  const res = await fetch('https://tempmailblocker.com/api/v1/validate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-mails-api-key': 'your_api_key'
    },
    body: JSON.stringify({ email })
  });

  if (!res.ok) throw new Error('Request failed');
  return res.json();
};

validateEmail('test@example.com')
  .then(result => {
    console.log('Valid:', result.deliverable);
    console.log('Risk:', result.risk);
  })
  .catch(console.error);

cURL Example

cURL

# Single email validation
curl -X POST https://tempmailblocker.com/api/v1/validate \
  -H "Content-Type: application/json" \
  -H "x-mails-api-key: YOUR_API_KEY" \
  -d '{ "email": "test@example.com" }'

# Bulk validation
curl -X POST https://tempmailblocker.com/api/v1/batch \
  -H "Content-Type: application/json" \
  -H "x-mails-api-key: YOUR_API_KEY" \
  -d '{ "emails": ["user1@example.com","user2@test.com"] }'

Go Example

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
)

func main() {
  body := map[string]string{"email": "test@example.com"}
  b, _ := json.Marshal(body)

  req, _ := http.NewRequest("POST", "https://tempmailblocker.com/api/v1/validate", bytes.NewBuffer(b))
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("x-mails-api-key", "YOUR_API_KEY")

  resp, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer resp.Body.Close()

  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}

Rust Example

Rust (reqwest)

use reqwest::blocking::Client;
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let res = client
        .post("https://tempmailblocker.com/api/v1/validate")
        .header("Content-Type", "application/json")
        .header("x-mails-api-key", "YOUR_API_KEY")
        .json(&json!({ "email": "test@example.com" }))
        .send()?;

    let text = res.text()?;
    println!("{}", text);
    Ok(())
}

PHP Example

PHP

<?php
$ch = curl_init("https://tempmailblocker.com/api/v1/validate");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Content-Type: application/json",
  "x-mails-api-key: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["email" => "test@example.com"]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Dart/Flutter Example

Dart (using http package)

import 'package:http/http.dart' as http;
import 'dart:convert';

Future<void> main() async {
  // Single email validation
  final url = Uri.parse('https://tempmailblocker.com/api/v1/validate');
  final body = jsonEncode({'email': 'test@example.com'});
  
  final response = await http.post(
    url,
    headers: {
      'x-mails-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: body,
  );
  
  if (response.statusCode == 200) {
    final data = jsonDecode(response.body);
    print('Valid: ${data['isValid']}');
    print('Score: ${data['score']}');
  } else {
    print('Error: ${response.statusCode}');
  }
  
  // Bulk validation
  final bulkUrl = Uri.parse('https://tempmailblocker.com/api/v1/batch');
  final bulkBody = jsonEncode({
    'emails': ['user1@example.com', 'user2@test.com']
  });
  
  final bulkResponse = await http.post(
    bulkUrl,
    headers: {
      'x-mails-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: bulkBody,
  );
  
  final job = jsonDecode(bulkResponse.body);
  print('Job ID: ${job['id']}');
}

Troubleshooting

Authentication Errors

Ensure your API key is sent as x-mails-api-key.

Rate Limiting

Free plans allow up to 60 requests/min. Upgrade for higher throughput.

Bulk Jobs

Always check job status before fetching results, or use the SDK's waitForJobCompletion helper.