Email Verification with cURL: Test API Requests from the Command Line

Before you write a single line of PHP, Python, or JavaScript, test the API with cURL. It takes five seconds, shows you exactly what the API returns, and eliminates guesswork when you start building your integration. Every developer has cURL available. It ships with macOS, Linux, and Windows 10+, and it runs in any terminal.

This guide shows you how to use cURL with the Bulk Email Checker real-time API for testing, debugging, and quick one-off verifications. You'll see the exact commands, the response format, and practical patterns for batch processing and troubleshooting.

Your First Verification Request

The Bulk Email Checker real-time API uses a simple GET request. You need two parameters: your API key and the email address to verify. Here's the basic command:

curl "https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=test@gmail.com"

Replace YOUR_API_KEY with your actual key from the API documentation dashboard. The response comes back as JSON, printed directly in your terminal.

For a cleaner view, pipe the output through Python's JSON formatter or jq:

# Pretty-print with Python (available on most systems)
curl -s "https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=test@gmail.com" | python3 -m json.tool

# Or with jq (if installed)
curl -s "https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=test@gmail.com" | jq .

Reading the API Response

A typical successful verification response looks like this:

{
    "status": "passed",
    "event": "",
    "email": "test@gmail.com",
    "isDisposable": false,
    "isRoleAccount": false,
    "isFreeService": true,
    "isGibberish": false,
    "emailSuggested": "",
    "mxEnrichment": {
        "mxIp": "142.250.115.27",
        "mxHost": "gmail-smtp-in.l.google.com",
        "mxGeo": "US",
        "mxCity": "Mountain View",
        "mxIsp": "Google LLC"
    }
}

The three fields you'll check most often:

• status - passed (valid), failed (invalid), or unknown (inconclusive, often catch-all domains)
• isDisposable - true if the address uses a temporary/throwaway email service
• event - When status is failed, this tells you exactly why (e.g., mailbox_does_not_exist, domain_does_not_exist)

The mxEnrichment object provides extra intelligence about the mail server: its IP, hostname, geographic location, and ISP. This is useful for understanding where your subscribers' mail is hosted.

Parsing JSON Responses with jq

jq is a command-line JSON processor that lets you extract specific fields from the response. This is especially useful when you only need the status or want to check a specific flag:

# Get just the status
curl -s "https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=test@gmail.com" | jq -r '.status'

# Output: passed

# Check if the email is disposable
curl -s "https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=temp@mailinator.com" | jq '.isDisposable'

# Output: true

# Get the mail server location
curl -s "https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=user@company.com" | jq -r '.mxEnrichment.mxGeo'

# Output: US

# Extract multiple fields at once
curl -s "https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=test@gmail.com" | jq '{status, isDisposable, isRoleAccount}'

# Output:
# {
#   "status": "passed",
#   "isDisposable": false,
#   "isRoleAccount": false
# }

Testing Common Edge Cases

Before building your integration, test how the API handles the scenarios your application will encounter. Here are the key edge cases to verify:

# Test a nonexistent mailbox
curl -s "https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=fakeperson123@gmail.com" | jq '{status, event}'
# Expected: {"status": "failed", "event": "mailbox_does_not_exist"}

# Test a nonexistent domain
curl -s "https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=user@thisdomain-does-not-exist-xyz.com" | jq '{status, event}'
# Expected: {"status": "failed", "event": "domain_does_not_exist"}

# Test a disposable email
curl -s "https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=test@mailinator.com" | jq '{status, isDisposable}'
# Expected: isDisposable will be true

# Test a role-based address
curl -s "https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=info@google.com" | jq '{status, isRoleAccount}'
# Expected: isRoleAccount will be true

# Test invalid syntax
curl -s "https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=not-an-email" | jq '{status, event}'
# Expected: {"status": "failed", "event": "invalid_syntax"}

# Test with timing info
curl -s -w "\nResponse time: %{time_total}s\n" "https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=test@gmail.com" | head -1 | jq .status

Running through these edge cases gives you a clear picture of the response format for each scenario. Use these results to build your application's decision logic: what to do for passed, failed, unknown, disposable, and role-based results.

Batch Verification from a Text File

