Home / Docs / Code Examples

Code Examples

Copy-paste integration examples for every major language. Each includes request, response, and error handling.

Check Email

GET /check

Check if an email address is from a disposable/temporary email provider.

📤 Request
curl -X GET "https://tempmailchecker.com/check?email=test@mailinator.com" \
  -H "X-API-Key: your_api_key_here"
📥 Success Response (200)
{
  "temp": true,
  "email": "test@mailinator.com",
  "domain": "mailinator.com"
}
⚠️ Error Response (401 / 429)
// 401 Unauthorized
{ "error": "Invalid API key" }

// 429 Rate Limited
{ "error": "Daily limit exceeded", "limit": 100, "reset": "2025-11-28T00:00:00Z" }

Check Usage

GET /usage

Get your current API usage and remaining quota for today.

📤 Request
curl -X GET "https://tempmailchecker.com/usage" \
  -H "X-API-Key: your_api_key_here"
📥 Success Response (200)
{
  "used": 42,
  "limit": 100,
  "remaining": 58,
  "reset": "2025-11-28T00:00:00Z"
}
🔄

Real-Life Integration: Signup Flow

Here's how to integrate the API into a typical signup validation script:

🛡️ Bash Script: Validate Email on Signup
#!/bin/bash
# validate_signup.sh - Check email before allowing registration

API_KEY="your_api_key_here"
EMAIL="$1"

# Call TempMailChecker API
RESPONSE=$(curl -s -X GET "https://tempmailchecker.com/check?email=$EMAIL" \
  -H "X-API-Key: $API_KEY")

# Parse the response
IS_TEMP=$(echo $RESPONSE | grep -o '"temp":\s*true')

if [ -n "$IS_TEMP" ]; then
  echo "❌ BLOCKED: $EMAIL is a disposable email"
  echo "→ Signup rejected. Please use a permanent email address."
  exit 1
else
  echo "✅ ALLOWED: $EMAIL is a valid email"
  echo "→ Proceeding with registration..."
  # Continue with your signup logic here
  exit 0
fi
▶️ Example Output
# Disposable email detected:
$ ./validate_signup.sh test@mailinator.com
❌ BLOCKED: test@mailinator.com is a disposable email
→ Signup rejected. Please use a permanent email address.

# Legitimate email allowed:
$ ./validate_signup.sh john@company.com
✅ ALLOWED: john@company.com is a valid email
→ Proceeding with registration...

Check Email

GET /check

Check if an email address is from a disposable/temporary email provider.

📤 Request
async function checkEmail(email) {
  const response = await fetch(
    `https://tempmailchecker.com/check?email=${encodeURIComponent(email)}`,
    {
      headers: {
        'X-API-Key': 'your_api_key_here'
      }
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error || 'API request failed');
  }

  return await response.json();
}

// Usage
try {
  const result = await checkEmail('test@mailinator.com');
  
  if (result.temp) {
    console.log('❌ Disposable email detected!');
  } else {
    console.log('✅ Valid email address');
  }
} catch (error) {
  console.error('Error:', error.message);
}
📥 Success Response
{ "temp": true, "email": "test@mailinator.com", "domain": "mailinator.com" }

Check Usage

GET /usage

Get your current API usage and remaining quota for today.

📤 Request
async function getUsage() {
  const response = await fetch(
    'https://tempmailchecker.com/usage',
    {
      headers: {
        'X-API-Key': 'your_api_key_here'
      }
    }
  );

  if (!response.ok) {
    throw new Error('Failed to fetch usage');
  }

  return await response.json();
}

// Usage
const usage = await getUsage();
console.log(`Used: ${usage.used}/${usage.limit}`);
🔄

Real-Life Integration: Signup Form

Complete signup form validation with user feedback:

🛡️ Frontend: Validate Before Submit
async function handleSignup(event) {
  event.preventDefault();
  
  const email = document.getElementById('email').value;
  const errorDiv = document.getElementById('email-error');
  const submitBtn = document.getElementById('submit-btn');
  
  // Show loading state
  submitBtn.disabled = true;
  submitBtn.textContent = 'Checking email...';
  
  try {
    // Check if email is disposable
    const result = await checkEmail(email);
    
    if (result.temp) {
      // ❌ BLOCKED: Disposable email detected
      errorDiv.textContent = 'Please use a permanent email address. Disposable emails are not allowed.';
      errorDiv.style.display = 'block';
      submitBtn.disabled = false;
      submitBtn.textContent = 'Sign Up';
      return;
    }
    
    // ✅ ALLOWED: Proceed with registration
    errorDiv.style.display = 'none';
    submitBtn.textContent = 'Creating account...';
    
    // Submit to your backend
    await createAccount(email);
    
  } catch (error) {
    errorDiv.textContent = 'Error validating email. Please try again.';
    errorDiv.style.display = 'block';
  }
  
  submitBtn.disabled = false;
  submitBtn.textContent = 'Sign Up';
}

