API - BulkMail Single Email Verification API

A high-performance, real-time email verification service that validates individual email addresses instantly. Perfect for signup forms, contact validation, and real-time email quality checking.

🚀 Quick Start

Basic Email Verification

GET https://api.bulkmailapp.co.za/single/?api=YOUR_API_KEY&[email protected]

Enhanced Verification with Data Enrichment

GET https://api.bulkmailapp.co.za/single/?api=YOUR_API_KEY&[email protected]&photo=true&append=true&gsuite=true

Human-Readable HTML View

GET https://api.bulkmailapp.co.za/single/?api=YOUR_API_KEY&[email protected]&format=html

📋 API Parameters

Required Parameters

Optional Parameters

📊 Response Formats

JSON Response (Default)

Perfect for programmatic integration and API clients.

Successful Verification

{
  "bulkmailverify": {
    "email": "[email protected]",
    "code": "5",
    "role": "false",
    "free_email": "true",
    "result": "Safe to Send",
    "reason": "Deliverable",
    "send_transactional": "1",
    "did_you_mean": ""
  },
  "success": "1",
  "balance": "178493.8"
}

Error Response

{
  "bulkmailverify": {
    "error": "Wrong API",
    "code": "0"
  },
  "success": "0"
}

HTML Response (Human-Readable)

Add &format=html to get a beautiful, responsive web interface showing verification results with:

• Color-coded result badges
• Detailed breakdown of email properties
• Account balance display
• Professional BulkMail branding
• Mobile-responsive design

🔍 Response Field Explanations

Core Verification Fields

Email Analysis Fields

🎯 Use Cases & Examples

1. Signup Form Validation

Use Case: Validate emails during user registration to prevent fake signups.

Example Request:

GET /single/?api=YOUR_API_KEY&[email protected]

Decision Logic:

// Accept if send_transactional is 1
if (response.bulkmailverify.send_transactional === "1") {
    // Accept signup
} else {
    // Show error or request different email
}

2. Contact Form Validation

Use Case: Real-time validation for contact forms and newsletter signups.

Example Request:

GET /single/?api=YOUR_API_KEY&[email protected]&gsuite=true

Expected Response:

{
  "bulkmailverify": {
    "email": "[email protected]",
    "result": "Safe to Send",
    "reason": "Deliverable",
    "role": "true",
    "free_email": "false",
    "send_transactional": "1"
  },
  "success": "1",
  "balance": "178493.8"
}

3. Data Enrichment for CRM

Use Case: Enrich contact data with profile photos and names.

Example Request:

GET /single/?api=YOUR_API_KEY&[email protected]&photo=true&append=true

Enhanced Response (includes additional fields when data found):

{
  "bulkmailverify": {
    "email": "[email protected]",
    "result": "Safe to Send",
    "reason": "Deliverable",
    "send_transactional": "1",
    "full_name": "John Doe",
    "avatar": "https://example.com/photo.jpg",
    "photo": "https://example.com/profile.jpg"
  },
  "success": "1",
  "balance": "178491.8"
}

🚨 Error Handling

Common Error Responses

Invalid API Key (401)

{
  "bulkmailverify": {
    "error": "Wrong API",
    "code": "0"
  },
  "success": "0"
}

Insufficient Credits (402)

{
  "bulkmailverify": {
    "error": "Credits Low",
    "code": "0"
  },
  "success": "0"
}

Rate Limit Exceeded (429)

{
  "bulkmailverify": {
    "error": "Maximum concurrent calls reached",
    "code": "0"
  },
  "success": "0"
}

Invalid Email Format (400)

{
  "bulkmailverify": {
    "error": "Invalid email address",
    "code": "0"
  },
  "success": "0"
}

💻 Code Examples

JavaScript (Fetch API)

async function verifyEmail(apiKey, email) {
    const url = `https://api.bulkmailapp.co.za/single/?api=${apiKey}&email=${encodeURIComponent(email)}`;
    
    try {
        const response = await fetch(url);
        const data = await response.json();
        
        if (data.success === "1") {
            console.log('Verification Result:', data.bulkmailverify.result);
            console.log('Safe for Transactional:', data.bulkmailverify.send_transactional === "1");
            return data.bulkmailverify;
        } else {
            console.error('Verification Error:', data.bulkmailverify.error);
            return null;
        }
    } catch (error) {
        console.error('API Error:', error);
        return null;
    }
}

// Usage
verifyEmail('YOUR_API_KEY', '[email protected]');

PHP (Modern Approach)

<?php
function verifyEmail($apiKey, $email, $options = []) {
    $params = [
        'api' => $apiKey,
        'email' => $email
    ];
    
    // Add optional parameters
    if (isset($options['photo']) && $options['photo']) {
        $params['photo'] = 'true';
    }
    if (isset($options['append']) && $options['append']) {
        $params['append'] = 'true';
    }
    if (isset($options['gsuite']) && $options['gsuite']) {
        $params['gsuite'] = 'true';
    }
    
    $url = 'https://api.bulkmailapp.co.za/single/?' . http_build_query($params);
    
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_SSL_VERIFYPEER => true,
        CURLOPT_USERAGENT => 'YourApp/1.0'
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($response === false || $httpCode !== 200) {
        return ['error' => 'API request failed'];
    }
    
    return json_decode($response, true);
}

