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.