Check Email

GET /check

Check if an email address is from a disposable/temporary email provider.

📤 Request (using axios)
const axios = require('axios');

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://tempmailchecker.com';

async function checkEmail(email) {
  try {
    const response = await axios.get(`${BASE_URL}/check`, {
      params: { email },
      headers: { 'X-API-Key': API_KEY }
    });
    
    return response.data;
  } catch (error) {
    if (error.response) {
      // API returned an error response
      const { status, data } = error.response;
      
      if (status === 401) {
        throw new Error('Invalid API key');
      } else if (status === 429) {
        throw new Error(`Rate limited. Resets at ${data.reset}`);
      }
      throw new Error(data.error || 'Unknown error');
    }
    throw error;
  }
}

// Usage
(async () => {
  const result = await checkEmail('test@mailinator.com');
  
  if (result.temp) {
    console.log('❌ Blocked: Disposable email');
  } else {
    console.log('✅ Allowed: Real email');
  }
})();

Check Usage

GET /usage
📤 Request
async function getUsage() {
  const response = await axios.get(`${BASE_URL}/usage`, {
    headers: { 'X-API-Key': API_KEY }
  });
  
  return response.data;
}

const usage = await getUsage();
console.log(`Remaining: ${usage.remaining} requests`);
🔄

Real-Life Integration: Express.js Middleware

Protect your signup endpoint with validation middleware:

🛡️ Express Middleware
const express = require('express');
const axios = require('axios');
const app = express();

// Middleware: Block disposable emails
async function blockDisposableEmails(req, res, next) {
  const { email } = req.body;
  
  try {
    const response = await axios.get('https://tempmailchecker.com/check', {
      params: { email },
      headers: { 'X-API-Key': process.env.TEMPMAIL_API_KEY }
    });
    
    if (response.data.temp) {
      // ❌ BLOCKED: Disposable email
      return res.status(400).json({
        error: 'Disposable emails are not allowed',
        code: 'DISPOSABLE_EMAIL'
      });
    }
    
    // ✅ ALLOWED: Continue to signup
    next();
  } catch (error) {
    // On API error, allow signup (fail open)
    console.error('TempMailChecker error:', error.message);
    next();
  }
}

// Apply to signup route
app.post('/api/signup', blockDisposableEmails, async (req, res) => {
  // Email already validated - create user
  const user = await createUser(req.body);
  res.json({ success: true, user });
});

Check Email

GET /check

Check if an email address is from a disposable/temporary email provider.

📤 Request (using requests)
import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://tempmailchecker.com"

def check_email(email: str) -> dict:
    """Check if email is disposable."""
    response = requests.get(
        f"{BASE_URL}/check",
        params={"email": email},
        headers={"X-API-Key": API_KEY}
    )
    
    if response.status_code == 401:
        raise Exception("Invalid API key")
    elif response.status_code == 429:
        data = response.json()
        raise Exception(f"Rate limited. Resets at {data['reset']}")
    
    response.raise_for_status()
    return response.json()

# Usage
try:
    result = check_email("test@mailinator.com")
    
    if result["temp"]:
        print("❌ Disposable email detected!")
    else:
        print("✅ Valid email address")
        
except Exception as e:
    print(f"Error: {e}")
📥 Success Response
{"temp": True, "email": "test@mailinator.com", "domain": "mailinator.com"}

Check Usage

GET /usage
📤 Request
def get_usage() -> dict:
    """Get current API usage."""
    response = requests.get(
        f"{BASE_URL}/usage",
        headers={"X-API-Key": API_KEY}
    )
    response.raise_for_status()
    return response.json()

usage = get_usage()
print(f"Used: {usage['used']}/{usage['limit']}")
🔄

Real-Life Integration: Flask/Django Signup

Validate emails in your Python web framework:

🛡️ Flask Example
from flask import Flask, request, jsonify
import requests

app = Flask(__name__)
API_KEY = "your_api_key_here"

