Verify an address from the browser with a publishable key

The endpoint behind the form widget (https://spaw.co/spaw-form.js). It is authenticated by a publishable pk_ key in the body plus the browser's Origin header, which must match one of the domains the key is locked to. A missing Origin is rejected on purpose: servers use a secret key and POST /api/v1/email instead.

The lookup bills the key's owner under the normal rules and answers { "success", "data" } with no meta block, so page visitors never see the owner's balance. Because the key sits in page source, give it a daily credit cap in the dashboard: once the cap is spent the endpoint answers 429 KEY_SPEND_CAP_REACHED until the next day. Free answers (undeliverable, cache hits, test addresses) never count toward the cap.

For forms open to the public, store a Cloudflare Turnstile site key and secret on the publishable key. The endpoint then requires a confirmed turnstile_token with every lookup and answers 403 TURNSTILE_FAILED without one, before any credit is spent. Tokens are single-use. The form widget obtains a fresh token per lookup when the script tag carries data-turnstile-site-key.

Throttled at 20 requests per minute per IP.

curl -X POST https://spaw.co/api/v1/email/public \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "pk_live_…",
  "email": "[email protected]"
}'

const response = await fetch('https://spaw.co/api/v1/email/public', {
  method: 'POST',
  headers: {
    'Origin': 'https://www.example.com',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "key": "pk_live_…",
    "email": "[email protected]"
  }),
});
const result = await response.json();

import requests

response = requests.post(
    'https://spaw.co/api/v1/email/public',
    headers={'Origin': 'https://www.example.com'},
    json={
        'key': 'pk_live_…',
        'email': '[email protected]'
    },
)
result = response.json()

$ch = curl_init('https://spaw.co/api/v1/email/public');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Origin: https://www.example.com', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'key' => 'pk_live_…',
        'email' => '[email protected]'
    ]),
]);
$result = json_decode(curl_exec($ch), true);

{
    "success": true,
    "data": {
        "email": "[email protected]",
        "deliverable": "deliverable",
        "reason": null,
        "risk_score": 0,
        "risk_level": "low",
        "did_you_mean": null
    }
}

{
    "success": false,
    "error": {
        "code": "INVALID_PUBLISHABLE_KEY",
        "message": "That publishable key does not exist or was revoked.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Your credit balance is empty.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "ORIGIN_NOT_ALLOWED",
        "message": "This publishable key cannot be used from this origin.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "The email field is required.",
        "errors": {
            "email": [
                "The email field is required."
            ]
        },
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "KEY_SPEND_CAP_REACHED",
        "message": "This publishable key has reached its daily credit cap. The counter resets each day.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}