Validate Bulk Emails

Validate up to 100 emails in a single request

POST /v1/validate/bulk

Validate multiple email addresses (up to 100) in a single API request.

This endpoint is synchronous and returns conservative temporary SMTP results immediately. For durable retries after 15 minutes and four additional hours for explicit unknown_temporary SMTP responses, use Async Validation Jobs.

Each result also contains additive combined-evidence fields. Enterprise-gateway inference is returned in shadow mode and does not override the canonical result, the production send_recommendation, or billing.

Endpoint

POST https://api.gtmapis.com/v1/validate/bulk

Headers

Header	Required	Description
Content-Type	Yes	Must be application/json
X-API-Key	Yes	Your API key (gtm_test_* or gtm_live_*)
Idempotency-Key	No	Retry-safe key for one logical batch. Successful responses are replayable for 24 hours without validating, signing, or charging again.
X-GTM-Benchmark-Receipt	No	Set to email-benchmark-receipt-v6 and use force_refresh: true for prospective accuracy acquisition. It signs the fresh-evidence request, exact mailbox identity, the provider-family snapshot, and decisive reviewed Microsoft SMTP route provenance when available. Version 5 preserves route provenance without the freshness claim; version 4 preserves provider-family evidence; versions 2 and 3 preserve older artifacts.

Retry-safe requests

Use a unique Idempotency-Key for each logical batch. Reusing the key with the same ordered, canonical email list and benchmark-receipt setting returns the exact successful JSON response with Idempotency-Replayed: true. The original response sets the header to false.

Email order is part of the request identity because result order is preserved. A changed list, changed order, or changed benchmark-receipt setting returns 409 idempotency_key_conflict. A duplicate still in progress returns 409 idempotency_request_in_progress with Retry-After: 2. Only successful responses are retained; deterministic and transient failures can be retried with the same key after their cause is resolved.

Request Body

Field	Type	Required	Description
emails	array[string]	Yes	Up to 100 strings to classify; syntax-invalid strings receive free per-row invalid results

Example Request

cURL

curl -X POST https://api.gtmapis.com/v1/validate/bulk \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gtm_test_1234567890abcdef1234567890abcdef" \
  -H "Idempotency-Key: import-2026-08-05-chunk-1" \
  -d '{
    "emails": [
      "[e-mail]",
      "[e-mail]",
      "not-an-email"
    ]
  }'

Response

Success Response (200 OK)

{
  "results": [
    {
      "email": "[e-mail]",
      "result": "valid",
      "send_recommendation": "send",
      "pre_send_bounce_risk": "low",
      "pre_send_bounce_reason": "smtp_verified",
      "domain_typo_suspected": false,
      "suggested_email": null,
      "is_role_based": false,
      "is_disposable": false,
      "b2b_outbound_quality": "high",
      "credits_charged": 1,
      "charge_reason": "Valid personal email with high B2B outbound quality"
    },
    {
      "email": "[e-mail]",
      "result": "valid_role_based",
      "send_recommendation": "send",
      "pre_send_bounce_risk": "low",
      "pre_send_bounce_reason": "role_based_but_verified",
      "domain_typo_suspected": false,
      "suggested_email": null,
      "is_role_based": true,
      "is_disposable": false,
      "b2b_outbound_quality": "low",
      "credits_charged": 0,
      "charge_reason": "Role-based email - free for low B2B value"
    },
    {
      "email": "not-an-email",
      "result": "invalid",
      "send_recommendation": "do_not_send",
      "pre_send_bounce_risk": "blocked",
      "pre_send_bounce_reason": "invalid_syntax",
      "domain_typo_suspected": false,
      "suggested_email": null,
      "syntax_valid": false,
      "dns_valid": false,
      "dns_status": "not_checked",
      "b2b_outbound_quality": "none",
      "credits_charged": 0,
      "charge_reason": "Invalid email syntax - no credit charged"
    }
  ],
  "summary": {
    "total": 3,
    "valid": 1,
    "valid_role_based": 1,
    "invalid": 1,
    "risky": 0,
    "unknown": 0,
    "high_value": 1,
    "catch_all": 0,
    "credits_reserved": 2,
    "credits_charged": 1,
    "credits_consumed": 1,
    "credits_refunded": 1,
    "credits_per_high_value_validation": 1
  }
}

Response Fields

results · array · required

Array of validation results, one per input email

Each result has the same fields as the single validation endpoint

summary · object · required

Summary statistics for the bulk validation

benchmark_receipt · object

Present only when X-GTM-Benchmark-Receipt: email-benchmark-receipt-v6 (or explicit compatibility v2/v3/v4/v5) was requested. Contains schema_version, an ES256 compact-JWS token, and the signed server issued_at timestamp. The token binds aggregate hashes of the cohort and ordered benchmark projection. Version 6 also binds the requested fresh-evidence mode. Its projection includes the bounded provider family, taxonomy version, and decisive reviewed Microsoft SMTP route provenance when available; it contains no raw email addresses, tenant MX hosts, internal route IDs, or verdicts. Verify it with the benchmark key published at https://api.gtmapis.com/.well-known/jwks.json.

summary.total · integer · required

Total number of emails validated

summary.valid · integer · required

Count of valid results (personal emails)

summary.valid_role_based · integer · required

Count of valid_role_based results

summary.risky · integer · required