Need to verify a handful of addresses quickly without uploading to the web interface? Put them in a text file (one per line) and loop through them with a Bash script:

#!/bin/bash
# verify_list.sh - Verify a list of emails from a text file
# Usage: ./verify_list.sh emails.txt YOUR_API_KEY

INPUT_FILE="$1"
API_KEY="$2"

if [ -z "$INPUT_FILE" ] || [ -z "$API_KEY" ]; then
    echo "Usage: $0 <email_file> <api_key>"
    exit 1
fi

echo "email,status,event,disposable,role_account"

while IFS= read -r email; do
    # Skip empty lines
    [ -z "$email" ] && continue

    # Call the API
    response=$(curl -s "https://api.bulkemailchecker.com/real-time/?key=${API_KEY}&email=${email}")

    # Extract fields with jq
    status=$(echo "$response" | jq -r '.status')
    event=$(echo "$response" | jq -r '.event')
    disposable=$(echo "$response" | jq -r '.isDisposable')
    role=$(echo "$response" | jq -r '.isRoleAccount')

    echo "${email},${status},${event},${disposable},${role}"

    # Rate limiting: wait 1 second between requests
    sleep 1
done < "$INPUT_FILE"

Create an emails.txt file with one address per line, then run the script:

chmod +x verify_list.sh
./verify_list.sh emails.txt YOUR_API_KEY > results.csv

The output is CSV format that you can open in Excel or import into your database. The sleep 1 between requests prevents hitting rate limits. For larger lists (hundreds or thousands of addresses), use the bulk verification tool instead, which processes lists in parallel and handles rate limiting automatically.

Debugging Connection and Auth Errors

When a cURL request doesn't return the expected result, add verbose output to see what's happening at the HTTP level:

# Verbose output shows full request/response headers
curl -v "https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=test@gmail.com"

# Check only the HTTP status code
curl -s -o /dev/null -w "%{http_code}" "https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=test@gmail.com"

# Set a timeout (10 seconds)
curl -s --max-time 10 "https://api.bulkemailchecker.com/real-time/?key=YOUR_API_KEY&email=test@gmail.com"

Common issues and their solutions:

Frequently Asked Questions

Do I need to install anything to use cURL?

On macOS and most Linux distributions, cURL is pre-installed. On Windows 10 and later, cURL ships with the OS and is available in Command Prompt and PowerShell. For the JSON parsing examples, you'll also want jq, which you can install via Homebrew (brew install jq), apt (sudo apt install jq), or download from the jq project site.

Is the real-time API the same as the bulk verification tool?

No. The real-time API verifies one address per request and responds in under a second. It's designed for signup forms, single lookups, and quick testing. The bulk verification tool processes entire CSV files with thousands of addresses in parallel. For cURL testing, you'll always use the real-time endpoint.

Can I use cURL in Windows PowerShell?

Yes, but there's a gotcha: PowerShell has a built-in alias curl that maps to Invoke-WebRequest, which is different from real cURL. Use curl.exe (with the .exe) to invoke the actual cURL binary on Windows. Or run the commands in Command Prompt (cmd.exe) where this alias doesn't exist.

How many requests can I make with cURL before hitting rate limits?

Rate limits depend on your plan. The free tier includes a limited number of credits for testing. Paid plans scale based on volume. For cURL testing purposes, individual requests with a 1-second delay between them will stay well within any plan's limits. If you hit a 429 response, wait 60 seconds before retrying.

Should I use cURL in production?

No. cURL is a testing and debugging tool. For production integrations, use a proper HTTP client in your application language (PHP's cURL extension, Python's requests library, Node's axios or fetch). These provide better error handling, connection pooling, retry logic, and async processing that cURL can't match. Use cURL to learn the API, then build your integration in code.

Start Testing in 30 Seconds

Open your terminal, paste the basic cURL command, and you'll have a verified email result before you finish reading this sentence. That's the value of cURL for API testing. No SDKs to install, no code to write, no dependencies to manage. Just a URL, your API key, and an email address.

Once you've tested the edge cases and understand the response format, you're ready to build your integration in whatever language your application uses. Check the API documentation for language-specific examples in PHP, Python, Node.js, and more.