Bulk verification endpoint: submit a list, poll for results

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

{
  "emails": ["user1@example.com", "user2@example.com", "user3@example.com"],
  "name": "Q2 newsletter cleanup"
}

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": "Q2 newsletter cleanup"
  }'

{
  "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"
}

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

{
  "task_id": "VECGE7KL3DQ",
  "name": "Q2 newsletter cleanup",
  "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-05-19T21: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-05-19T21:17:06.460Z",
      "reason": "Inbox full"
    }
  }
}

async function waitForResults(taskId, maxWaitSeconds = 600) {
  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 ${process.env.VEC_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 new Promise(r => setTimeout(r, pollInterval));
  }

  throw new Error('Timeout waiting for results');
}

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

{
  "error": "Task not found"
}

async function safeGetResults(taskId) {
  const response = await fetch(
    `https://app.validemailchecker.com/api/get-results/${taskId}`,
    { headers: { Authorization: `Bearer ${process.env.VEC_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');
  if (response.status === 403) throw new Error('Unauthorized — task belongs to a different account');

  return await response.json();
}