Count of risky results (catch-all domains)

summary.invalid · integer · required

Count of invalid results

summary.unknown · integer · required

Count of unknown results

summary.high_value · integer · required

Count of High-Value Validations: valid personal emails that are not role-based, catch-all, risky, invalid, or unknown.

summary.catch_all · integer · required

Count of results from catch-all domains. These are not High-Value Validations by default.

summary.credits_reserved · integer · required

Credits reserved before uncached validation work starts.

summary.credits_charged · integer · required

Total credits charged for this bulk validation. This is kept as a compatibility alias for consumed credits.

Sum of all credits_charged values in results

summary.credits_consumed · integer · required

Credits consumed after applying GTMAPIs credit policy. For Email Validation this matches credits_charged.

summary.credits_refunded · integer · required

Reserved credits returned because the corresponding results were role-based, catch-all, invalid, risky, unknown, or otherwise non-chargeable.

summary.credits_per_high_value_validation · number | null · required

Effective credits consumed per High-Value Validation. This is null when the response contains no high-value validations.

Limits

Limit	Value
Max emails per request	100
Max emails per async job (/v1/validate/batch)	500,000
Rate limit	10,000 requests/minute per API key

Exceeding Limits

Too many emails in one request (> 100):

{
  "error": "Bad Request",
  "message": "Maximum 100 emails per request. Received: 150"
}

Solution: Split into multiple requests of 100 emails each, or use /v1/validate/batch for larger asynchronous jobs.

Processing Time

Processing time varies with cache state, DNS responsiveness, and SMTP server behavior. Use /v1/validate/bulk for synchronous batches up to 100 emails, and use /v1/validate/batch or the signed CSV upload flow for larger jobs that need polling and download handoffs.

Best Practices

Batch Processing

For large lists (1000+ emails), process in batches:

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

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

    const response = await fetch('https://api.gtmapis.com/v1/validate/bulk', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.GTMAPIS_API_KEY
      },
      body: JSON.stringify({ emails: batch })
    });

    const batchResults = await response.json();
    results.push(...batchResults.results);

    // Optional: Add delay to avoid rate limits
    if (i + batchSize < emails.length) {
      await new Promise(resolve => setTimeout(resolve, 500));
    }
  }

  return results;
}

Error Handling

An upstream validation failure returns 502, code: "validation_upstream_failed", retry_after: 30, and a matching Retry-After: 30 header. Wait for that delay before retrying the same logical request. The failed validation does not consume credits.

Handle errors gracefully:

async function validateBatch(emails) {
  try {
    const response = await fetch('https://api.gtmapis.com/v1/validate/bulk', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.GTMAPIS_API_KEY
      },
      body: JSON.stringify({ emails })
    });

    if (!response.ok) {
      if (response.status === 429) {
        // Rate limit - wait and retry
        await new Promise(resolve => setTimeout(resolve, 60000));
        return validateBatch(emails);
      }
      throw new Error(`HTTP ${response.status}: ${await response.text()}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Validation failed:', error);
    throw error;
  }
}

Filtering Results

Filter by quality for campaign use:

const { results, summary } = await validateBulk(emails);

// Only high-quality emails for primary campaign
const highQuality = results.filter(r =>
  r.result === 'valid' && r.b2b_outbound_quality === 'high'
);

// Role-based emails for secondary campaign
const roleBased = results.filter(r =>
  r.result === 'valid_role_based'
);

// Remove invalids and risky
const toRemove = results.filter(r =>
  r.result === 'invalid' || r.result === 'risky'
);

console.log(`High quality: ${highQuality.length}`);
console.log(`Role-based: ${roleBased.length}`);
console.log(`To remove: ${toRemove.length}`);
console.log(`Credits charged: ${summary.credits_charged}`);

Credit Estimate

Estimate the maximum credits before processing:

// Estimate maximum credits (assuming all are high-value personal emails)
const emailCount = emails.length;
const maxCredits = emailCount;

console.log(`Max credits: ${maxCredits}`);

// After validation, calculate actual credits charged
const actualCredits = summary.credits_charged;

console.log(`Actual credits: ${actualCredits}`);
console.log(`Credits not charged: ${maxCredits - actualCredits}`);

Common Patterns

Deduplicate Before Validation

Save credits by removing duplicates:

// Remove duplicates (case-insensitive)
const uniqueEmails = [...new Set(
  emails.map(e => e.toLowerCase())
)];

console.log(`Original: ${emails.length}`);
console.log(`Unique: ${uniqueEmails.length}`);
console.log(`Duplicates removed: ${emails.length - uniqueEmails.length}`);

// Validate unique emails only
const results = await validateBulk(uniqueEmails);

Progress Tracking

Track progress for large batches:

async function validateWithProgress(emails, onProgress) {
  const batchSize = 100;
  const results = [];

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

    results.push(...batchResults.results);

    // Report progress
    const progress = Math.min(100, ((i + batchSize) / emails.length) * 100);
    onProgress(progress, results.length, emails.length);
  }

  return results;
}

// Usage
await validateWithProgress(emails, (progress, validated, total) => {
  console.log(`Progress: ${progress.toFixed(0)}% (${validated}/${total})`);
});

Next Steps

Single Validation

Validate one email at a time

CSV Upload Guide

Upload and validate CSV files via dashboard