API Documentation

// Bearer Token Authentication (Recommended)
Authorization: Bearer YOUR_API_KEY_HERE

// Alternative: X-API-Key Header
X-API-Key: YOUR_API_KEY_HERE

# Python with requests library
import requests
import json
from typing import Optional, Dict, Any

class VirtualBlacklistAPI:
    def __init__(self, api_key: str, base_url: str = "https://virtualblacklist.com"):
        self.api_key = api_key
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
    
    def check_email(self, email: str) -> Optional[Dict[str, Any]]:
        """Check if an email is blacklisted"""
        url = f"{self.base_url}/api/check_email"
        data = {"email": email}
        
        try:
            response = requests.post(url, headers=self.headers, json=data)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f"API Error: {e}")
            return None
    
    def batch_check_emails(self, emails: list) -> list:
        """Check multiple emails (implement rate limiting)
        results = []
        for email in emails:
            result = self.check_email(email)
            results.append(result)
            time.sleep(0.1)  # Rate limiting
        return results

# Usage
api = VirtualBlacklistAPI("YOUR_API_KEY")
result = api.check_email("[email protected]")

if result and result["is_blacklisted"]:
    print(f"⚠️ {result['email']} is blacklisted!")
    print(f"Risk Level: {result['blacklist_info']['risk_level']}")
else:
    print(f"✅ {result['email']} appears safe")

// PHP with cURL
class VirtualBlacklistAPI {
    private $apiKey;
    private $baseUrl;
    
    public function __construct($apiKey, $baseUrl = 'https://virtualblacklist.com') {
        $this->apiKey = $apiKey;
        $this->baseUrl = $baseUrl;
    }
    
    public function checkEmail($email) {
        $url = $this->baseUrl . '/api/check_email';
        $data = json_encode(['email' => $email]);
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer ' . $this->apiKey,
            'Content-Type: application/json'
        ]);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 30);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($httpCode === 200) {
            return json_decode($response, true);
        }
        
        return null;
    }
    
    public function batchCheckEmails($emails) {
        $results = [];
        foreach ($emails as $email) {
            $results[] = $this->checkEmail($email);
            usleep(100000); // Rate limiting (0.1 second)
        }
        return $results;
    }
}

// Usage
$api = new VirtualBlacklistAPI('YOUR_API_KEY');
$result = $api->checkEmail('[email protected]');

if ($result && $result['is_blacklisted']) {
    echo "⚠️ {$result['email']} is blacklisted!";
    echo "Risk Level: " . $result['blacklist_info']['risk_level'];
} else {
    echo "✅ {$result['email']} appears safe";
}

// Node.js with fetch
class VirtualBlacklistAPI {
    constructor(apiKey, baseUrl = 'https://virtualblacklist.com') {
        this.apiKey = apiKey;
        this.baseUrl = baseUrl;
    }
    
    async checkEmail(email) {
        const url = `${this.baseUrl}/api/check_email`;
        const headers = {
            'Authorization': `Bearer ${this.apiKey}`,
            'Content-Type': 'application/json'
        };
        
        try {
            const response = await fetch(url, {
                method: 'POST',
                headers,
                body: JSON.stringify({ email })
            });
            
            if (!response.ok) {
                throw new Error(`HTTP error! status: ${response.status}`);
            }
            
            return await response.json();
        } catch (error) {
            console.error('API Error:', error);
            return null;
        }
    }
    
    async batchCheckEmails(emails) {
        const results = [];
        for (const email of emails) {
            const result = await this.checkEmail(email);
            results.push(result);
            await new Promise(resolve => setTimeout(resolve, 100)); // Rate limiting
        }
        return results;
    }
// Usage
const api = new VirtualBlacklistAPI('YOUR_API_KEY');

api.checkEmail('[email protected]')
    .then(result => {
        if (result && result.is_blacklisted) {
            console.log(`⚠️ ${result.email} is blacklisted!`);
            console.log(`Risk Level: ${result.blacklist_info.risk_level}`);
        } else {
            console.log(`✅ ${result.email} appears safe`);
        }
    })
    .catch(error => console.error('Error:', error));

# Basic cURL request
curl -X POST "https://virtualblacklist.com/api/check_email" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

# With verbose output for debugging
curl -v -X POST "https://virtualblacklist.com/api/check_email" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

# Save response to file
curl -X POST "https://virtualblacklist.com/api/check_email" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}' \
  -o response.json

# Set up webhook endpoint in your application
# This allows real-time notifications when new blacklist entries are added

// Express.js webhook endpoint example
app.post('/webhook/blacklist-update', (req, res) => {
    const { email, status, reason, timestamp } = req.body;
    
    // Verify webhook signature (implement security)
    if (!verifyWebhookSignature(req)) {
        return res.status(401).json({ error: 'Invalid signature' });
    }
    
    // Process the blacklist update
    console.log(`New blacklist entry: ${email} - ${status}`);
    
    // Update your local database or trigger alerts
    updateLocalBlacklist(email, status, reason);
    
    res.status(200).json({ received: true });
});

// Configure webhook in VirtualBlacklist dashboard
// Webhook URL: https://yourdomain.com/webhook/blacklist-update