// Usage Examples
$result = verifyEmail('YOUR_API_KEY', '[email protected]');
$enriched = verifyEmail('YOUR_API_KEY', '[email protected]', [
    'photo' => true,
    'append' => true,
    'gsuite' => true
]);

if ($result['success'] === '1') {
    echo "Result: " . $result['bulkmailverify']['result'];
    echo "Safe for signup: " . ($result['bulkmailverify']['send_transactional'] === '1' ? 'Yes' : 'No');
}
?>

Python (Requests Library)

import requests
import urllib.parse

def verify_email(api_key, email, photo=False, append=False, gsuite=False):
    """
    Verify a single email address using BulkMail API
    
    Args:
        api_key (str): Your API key
        email (str): Email address to verify
        photo (bool): Include profile photo (+0.2 credits)
        append (bool): Include data enrichment (+2.0 credits)
        gsuite (bool): Enhanced G Suite detection
    
    Returns:
        dict: Verification results or error information
    """
    params = {
        'api': api_key,
        'email': email
    }
    
    if photo:
        params['photo'] = 'true'
    if append:
        params['append'] = 'true'
    if gsuite:
        params['gsuite'] = 'true'
    
    try:
        response = requests.get(
            'https://api.bulkmailapp.co.za/single/',
            params=params,
            timeout=15
        )
        
        if response.status_code == 200:
            return response.json()
        else:
            return {'error': f'HTTP {response.status_code}: {response.text}'}
            
    except requests.exceptions.RequestException as e:
        return {'error': f'Request failed: {str(e)}'}

# Usage Examples
result = verify_email('YOUR_API_KEY', '[email protected]')

if result.get('success') == '1':
    verification = result['bulkmailverify']
    print(f"Email: {verification['email']}")
    print(f"Result: {verification['result']}")
    print(f"Reason: {verification['reason']}")
    print(f"Safe for transactional: {'Yes' if verification['send_transactional'] == '1' else 'No'}")
else:
    print(f"Error: {result.get('bulkmailverify', {}).get('error', 'Unknown error')}")

Node.js (Async/Await)

const axios = require('axios');

class BulkMailVerifier {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.baseUrl = 'https://api.bulkmailapp.co.za/single/';
    }
    
    async verifyEmail(email, options = {}) {
        const params = {
            api: this.apiKey,
            email: email
        };
        
        // Add optional parameters
        if (options.photo) params.photo = 'true';
        if (options.append) params.append = 'true';
        if (options.gsuite) params.gsuite = 'true';
        if (options.format) params.format = options.format;
        
        try {
            const response = await axios.get(this.baseUrl, { 
                params,
                timeout: 15000 
            });
            
            return response.data;
        } catch (error) {
            if (error.response) {
                return {
                    error: `HTTP ${error.response.status}: ${error.response.statusText}`,
                    data: error.response.data
                };
            } else {
                return { error: `Request failed: ${error.message}` };
            }
        }
    }
    
    async isValidForSignup(email) {
        const result = await this.verifyEmail(email);
        
        if (result.success === '1' && result.bulkmailverify) {
            // Use send_transactional flag for signup validation
            return result.bulkmailverify.send_transactional === '1';
        }
        
        return false;
    }
}

// Usage
const verifier = new BulkMailVerifier('YOUR_API_KEY');

// Basic verification
verifier.verifyEmail('[email protected]')
    .then(result => {
        if (result.success === '1') {
            console.log('Verification Result:', result.bulkmailverify.result);
            console.log('Balance Remaining:', result.balance);
        } else {
            console.error('Error:', result.bulkmailverify?.error || 'Unknown error');
        }
    });

// Signup validation
verifier.isValidForSignup('[email protected]')
    .then(isValid => {
        console.log('Safe for signup:', isValid);
    });

🎯 Result Interpretation Guide

Result Status Values

Signup Form Best Practices

For signup forms, accept these statuses to avoid rejecting legitimate users:

• ✅ Safe to Send - Perfect emails
• ✅ Unknown - May be legitimate new domains
• ⚠️ Risky - Use with caution (depending on your risk tolerance)
• ❌ Invalid - Definitely reject

Simplified Approach: Use the send_transactional field:

if (result.bulkmailverify.send_transactional === "1") {
    // Safe to accept for signup
    acceptUser();
} else {
    // Request different email or show warning
    requestDifferentEmail();
}

Email Type Analysis

Role-Based Emails (role field)

• true: emails like [email protected], [email protected]
• false: personal emails like [email protected]
• Marketing tip: Role emails often have multiple recipients

