Quick start

KAWAA_REQUEST_KEY=$(python3 -c 'import uuid; print(uuid.uuid4())') || exit 1
test -n "$KAWAA_REQUEST_KEY" || exit 1
export KAWAA_REQUEST_KEY

# Refuse to send until the operation key is set in this terminal.
: "${KAWAA_REQUEST_KEY:?Set KAWAA_REQUEST_KEY before running this request}"

curl --fail-with-body --max-time 65 -X POST https://api.kawaa.com/v1/verify \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: $KAWAA_REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

// Reusing the environment value also preserves the key across script reruns.
const requestKey = process.env.KAWAA_REQUEST_KEY;
if (!requestKey) throw new Error('Set KAWAA_REQUEST_KEY before running this request');

const response = await fetch('https://api.kawaa.com/v1/verify', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Idempotency-Key': requestKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ email: 'test@example.com' }),
  signal: AbortSignal.timeout(65_000),
});

if (!response.ok) {
  throw new Error(`Verification request failed: HTTP ${response.status}`);
}
const result = await response.json();
console.log(result);

import os
import requests

# Refuse to send without the operation key; reuse it on script reruns.
request_key = os.environ['KAWAA_REQUEST_KEY']
if not request_key:
    raise ValueError('Set KAWAA_REQUEST_KEY before running this request')

response = requests.post(
    'https://api.kawaa.com/v1/verify',
    headers={
        'X-Api-Key': 'YOUR_API_KEY',
        'Idempotency-Key': request_key,
    },
    json={'email': 'test@example.com'},
    timeout=(5, 65),
)

response.raise_for_status()
print(response.json())

{
  "success": true,
  "data": {
    "email": "test@example.com",
    "status": "invalid",
    "sub_status": "no_mx",
    "quality_score": 10,
    "verification": {
      "syntax_valid": true,
      "domain_exists": true,
      "mx_found": false,
      "greylisted": false
    },
    "flags": {
      "disposable": false,
      "role_account": false,
      "free_provider": false,
      "spam_trap": false,
      "abuse_email": false,
      "honeypot": false,
      "complainer": false,
      "bot_generated": false
    }
  }
}