def is_disposable_email(email: str) -> bool:
    """Check if email is from a disposable provider."""
    try:
        response = requests.get(
            "https://tempmailchecker.com/check",
            params={"email": email},
            headers={"X-API-Key": API_KEY},
            timeout=5
        )
        return response.json().get("temp", False)
    except:
        return False  # Fail open on API errors

@app.route("/signup", methods=["POST"])
def signup():
    email = request.json.get("email")
    
    if is_disposable_email(email):
        # ❌ BLOCKED: Disposable email
        return jsonify({
            "error": "Please use a permanent email address",
            "code": "DISPOSABLE_EMAIL"
        }), 400
    
    # ✅ ALLOWED: Create user account
    user = create_user(email, request.json.get("password"))
    return jsonify({"success": True, "user_id": user.id})

Check Email

GET /check

Check if an email address is from a disposable/temporary email provider.

📤 Request (using cURL)
<?php

$apiKey = 'your_api_key_here';
$baseUrl = 'https://tempmailchecker.com';

function checkEmail($email) {
    global $apiKey, $baseUrl;
    
    $url = $baseUrl . '/check?email=' . urlencode($email);
    
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . $apiKey
        ]
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 401) {
        throw new Exception('Invalid API key');
    } elseif ($httpCode === 429) {
        $data = json_decode($response, true);
        throw new Exception('Rate limited. Resets at ' . $data['reset']);
    }
    
    return json_decode($response, true);
}

// Usage
try {
    $result = checkEmail('test@mailinator.com');
    
    if ($result['temp']) {
        echo "❌ Disposable email detected!\n";
    } else {
        echo "✅ Valid email address\n";
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

Check Usage

GET /usage
📤 Request
function getUsage() {
    global $apiKey, $baseUrl;
    
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $baseUrl . '/usage',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['X-API-Key: ' . $apiKey]
    ]);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

$usage = getUsage();
echo "Remaining: {$usage['remaining']} requests\n";
🔄

Real-Life Integration: Laravel/WordPress Signup

Validate emails in your PHP application:

🛡️ PHP Signup Handler
<?php

class SignupController {
    private $apiKey = 'your_api_key_here';
    
    public function handleSignup($email, $password) {
        // Step 1: Check if email is disposable
        if ($this->isDisposableEmail($email)) {
            // ❌ BLOCKED: Disposable email
            return [
                'success' => false,
                'error' => 'Disposable emails are not allowed. Please use a permanent email.',
                'code' => 'DISPOSABLE_EMAIL'
            ];
        }
        
        // ✅ ALLOWED: Create user account
        $user = $this->createUser($email, $password);
        
        return [
            'success' => true,
            'message' => 'Account created successfully!',
            'user_id' => $user['id']
        ];
    }
    
    private function isDisposableEmail($email) {
        try {
            $result = checkEmail($email);
            return $result['temp'] === true;
        } catch (Exception $e) {
            return false; // Fail open on API errors
        }
    }
}

// Usage
$controller = new SignupController();
$result = $controller->handleSignup($_POST['email'], $_POST['password']);
echo json_encode($result);
?>

Check Email

GET /check

Check if an email address is from a disposable/temporary email provider.

📤 Request
package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
)

const (
    apiKey  = "your_api_key_here"
    baseURL = "https://tempmailchecker.com"
)

type CheckResponse struct {
    Temp   bool   `json:"temp"`
    Email  string `json:"email"`
    Domain string `json:"domain"`
}

type ErrorResponse struct {
    Error string `json:"error"`
    Reset string `json:"reset,omitempty"`
}

func checkEmail(email string) (*CheckResponse, error) {
    reqURL := fmt.Sprintf("%s/check?email=%s", baseURL, url.QueryEscape(email))
    
    req, _ := http.NewRequest("GET", reqURL, nil)
    req.Header.Set("X-API-Key", apiKey)
    
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    if resp.StatusCode == 401 {
        return nil, fmt.Errorf("invalid API key")
    } else if resp.StatusCode == 429 {
        var errResp ErrorResponse
        json.NewDecoder(resp.Body).Decode(&errResp)
        return nil, fmt.Errorf("rate limited, resets at %s", errResp.Reset)
    }
    
    var result CheckResponse
    json.NewDecoder(resp.Body).Decode(&result)
    return &result, nil
}

func main() {
    result, err := checkEmail("test@mailinator.com")
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    
    if result.Temp {
        fmt.Println("❌ Disposable email detected!")
    } else {
        fmt.Println("✅ Valid email address")
    }
}