Free Email Providers (free_email field)

• true: Gmail, Yahoo, Hotmail, etc.
• false: Corporate/business domains
• Marketing tip: Free emails may have different engagement patterns

💡 Advanced Usage Examples

WordPress Plugin Integration

// WordPress hook for user registration
add_filter('registration_errors', function($errors, $sanitized_user_login, $user_email) {
    $result = verifyEmail(get_option('bulkmail_api_key'), $user_email);
    
    if ($result['success'] === '1') {
        $verification = $result['bulkmailverify'];
        
        if ($verification['send_transactional'] !== '1') {
            $errors->add('email_invalid', 
                'Please provide a valid email address. ' . 
                ($verification['did_you_mean'] ? 
                    'Did you mean: ' . $verification['did_you_mean'] . '?' : '')
            );
        }
    }
    
    return $errors;
}, 10, 3);

React Component Integration

import React, { useState } from 'react';

const EmailVerificationInput = ({ apiKey, onValidation }) => {
    const [email, setEmail] = useState('');
    const [verification, setVerification] = useState(null);
    const [loading, setLoading] = useState(false);
    
    const verifyEmail = async (emailValue) => {
        setLoading(true);
        
        try {
            const response = await fetch(
                `https://api.bulkmailapp.co.za/single/?api=${apiKey}&email=${encodeURIComponent(emailValue)}`
            );
            const data = await response.json();
            
            setVerification(data);
            onValidation(data);
        } catch (error) {
            console.error('Verification failed:', error);
        } finally {
            setLoading(false);
        }
    };
    
    const handleBlur = () => {
        if (email && email.includes('@')) {
            verifyEmail(email);
        }
    };
    
    const getStatusColor = () => {
        if (!verification?.bulkmailverify) return '';
        
        switch (verification.bulkmailverify.result) {
            case 'Safe to Send': return 'text-success';
            case 'Invalid': return 'text-danger';
            case 'Risky': return 'text-warning';
            default: return 'text-secondary';
        }
    };
    
    return (
        <div className="form-group">
            <label>Email Address</label>
            <input
                type="email"
                className={`form-control ${getStatusColor()}`}
                value={email}
                onChange={(e) => setEmail(e.target.value)}
                onBlur={handleBlur}
                placeholder="Enter email address"
            />
            
            {loading && <small className="text-muted">Verifying...</small>}
            
            {verification?.bulkmailverify && (
                <small className={getStatusColor()}>
                    {verification.bulkmailverify.result} - {verification.bulkmailverify.reason}
                    {verification.bulkmailverify.did_you_mean && (
                        <span> (Did you mean: {verification.bulkmailverify.did_you_mean}?)</span>
                    )}
                </small>
            )}
        </div>
    );
};

🔧 Cost Calculation

Base Verification

• Standard verification: 1.0 credit per email
• Response time: ~500ms average

Optional Enhancements

• Photo enrichment (&photo=true): +0.2 credits
• Data enrichment (&append=true): +2.0 credits
• G Suite detection (&gsuite=true): No additional cost

Example Cost Scenarios

Basic verification: 1.0 credit
With photo: 1.2 credits  
With data enrichment: 3.0 credits
Full enrichment (photo + append): 3.2 credits

⚡ Performance & Limits

Response Times

• Basic verification: 300-800ms
• With photo: 500-1200ms
• With data enrichment: 800-1500ms

Rate Limits

• Default: 100 requests per minute
• Burst: Up to 10 concurrent requests
• Contact support for higher limits

🔗 Integration Tips

Best Practices

1. Cache results - Don't verify the same email repeatedly
2. Handle timeouts - Set appropriate timeout values (15s recommended)
3. Validate locally first - Basic format checking before API calls
4. Use send_transactional - Simplest way to determine acceptance
5. Handle rate limits - Implement exponential backoff for 429 errors

Security Considerations

• Protect API keys - Never expose in client-side code
• Use HTTPS - Always use secure connections
• Input validation - Validate email format before API calls
• Error handling - Don't expose API errors to end users

📱 Testing & Development

Development Endpoints

• JSON API: https://api.bulkmailapp.co.za/single/?api=KEY&email=EMAIL
• HTML View: https://api.bulkmailapp.co.za/single/?api=KEY&email=EMAIL&format=html

Test Email Addresses

Use these for development testing:

• Valid email: [email protected]
• Invalid email: [email protected]
• Role email: [email protected]
• Typo email: [email protected] (should suggest gmail.com)

📞 Support & Documentation

• Main Documentation: https://bulkmail.co.za/resources/articles/single-email-validation
• API Reference: This document
• Support: Contact BulkMail support team
• Code Examples: Available in multiple programming languages above

Service: BulkMail Single Email Verification API
Version: 2025.1
Last Updated: September 2025
Endpoint: https://api.bulkmailapp.co.za/single/
Response Time: ~500ms average
Format Support: JSON (default) + HTML view