Bulk Verification Endpoint

Need to verify hundreds or thousands of emails? The bulk verification endpoint lets you submit lists programmatically and retrieve results when ready. It's a two-step process: create a task, then get results.

---

How Bulk Verification Works

Unlike single verification (which is synchronous), bulk verification is asynchronous:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Step 1: POST   │────▶│  Processing...  │────▶│  Step 2: GET    │
│  Create Task    │     │  (Background)   │     │  Get Results    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
   Returns task_id         Takes time            Returns results

1. Submit your email list → Receive a task_id
2. Poll for results → Get status and results when complete

---

Step 1: Create Verification Task

Endpoint Details

Property	Value
URL	https://app.validemailchecker.com/api/verify-bulk
Method	POST
Content-Type	application/json
Authentication	Bearer token (API key)

Request Format

{
  "emails": ["user1@example.com", "user2@example.com", "user3@example.com"],
  "name": "My Bulk Task"
}

Field	Type	Required	Description
emails	array	Yes	Array of email addresses to verify
name	string	No	A friendly name for the task (helps identify it later)

cURL Example

curl -X POST https://app.validemailchecker.com/api/verify-bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["user1@example.com", "user2@example.com"],
    "name": "My Bulk Task"
  }'

Response

{
    "task_id": "VECGE7KL3DQ",
    "status": "processing",
    "total_emails": 2,
    "is_chunked": false,
    "total_chunks": 1,
    "partial_failure": false,
    "failed_emails_count": 0,
    "credits_refunded": 0,
    "message": "Bulk verification task created successfully"
}

info

Save the task_id! You'll need it to retrieve your results in Step 2.

---

Step 2: Get Results

Endpoint Details

Property	Value
URL	https://app.validemailchecker.com/api/get-results/{task_id}
Method	GET
Authentication	Bearer token (API key)

cURL Example

curl -X GET https://app.validemailchecker.com/api/get-results/VEC_TASK_123456 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (Completed)

{
    "task_id": "VECGE7KL3DQ",
    "name": "My Bulk Task",
    "status": "completed",
    "progress_percentage": 100,
    "count_checked": 2,
    "count_total": 2,
    "results": {
        "support@validemailchecker.com": {
            "email": "support@validemailchecker.com",
            "status": "role_account",
            "is_valid": true,
            "is_disposable": false,
            "is_role_account": true,
            "is_catch_all": false,
            "is_free_email": false,
            "mx_found": true,
            "domain": "validemailchecker.com",
            "risk_score": 7,
            "deliverability": "high",
            "credits_used": 1,
            "verified_at": "2026-01-03T21:17:06.460Z",
            "reason": "Role account detected"
        },
        "username@gmail.com": {
            "email": "username@gmail.com",
            "status": "inbox_full",
            "is_valid": false,
            "is_disposable": false,
            "is_role_account": false,
            "is_catch_all": false,
            "is_free_email": true,
            "mx_found": true,
            "domain": "gmail.com",
            "risk_score": 80,
            "deliverability": "low",
            "credits_used": 1,
            "verified_at": "2026-01-03T21:17:06.460Z",
            "reason": "Inbox full"
        }
    }
}

tip

Check the progress_percentage to see how far along the task is. Results are only available when status is completed.

---

Task Status Values

Status	Meaning
pending	Task created, waiting to start
processing	Verification in progress
completed	All emails verified, results ready
failed	Task failed (rare, usually system issue)
Deleted	Task deleted from our server after 15 days

---

Polling for Results

Since bulk verification is asynchronous, you need to poll for results. Here's a recommended approach:

Simple Polling Strategy

async function waitForResults(taskId, maxWaitSeconds = 300) {
  const startTime = Date.now();
  const pollInterval = 5000; // 5 seconds
  
  while (Date.now() - startTime < maxWaitSeconds * 1000) {
    const response = await fetch(
      `https://app.validemailchecker.com/api/get-results/${taskId}`,
      {
        headers: { 'Authorization': `Bearer ${API_KEY}` }
      }
    );
    
    const data = await response.json();
    
    if (data.status === 'completed') {
      return data.results;
    }
    
    if (data.status === 'failed') {
      throw new Error('Task failed');
    }
    
    console.log(`Progress: ${data.progress_percentage}%`);
    await sleep(pollInterval);
  }
  
  throw new Error('Timeout waiting for results');
}

Recommended Poll Intervals

List Size	Poll Interval
1-100 emails	Every 3 seconds
100-1,000 emails	Every 5 seconds
1,000-10,000 emails	Every 10 seconds
10,000+ emails	Every 30 seconds

warning

Don't poll too frequently! Excessive polling may trigger rate limits. A 5-second minimum interval is recommended.

---

info

Tasks and results are stored for 15 days. After that, they're automatically deleted. Make sure to download your results before then!

---

Error Handling

Task Creation Errors

{
  "error": true,
  "message": "You need 1000 credits but only have 500 available",
  "code": "INSUFFICIENT_CREDITS",
  "required": 1000,
  "current_balance": 500
}

Result Retrieval Errors

{
  "error": true,
  "message": "Task not found",
  "code": "NOT_FOUND"
}

Handle All Scenarios

async function safeGetResults(taskId) {
  try {
    const response = await fetch(`${BASE_URL}/get-results/${taskId}`, {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    });
    
    if (response.status === 404) {
      throw new Error('Task not found - may have expired');
    }
    
    if (response.status === 401) {
      throw new Error('Invalid API key');
    }
    
    return await response.json();
    
  } catch (error) {
    console.error('Failed to get results:', error.message);
    throw error;
  }
}

---

Common Questions

How long does bulk verification take?

Processing time depends on list size:

• 100 emails: ~Seconds
• 1,000 emails: ~1-2 minutes
• 10,000 emails: ~5-10 minutes
• 100,000 emails: ~15-30 minutes
• 1,000,000 emails: ~1-2 hours

Times vary based on email domains and server responsiveness.

Can I cancel a running task?

Currently, tasks cannot be cancelled once started. Credits are reserved when the task is created.

What if my process crashes mid-poll?

Your task continues processing. Just call the get-results endpoint again with the same task_id to resume checking status.

Are results available in the dashboard too?

Yes! Bulk tasks created via API also appear in your Uploads & Results page in the dashboard.

How are credits charged?

Credits are reserved when you create the task. If verification fails for system reasons, credits are refunded.

---

Next Steps

-> Rate Limits & Error Handling - Understand limits and handle errors gracefully

-> Single Verification Endpoint - For real-time, one-at-a-time verification