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);
  }
}

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;

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.