Bulk verification

Submit a list of addresses as an asynchronous batch, then poll for results. Quota for the full batch size is checked up front, before any items are processed.

#Submit a batch

POST /verify/bulk

Provide emails, text, or both, they're merged and de-duplicated. Addresses are trimmed and lower-cased, and anything without an @ is dropped. A batch may contain at most 50,000 addresses. name is at most 120 characters.

curl https://app.warmerly.com/api/v1/verify/bulk \
  -X POST \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Q3 leads", "emails": ["jane@example.com", "john@example.com"] }'

{
  "batch": {
    "id": "6f2c6c8e-9b1d-4e3a-9c7f-2d1e8b4a6c9e",
    "total": 2,
    "status": "processing"
  }
}

201 Created on success. Errors: 400 bad_request (invalid_body, no_valid_emails or batch_too_large_max_50000), 403 channel_not_included if your plan does not include email features, and 402 quota_exhausted if the batch does not fit your remaining quota. The 402 details hold label, used, limit, topUpUrl and upgradeUrl, plus topUp when credits can cover the shortfall. Items still queued from your earlier batches count against the new one.

#Get batch status and results

GET /verify/bulk/{id}

Returns the batch's progress and, for items that have been processed, their verification results.

curl https://app.warmerly.com/api/v1/verify/bulk/6f2c6c8e-9b1d-4e3a-9c7f-2d1e8b4a6c9e \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "batch": {
    "id": "6f2c6c8e-9b1d-4e3a-9c7f-2d1e8b4a6c9e",
    "name": "Q3 leads",
    "status": "processing",
    "total": 2,
    "processed": 1,
    "createdAt": "2026-07-02T10:00:00.000Z",
    "completedAt": null
  },
  "items": [
    {
      "email": "jane@example.com",
      "recommendation": "Safe to send",
      "status": "valid",
      "confidence": 95,
      "reason": "mailbox_accepts"
    },
    {
      "email": "john@example.com",
      "recommendation": "Pending",
      "status": null,
      "confidence": null,
      "reason": null
    }
  ],
  "itemsTruncated": false,
  "itemsLimit": 1000
}

batch.status is processing or completed. The JSON view returns at most 1,000 items, in a stable order; itemsTruncated says whether the list was cut and itemsLimit is the cap (1000). Add ?all=1 for every item as JSON. Each item's recommendation is Safe to send, Send with caution, Do not send, Unknown, or Pending (not yet processed), a human-readable summary derived from status/confidence/checks. 404 not_found if the batch doesn't exist or belongs to another user.

Pass ?format=csv to download all results (not capped at 1,000) as a CSV file (email,recommendation,status,confidence,reason) instead of JSON. Items not yet processed show pending in the status column:

curl "https://app.warmerly.com/api/v1/verify/bulk/6f2c6c8e-9b1d-4e3a-9c7f-2d1e8b4a6c9e?format=csv" \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -o results.csv