Overview

The Bulk CSV Validation API lets you validate email addresses in bulk by uploading a CSV file up to 100 MB.

Instead of calling the single-email endpoints one at a time, you upload your entire file and download the results when processing is complete.

How It Works

The bulk validation flow has four steps:

Step 1: Create a Job

Call Create CSV Validation Job with the column number that contains your email addresses.

curl -X POST https://api.allegrow.co/v1/email/validate-file \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emailColumn": 0}'

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "awaiting_upload",
  "uploadUrl": "https://s3.amazonaws.com/...presigned-url...",
  "uploadExpiresIn": 300
}

You'll receive a jobId to use in all subsequent requests and a temporary uploadUrl for uploading your CSV file.

Step 2: Upload Your CSV

Upload your CSV file to the uploadUrl from Step 1. This is a direct file upload to a presigned URL — no API key is needed for this request.

curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
  -H "Content-Type: text/csv" \
  --data-binary @your-file.csv

• Method: PUT (not POST)
• Header: Content-Type: text/csv (required)
• Body: Your raw CSV file contents

Response: An HTTP 200 with no body indicates a successful upload.

Important: The upload URL expires after 5 minutes. If it expires, create a new job to get a fresh URL. The maximum file size is 100 MB.

If the upload URL has expired, you will receive an HTTP 403 error. Create a new job to get a fresh upload URL.

Processing begins automatically once the upload is complete — no further action is needed to start it.

Step 3: Poll for Status

Call Get CSV Job Status periodically until status is completed.

curl https://api.allegrow.co/v1/email/validate-file/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY"

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "totalEmails": 10000,
  "processedEmails": 4523,
  "percentComplete": 45,
  "createdAt": "2026-04-01T10:30:00.000Z",
  "completedAt": null,
  "statistics": null
}

Once the status is completed, statistics will contain a full breakdown of results and completedAt will have a timestamp.

Step 4: Download Results

Once the status is completed, call Download CSV Job Results to get a temporary download URL.

curl https://api.allegrow.co/v1/email/validate-file/550e8400-e29b-41d4-a716-446655440000/download \
  -H "x-api-key: YOUR_API_KEY"

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "downloadUrl": "https://s3.amazonaws.com/...presigned-url...",
  "expiresIn": 3600,
  "format": "csv"
}

The results file is your original CSV with an additional column appended containing the Allegrow validation status for each email. Download it with a simple GET request:

curl -o results.csv "DOWNLOAD_URL_FROM_RESPONSE"

Limits

Validation Statuses in Results

The results CSV includes an Allegrow validation status for each email. See Validation Statuses for a full explanation of each status value.

Completion Webhook

You can provide a callbackUrl when creating a job. When the job completes, Allegrow sends a POST request to your URL with the job results.

curl -X POST https://api.allegrow.co/v1/email/validate-file \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emailColumn": 0, "callbackUrl": "https://your-app.com/webhooks/validation-complete"}'

Webhook payload:

{
  "event": "bulk_validation.completed",
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "totalEmails": 10000,
  "statistics": {
    "safe": 7200,
    "block_bounce_risk": 1500,
    "some_risk": 800,
    "dead_email": 300,
    "do_not_mail_abuse": 200
  }
}

Retry behavior:

• Your endpoint should return an HTTP 2xx status to acknowledge receipt.
• If your endpoint returns a 5xx error or 429, Allegrow will retry the webhook up to 5 times within a 1-hour window, using exponential backoff.
• If your endpoint returns a 4xx error (other than 429), the webhook will not be retried.
• After all retries are exhausted, the webhook is not sent again. You can always check job status and download results using the API endpoints, even if the webhook delivery fails.

Verifying the webhook:

You can confirm a completion webhook genuinely came from Allegrow by checking its signature. See Verifying Webhook Signatures.