Bulk Processing

Process thousands of email addresses or domains in a single request. Upload a CSV file and download the classified results when processing completes.

How it works

  1. Upload a CSV file containing emails or domains (one per row)
  2. EmailKind processes each item asynchronously in the background
  3. Check the job status via the API or dashboard
  4. Download the results as a CSV when complete

Upload a bulk job

POST /v1/bulk
Content-Type: multipart/form-data

curl -X POST -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -F "[email protected]" \
  -F "enrich=true" \
  "https://emailkind.com/v1/bulk"

Parameters:

| Field | Type | Required | Description | |---|---|---|---| | file | file | Yes | CSV file (max 2MB, max 10,000 rows) | | enrich | string | No | Set to true to include company enrichment |

Response (202 Accepted):

{
  "success": true,
  "request_id": "req_abc123",
  "job": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "total_items": 1500,
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Check job status

GET /v1/bulk/{id}

curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://emailkind.com/v1/bulk/550e8400-e29b-41d4-a716-446655440000"

Response:

{
  "success": true,
  "request_id": "req_def456",
  "job": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "total_items": 1500,
    "processed_items": 750,
    "enrich": true,
    "created_at": "2025-01-15T10:30:00Z",
    "started_at": "2025-01-15T10:30:01Z"
  }
}

Job statuses:

| Status | Description | |---|---| | pending | Job created, waiting to start | | processing | Currently classifying items | | completed | All items processed, results ready | | failed | An error occurred during processing |

Download results

GET /v1/bulk/{id}/results

curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -o results.csv \
  "https://emailkind.com/v1/bulk/550e8400-e29b-41d4-a716-446655440000/results"

Returns a CSV file with the following columns:

| Column | Description | |---|---| | input | Original email or domain from the uploaded file | | domain | Extracted domain | | provider_id | Provider identifier | | provider_name | Provider display name | | provider_type | business, personal, disposable, etc. | | is_business | true/false | | is_free | true/false | | is_disposable | true/false | | is_education | true/false | | confidence | Confidence score (0.0 - 1.0) | | company_name | Company name (if enrich=true) | | company_source | Enrichment source (if enrich=true) |

List all jobs

GET /v1/bulk

Returns the 20 most recent bulk jobs for your account.

CSV input format

The CSV should contain one email address or domain per row in the first column. A header row is automatically detected and skipped.

Example:

email
[email protected]
[email protected]
[email protected]

Or just domains:

gmail.com
company.com
example.org

Limits

  • Maximum 10,000 items per file
  • Maximum 2MB file size
  • Maximum 3 concurrent jobs per account
  • Available on Starter plan and above
  • Not available in sandbox mode

Webhooks

If you have webhooks configured, a bulk.completed event is dispatched when a job finishes:

{
  "event": "bulk.completed",
  "timestamp": "2025-01-15T10:35:00Z",
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "total_items": 1500,
    "status": "completed"
  }
}

Email notification

An email notification is sent to the account owner when a bulk job completes.