Check Usage

GET /usage
📤 Request
type UsageResponse struct {
    Used      int    `json:"used"`
    Limit     int    `json:"limit"`
    Remaining int    `json:"remaining"`
    Reset     string `json:"reset"`
}

func getUsage() (*UsageResponse, error) {
    req, _ := http.NewRequest("GET", baseURL+"/usage", nil)
    req.Header.Set("X-API-Key", apiKey)
    
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var result UsageResponse
    json.NewDecoder(resp.Body).Decode(&result)
    return &result, nil
}

// Usage: fmt.Printf("Remaining: %d requests\n", usage.Remaining)
🔄

Real-Life Integration: HTTP Handler

Protect your Go API signup endpoint:

🛡️ Go HTTP Handler
package main

import (
    "encoding/json"
    "net/http"
)

type SignupRequest struct {
    Email    string `json:"email"`
    Password string `json:"password"`
}

type SignupResponse struct {
    Success bool   `json:"success"`
    Message string `json:"message,omitempty"`
    Error   string `json:"error,omitempty"`
    Code    string `json:"code,omitempty"`
}

func signupHandler(w http.ResponseWriter, r *http.Request) {
    var req SignupRequest
    json.NewDecoder(r.Body).Decode(&req)
    
    // Check if email is disposable
    result, err := checkEmail(req.Email)
    if err == nil && result.Temp {
        // ❌ BLOCKED: Disposable email
        w.WriteHeader(http.StatusBadRequest)
        json.NewEncoder(w).Encode(SignupResponse{
            Success: false,
            Error:   "Disposable emails are not allowed",
            Code:    "DISPOSABLE_EMAIL",
        })
        return
    }
    
    // ✅ ALLOWED: Create user
    user := createUser(req.Email, req.Password)
    json.NewEncoder(w).Encode(SignupResponse{
        Success: true,
        Message: fmt.Sprintf("Welcome! User %d created.", user.ID),
    })
}

func main() {
    http.HandleFunc("/api/signup", signupHandler)
    http.ListenAndServe(":8080", nil)
}

Check Email

GET /check

Check if an email address is from a disposable/temporary email provider.

📤 Request
require 'net/http'
require 'json'
require 'uri'

API_KEY = 'your_api_key_here'
BASE_URL = 'https://tempmailchecker.com'

def check_email(email)
  uri = URI("#{BASE_URL}/check?email=#{URI.encode_www_form_component(email)}")
  
  request = Net::HTTP::Get.new(uri)
  request['X-API-Key'] = API_KEY
  
  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end
  
  case response.code.to_i
  when 401
    raise 'Invalid API key'
  when 429
    data = JSON.parse(response.body)
    raise "Rate limited. Resets at #{data['reset']}"
  end
  
  JSON.parse(response.body)
end

# Usage
begin
  result = check_email('test@mailinator.com')
  
  if result['temp']
    puts '❌ Disposable email detected!'
  else
    puts '✅ Valid email address'
  end
rescue => e
  puts "Error: #{e.message}"
end

Check Usage

GET /usage
📤 Request
def get_usage
  uri = URI("#{BASE_URL}/usage")
  
  request = Net::HTTP::Get.new(uri)
  request['X-API-Key'] = API_KEY
  
  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end
  
  JSON.parse(response.body)
end

usage = get_usage
puts "Remaining: #{usage['remaining']} requests"
🔄

Real-Life Integration: Rails Controller

Protect your Ruby on Rails signup endpoint:

🛡️ Rails Controller
class UsersController < ApplicationController
  def create
    email = params[:email]
    
    # Check if email is disposable
    if disposable_email?(email)
      # ❌ BLOCKED: Disposable email
      render json: {
        success: false,
        error: 'Disposable emails are not allowed. Please use a permanent email.',
        code: 'DISPOSABLE_EMAIL'
      }, status: 400
      return
    end
    
    # ✅ ALLOWED: Create user
    user = User.create!(
      email: email,
      password: params[:password]
    )
    
    render json: {
      success: true,
      message: 'Account created successfully!',
      user_id: user.id
    }
  end
  
  private
  
  def disposable_email?(email)
    result = check_email(email)
    result['temp'] == true
  rescue
    false # Fail open on API errors
  end
end

Ready to integrate?

Get your free API key and start blocking disposable emails in under 60 seconds.

🚀 Get Free API Key