Verification API

Request body

Any other top-level field is rejected with 400 BAD_REQUEST, and any other field inside options with 400 INVALID_OPTION; both name the supported fields, so a misspelled option can never be silently ignored and charged for.

Safe retries: the Idempotency-Key header

This endpoint charges before it answers, so a request that times out or fails with a 5xx on the way back may already have been charged. To retry it safely, send an optional Idempotency-Key header: any opaque token of 1–255 printable ASCII characters with no spaces or commas (a UUID is fine), unique per logical request. Repeating the same request with the same key returns the job the first attempt created and charges nothing more.

# Requires Python 3. Run once per verification; on retry, run only curl again.
KEY=$(python3 -c 'import uuid; print(uuid.uuid4())') || exit 1
test -n "$KEY" || exit 1

curl -X POST https://api.kawaa.com/v1/verify \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

• After dispatch, a repeat answers 200 with "idempotent_replay": true, the receipt's current job_id, "credits_used": 0 and the "status": "pending" shape. Read the result or refund for that attempt from GET /v1/jobs/{job_id}. The request claims its uncharged job first; the debit, credit-ledger entry and funded job state then commit together. If a caller stops between that commit and queueing, a repeat safely finishes the interrupted enqueue and returns the normal acceptance or result shape without a second charge. Once a failed attempt is fully refunded, the same key starts a newly charged attempt under a fresh job_id; the old failed job remains terminal (until the refund completes, a repeat returns that failed job uncharged).
• A key identifies one request on this endpoint. Reusing it with a different address or options is refused with 409 IDEMPOTENCY_KEY_CONFLICT before anything is charged. A malformed key is refused with 400 INVALID_IDEMPOTENCY_KEY.
• A repeat that arrives while another request under the same key is still queueing it answers 409 CONFLICT with retryable: true and a Retry-After header. Nothing more is charged; repeat it with the same key after that delay and it returns the job.
• Keys are scoped to your account and to this endpoint, and a repeat is answered with the receipt's current job for as long as that job is kept (the data retention of the plan it was submitted under); only the fully refunded rotation described above changes that current job. The receipt itself lasts at least 30 days and never less than the job, so a repeat that arrives after the job's retention period has ended (after 7 days on the Free plan) is refused with 410 IDEMPOTENT_JOB_EXPIRED and charges nothing, rather than buying the same work twice; a new key runs it again. Two requests racing with the same key produce one charge and one job.
• Without the header, an identical request (same address, same options other than timeout_ms, same include_activity) that arrives while an earlier one from your account is still being verified joins it instead of paying again: it gets that verification's result, or the same pending shape and job_id, with "credits_used": 0 and "idempotent_replay": true. A verification counts as in flight until it has its answer, and for at most 15 minutes after its charge. Once it has its answer, an identical request is charged as usual (0.5 credits from cache, 1 for a fresh check); only a key makes a later retry free. The Node and Python SDKs send a key automatically on every verify and batch call from 0.2.0 and retry only requests that carry one; earlier releases and the other SDKs do not.

Example request

curl -X POST https://api.kawaa.com/v1/verify \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "include_activity": true,
    "options": {
      "deep_verify": true,
      "include_ai": true
    }
  }'

This request runs on every plan. To also receive the enrichment block, add "enrich": true inside options. That option requires the Business plan or higher, and sending it without one returns 403 instead of a verification result.

Response

An address on a domain that accepts all mail, shown with every optional block populated. A catch_all result has its own status (it is never folded into risky), and its quality_score is capped at 60. enrichment appears only when you send options.enrich on a Business-or-higher plan, activity only with include_activity, and ai only when AI analysis returns something to report. A cached result ("from_cache": true) is answered on the spot and its response has no job_id. From October 7, 2026 it is still recorded as a single-verification job, like a fresh one: it is listed by GET /v1/jobs and counts as one verification and one API call in your usage and analytics. Cached answers from before October 7, 2026 appear in Credit history but not in verification counts.

{
  "success": true,
  "data": {
    "job_id": "5e809a8a-1d1a-4c92-86f8-2b7395e5d803",
    "email": "john@example.com",
    "status": "catch_all",
    "sub_status": "catch_all",
    "quality_score": 60,
    "verification": {
      "syntax_valid": true,
      "domain_exists": true,
      "mx_found": true,
      "mx_records": ["mx1.example.com", "mx2.example.com"],
      "smtp_check": true,
      "catch_all": true,
      "greylisted": false,
      "smtp_code": 250,
      "smtp_message": "250 2.1.5 Recipient OK"
    },
    "flags": {
      "disposable": false,
      "role_account": false,
      "free_provider": false,
      "spam_trap": false,
      "abuse_email": false,
      "honeypot": false,
      "complainer": false,
      "bot_generated": false
    },
    "domain_info": {
      "domain": "example.com",
      "provider_type": "corporate",
      "auth_score": 84,
      "auth_grade": "B",
      "has_spf": true,
      "spf_policy": "SoftFail",
      "has_dmarc": true,
      "dmarc_policy": "Quarantine",
      "has_dkim": true
    },
    "enrichment": {
      "first_name": "John",
      "full_name": "John",
      "gender": "male",
      "country": "United States",
      "country_code": "US"
    },
    "ai": {
      "catch_all_confidence": 35
    },
    "activity": {
      "level": "active",
      "score": 78,
      "last_activity_at": "2026-01-15T10:30:00Z",
      "engagement": { "open_count": 12, "click_count": 5, "reply_count": 1 },
      "deliverability": { "bounce_count": null, "complaint_count": null },
      "confidence": 80,
      "data_points": 18
    },
    "credits_used": 1,
    "credits_remaining": 4998,
    "from_cache": false,
    "processing_time_ms": 1345,
    "verified_at": "2026-02-03T14:22:15.123Z",
    "classifier_version": 7,
    "request_id": "2a4104cd-ef74-4412-89e2-a4859a72bd11"
  }
}

Response fields

Every field a completed result can carry. A field marked as omitted is absent from the JSON rather than null, so read it with a default. Fields are added without a version change; unknown ones are informational.

{
  "success": true,
  "data": {
    "job_id": "8f14e45f-ceea-467a-9a1f-2b0c8f9c4a11",
    "email": "user@example.com",
    "status": "pending",
    "message": "Verification is still in progress. 1 credit is held while processing; if the worker fails before producing a result, job reconciliation refunds it. Use GET /v1/jobs/{job_id} to check status.",
    "credits_held": 1,
    "credits_used": 1,
    "credits_remaining": 4998,
    "request_id": "6b0f3c55-27d4-4a5e-9f43-0c1d2e3f4a5b"
  }
}

Credits