Bulk Validate Endpoint

The /v1/bulk-validate endpoint allows you to validate multiple domains in a single API request, making it efficient for processing large lists of domains.

Endpoint

POST /v1/bulk-validate

Request Format

Headers

Header Value Required Description
X-API-Key string Yes Your API key for authentication
Content-Type application/json Yes Request body format

Request Body

{
  "domains": [
    {
      "domain": "example.com",
      "dkim_selector": "default"
    },
    {
      "domain": "another-example.com"
    }
  ],
  "options": {
    "include_score": true,
    "include_recommendations": false,
    "parallel": true
  }
}

Parameters

Parameter Type Required Description
domains array Yes Array of domain objects to validate (max 100)
domains[].domain string Yes Domain name to validate
domains[].dkim_selector string No Optional DKIM selector for this domain
options.include_score boolean No Include mailflow security score (default: true)
options.include_recommendations boolean No Include recommendations (default: false)
options.parallel boolean No Process domains in parallel (default: true)

Batch Size Limits

  • Free tier: Maximum 10 domains per request
  • Basic tier: Maximum 50 domains per request
  • Premium tier: Maximum 100 domains per request

Example Request

cURL: 

curl -X POST "https://api.reputeapi.com/v1/bulk-validate" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": [
      {"domain": "example.com"},
      {"domain": "another-example.com", "dkim_selector": "default"}
    ],
    "options": {
      "include_score": true
    }
  }'

Python: 

import requests

url = "https://api.reputeapi.com/v1/bulk-validate"
headers = {
    "X-API-Key": "your-api-key",
    "Content-Type": "application/json"
}

payload = {
    "domains": [
        {"domain": "example.com"},
        {"domain": "another-example.com", "dkim_selector": "default"}
    ],
    "options": {
        "include_score": True
    }
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

# Process results
for item in result["results"]:
    print(f"{item['domain']}: Score {item['score']}/100")

JavaScript: 

const response = await fetch(
  'https://api.reputeapi.com/v1/bulk-validate',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      domains: [
        { domain: 'example.com' },
        { domain: 'another-example.com', dkim_selector: 'default' }
      ],
      options: {
        include_score: true
      }
    })
  }
);

const result = await response.json();

// Process results
result.results.forEach(item => {
  console.log(`${item.domain}: Score ${item.score}/100`);
});

Response Format

Success Response (200 OK)

{
  "request_id": "req_abc123xyz",
  "total_domains": 2,
  "successful": 2,
  "failed": 0,
  "processing_time_ms": 1250,
  "results": [
    {
      "domain": "example.com",
      "status": "success",
      "score": 85,
      "spf": {
        "valid": true,
        "record": "v=spf1 include:_spf.google.com ~all"
      },
      "dkim": {
        "valid": true,
        "selector": "default",
        "record": "v=DKIM1; k=rsa; p=..."
      },
      "dmarc": {
        "valid": true,
        "record": "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com"
      },
      "issues": [
        {
          "code": "DMARC_POLICY_NONE",
          "severity": "high",
          "title": "DMARC policy set to 'none'"
        }
      ]
    },
    {
      "domain": "another-example.com",
      "status": "success",
      "score": 92,
      "spf": {
        "valid": true,
        "record": "v=spf1 include:_spf.google.com -all"
      },
      "dkim": {
        "valid": true,
        "selector": "default",
        "record": "v=DKIM1; k=rsa; p=..."
      },
      "dmarc": {
        "valid": true,
        "record": "v=DMARC1; p=reject; rua=mailto:dmarc@another-example.com"
      },
      "issues": []
    }
  ],
  "errors": []
}

Partial Success Response (207 Multi-Status)

When some domains fail validation:

{
  "request_id": "req_abc123xyz",
  "total_domains": 3,
  "successful": 2,
  "failed": 1,
  "processing_time_ms": 1500,
  "results": [
    {
      "domain": "example.com",
      "status": "success",
      "score": 85
      // ... rest of data
    },
    {
      "domain": "another-example.com",
      "status": "success",
      "score": 92
      // ... rest of data
    }
  ],
  "errors": [
    {
      "domain": "invalid-domain",
      "status": "error",
      "error_code": "DNS_RESOLUTION_FAILED",
      "message": "Failed to resolve domain: invalid-domain"
    }
  ]
}

Error Responses

400 Bad Request

Invalid request format:

{
  "error": "Bad Request",
  "message": "Request body must contain 'domains' array",
  "status": 400
}

413 Payload Too Large

Too many domains in request:

{
  "error": "Payload Too Large",
  "message": "Maximum 100 domains per request (Premium tier limit)",
  "max_domains": 100,
  "tier": "premium",
  "status": 413
}

429 Too Many Requests

Rate limit exceeded:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again later.",
  "retry_after": 60,
  "status": 429
}

Performance Considerations

Parallel Processing

By default, domains are processed in parallel for optimal performance:

  • Sequential processing: ~500ms per domain
  • Parallel processing: ~500-800ms total for up to 10 domains

Enable parallel processing (default): 

{
  "options": {
    "parallel": true
  }
}

Timeouts

  • Single domain timeout: 10 seconds
  • Total request timeout: 30 seconds
  • Domains that timeout will be included in the errors array

Caching

Results are cached for 5 minutes. Subsequent requests for the same domain within this window will return cached results instantly.

Best Practices

1. Batch Size Optimization

For best performance, batch domains in groups of 50:

domains = ["domain1.com", "domain2.com", ...]  # Large list

# Process in batches of 50
batch_size = 50
for i in range(0, len(domains), batch_size):
    batch = domains[i:i + batch_size]
    results = bulk_validate(batch)
    process_results(results)

2. Error Handling

Always check both results and errors arrays:

response = bulk_validate(domains)

# Process successful results
for result in response["results"]:
    if result["status"] == "success":
        save_to_database(result)

# Handle errors
for error in response["errors"]:
    log_error(f"Failed to validate {error['domain']}: {error['message']}")

3. Rate Limit Management

Respect rate limits by processing in batches with delays:

import time

batches = chunk_domains(all_domains, batch_size=50)

for batch in batches:
    results = bulk_validate(batch)
    process_results(results)

    # Wait to respect rate limits
    time.sleep(1)  # Adjust based on your tier

Pricing Impact

Each domain in the bulk request counts as 1 API call towards your monthly quota:

  • Validating 10 domains = 10 API calls
  • Validating 100 domains = 100 API calls

See Rate Limits for quota details.

See Also