Skip to main content

​
Overview

Create a batch verification task for up to 10,000 emails. Processing runs asynchronously, and you can optionally provide a webhook for completion notifications.

​
POST /api/v1/tasks

Purpose: create a batch verification task (up to 10,000 emails). Emails are grouped by domain and queued for processing. Optional webhook to receive completion callbacks.

​
Request

Headers:
  • Content-Type: application/json
Body:
  • emails (array of string, required, max 10,000)
  • webhook_url (string, optional, must be a valid URL)
Example request: 
curl -X POST \
  'https://api.example.com/api/v1/tasks' \
  -H 'Content-Type: application/json' \
  -d '{
    "emails": ["[email protected]", "[email protected]"],
    "webhook_url": "https://example.com/webhook"
  }'

​
Response

Status: 201 Created Example response: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "webhook_url": "https://example.com/webhook",
  "source": "frontend",
  "created_at": "2025-01-01T12:00:00Z",
  "email_count": 2,
  "domain_count": 1
}
Response fields:
  • id: batch verification task UUID.
  • user_id: derived from auth (may be null for dev keys).
  • webhook_url: webhook URL stored for the batch verification task.
  • source: indicates batch verification origin (frontend or api_key).
  • created_at: batch verification creation timestamp.
  • email_count: total emails submitted.
  • domain_count: number of unique domains queued.
Errors:
  • 400 invalid payload (invalid emails, webhook URL, or >10,000 emails).
  • 401 unauthorized.
  • 429 rate limited.
  • 500 internal error.