Batch Validation

Batch validation lets you validate multiple emails in a single request, reducing overhead and improving throughput for list cleaning and bulk operations.

Endpoint

POST /validate/batch

Request

Headers

Header	Required	Description
X-API-Key	Yes	Your API key
Content-Type	Yes	application/json

Body

{
  "emails": [
    "user1@example.com",
    "user2@company.org",
    "test@mailinator.com"
  ],
  "options": {
    "quickMode": false
  }
}

Field	Type	Required	Description
emails	string[]	Yes	Array of email addresses (1-100)
options.quickMode	boolean	No	Skip expensive checks for faster results

Caution

Maximum batch size is 100 emails. Requests with more than 100 emails return BATCH_TOO_LARGE error.

---

Response

{
  "total": 3,
  "valid": 2,
  "invalid": 1,
  "warning": 0,
  "results": [
    {
      "email": "user1@example.com",
      "severity": "valid",
      "isValid": true,
      "score": 95,
      "checks": { ... },
      "recommendations": []
    },
    {
      "email": "user2@company.org",
      "severity": "valid",
      "isValid": true,
      "score": 88,
      "checks": { ... },
      "recommendations": []
    },
    {
      "email": "test@mailinator.com",
      "severity": "invalid",
      "isValid": false,
      "score": 25,
      "checks": { ... },
      "recommendations": ["Disposable email detected"]
    }
  ],
  "processingTime": 342,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Response Fields

Field	Type	Description
total	number	Total emails processed
valid	number	Count of valid emails (score >= 70)
invalid	number	Count of invalid emails (score < 40)
warning	number	Count of warning emails (score 40-69)
results	array	Individual validation results
processingTime	number	Total processing time in milliseconds
timestamp	string	ISO 8601 timestamp

Each item in results follows the standard Response Schema.

---

Usage Examples

cURL

curl -X POST https://api.spamidate.com/validate/batch \
  -H "X-API-Key: spm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "user1@example.com",
      "user2@company.org",
      "test@mailinator.com"
    ]
  }'

JavaScript

const response = await fetch('https://api.spamidate.com/validate/batch', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.SPAMIDATE_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    emails: [
      'user1@example.com',
      'user2@company.org',
      'test@mailinator.com',
    ],
  }),
});

const result = await response.json();
console.log(`Valid: ${result.valid}/${result.total}`);

SDK

import { Spamidate } from '@spamidate/sdk';

const client = new Spamidate({ apiKey: process.env.SPAMIDATE_API_KEY });

const results = await client.validateBatch([
  'user1@example.com',
  'user2@company.org',
  'test@mailinator.com',
]);

console.log(`Valid: ${results.valid}/${results.total}`);

// Filter results
const validEmails = results.results
  .filter(r => r.isValid)
  .map(r => r.email);

---

Quota Behavior

Each email in a batch counts toward your monthly quota:

Batch Size	Quota Used	Rate Limit Impact
1 email	1	1 request
50 emails	50	1 request
100 emails	100	1 request

Tip

Batch requests count as a single rate-limit request but consume quota per email. This means you can validate 100 emails while only using 1 of your per-minute requests.

---

Processing Large Lists

For lists larger than 100 emails, process in batches:

async function validateLargeList(emails: string[]) {
  const results = [];
  const batchSize = 100;

  for (let i = 0; i < emails.length; i += batchSize) {
    const batch = emails.slice(i, i + batchSize);
    const response = await client.validateBatch(batch);
    results.push(...response.results);

    // Optional: Progress logging
    console.log(`Processed ${Math.min(i + batchSize, emails.length)}/${emails.length}`);
  }

  return {
    total: results.length,
    valid: results.filter(r => r.isValid).length,
    invalid: results.filter(r => !r.isValid).length,
    results,
  };
}

With Rate Limit Handling

async function validateWithRateLimit(emails: string[], client: Spamidate) {
  const results = [];
  const batchSize = 100;

  for (let i = 0; i < emails.length; i += batchSize) {
    const batch = emails.slice(i, i + batchSize);

    try {
      const response = await client.validateBatch(batch);
      results.push(...response.results);
    } catch (error) {
      if (error instanceof RateLimitError) {
        // Wait and retry
        await new Promise(r => setTimeout(r, error.retryAfter * 1000));
        i -= batchSize; // Retry this batch
        continue;
      }
      throw error;
    }
  }

  return results;
}

---

Deduplication

Remove duplicates before batch validation to save quota:

function deduplicateEmails(emails: string[]): string[] {
  const seen = new Set<string>();
  return emails.filter(email => {
    const normalized = email.toLowerCase().trim();
    if (seen.has(normalized)) return false;
    seen.add(normalized);
    return true;
  });
}

// Usage
const unique = deduplicateEmails(rawEmails);
const results = await client.validateBatch(unique);

---

Response Filtering

Extract Valid Emails

const validEmails = results.results
  .filter(r => r.severity === 'valid')
  .map(r => r.email);

Separate by Severity

const grouped = {
  valid: results.results.filter(r => r.severity === 'valid'),
  warning: results.results.filter(r => r.severity === 'warning'),
  invalid: results.results.filter(r => r.severity === 'invalid'),
};

Filter by Specific Check

// Get non-disposable emails
const realEmails = results.results.filter(
  r => r.checks.disposable?.passed !== false
);

// Get corporate emails only
const corporateEmails = results.results.filter(
  r => r.checks.corporateEmail?.metadata?.isCorporate === true
);

---

Error Handling

Batch-Specific Errors

Error	Description
BATCH_TOO_LARGE	More than 100 emails submitted
BATCH_EMPTY	Empty emails array

{
  "error": {
    "code": "BATCH_TOO_LARGE",
    "message": "Batch size exceeds maximum of 100 emails",
    "details": {
      "submitted": 150,
      "maximum": 100
    }
  }
}

Partial Failures

If individual emails fail validation, they’re included in results with error status:

{
  "email": "invalid-format",
  "severity": "invalid",
  "isValid": false,
  "score": 0,
  "checks": {
    "syntax": {
      "passed": false,
      "status": "fail",
      "reason": "Invalid email format"
    }
  }
}

Note

Batch validation never fails entirely due to individual email issues. Invalid emails are included in the results with appropriate error information.

---

Performance Tips

1. Use Quick Mode for Speed

   await client.validateBatch(emails, { quickMode: true });

2. Deduplicate First - Don’t pay for the same email twice

3. Process in Parallel (with rate limit awareness)

   // Process multiple batches concurrently (if your tier allows)
   const batches = chunk(emails, 100);
   const results = await Promise.all(
     batches.map(batch => client.validateBatch(batch))
   );

4. Cache Results - Validation results are stable for 24+ hours