Skip to main content

​
Overview

Upload a file of email addresses to start a batch verification task. Processing runs asynchronously, and you can optionally provide a webhook for completion notifications.

​
POST /api/v1/tasks/batch/upload

Purpose: upload a file containing email addresses for batch verification. Processing happens asynchronously.

​
Request

Headers:
  • Content-Type: multipart/form-data
Form fields:
  • file (required): the email list file.
  • webhook_url (optional): webhook URL for notifications.
  • email_column (optional): column header or 1-based index for CSV/XLSX.
  • column (optional): alias for email_column.
Notes:
  • Allowed formats and max file size are enforced by server config. Supported extensions: .txt, .csv, .xlsx.
  • email_column is not supported for .txt files.
  • user_id is not allowed in the form body.
  • Maximum of 10,000 emails per file.
Example request: 
curl -X POST \
  'https://api.example.com/api/v1/tasks/batch/upload' \
  -F '[email protected]' \
  -F 'webhook_url=https://example.com/webhook' \
  -F 'email_column=email'

​
Response

Status: 202 Accepted Example response: 
{
  "upload_id": "7d3df4c6-9a7d-4d16-9f2b-2a5ddf4f4f53",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "emails.csv",
  "email_count": 123,
  "status": "processing",
  "message": "File uploaded successfully and is being processed",
  "uploaded_at": "2025-01-01T12:00:00Z"
}
Response fields:
  • upload_id: UUID for this upload.
  • task_id: task created for processing.
  • filename: original file name.
  • email_count: emails queued for processing.
  • status: current status (processing, completed, failed).
  • message: human-readable status message.
  • uploaded_at: timestamp of the upload.
Errors:
  • 400 file missing, unsupported file format, invalid file, invalid webhook URL, invalid email_column, no valid emails, email limit exceeded, or validation failures.
  • 401 unauthorized.
  • 500 internal error.