Developers

One request at signup, one clear decision

Call the API from your server at signup time: you know whether to block the address and whether to grant the promo offer. Answers in milliseconds.

Get a free key API reference

curl -X POST https://api.useksar.com/v1/check-email \
  -H "x-api-key: $KSAR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"email":"[email protected]","event":"signup","offer":"welcome_discount"}'

const res = await fetch('https://api.useksar.com/v1/check-email', {
  method: 'POST',
  headers: { 'x-api-key': process.env.KSAR_API_KEY, 'content-type': 'application/json' },
  body: JSON.stringify({ email, event: 'signup', offer: 'welcome_discount' }),
});
const { block, offer } = await res.json();

r = requests.post("https://api.useksar.com/v1/check-email",
    headers={"x-api-key": os.environ["KSAR_API_KEY"]},
    json={"email": email, "event": "signup", "offer": "welcome_discount"}, timeout=2)
decision = r.json()["offer"]["decision"]

$ch = curl_init('https://api.useksar.com/v1/check-email');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['x-api-key: ' . getenv('KSAR_API_KEY'), 'content-type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['email' => $email, 'event' => 'signup'])]);
$result = json_decode(curl_exec($ch), true);

200 OK

{
  "block": false,
  "risk_score": 6,
  "duplicate": { "status": "exact", "count": 2 },
  "offer": { "decision": "deny", "reasons": ["duplicate_exact"] }
}

Quick start

Live in three steps

1
Create an account
Free signup, no credit card. Your API key is shown once: copy it.
2
Keep the key server-side
Store it in an environment variable (KSAR_API_KEY). It must never appear in a browser or a mobile app.
3
Make the first call
Send the address with event "signup" at signup time, then apply block and offer.decision. The dashboard has a "Test now" button.

Response

The fields to use

The full response is described in the reference; these fields are enough to decide.

Field	Values	Meaning
block	boolean	true: refuse the signup (disposable address, domain without email…).
risk_score	0–100	Risk score of the address; block is true above your threshold.
reasons	string[]	Detected reasons (disposable_domain, no_mx, duplicate_exact…).
duplicate.status	none · exact · series	The same person (or a series of similar addresses) already signed up.
offer.decision	grant · defer · deny	Grant the promo offer, put it on hold (granted later) or deny it.
mode	enforce · shadow	shadow: test mode, nothing is blocked; real decisions are in shadow.
degraded	boolean	true if an internal dependency was unavailable: answer with the available signals.
not_included	string[]	Features not included in your plan (duplicates, promo offer decision…).

Best practices

An integration that never breaks your form

Server-side only
The key gives access to your account: never call from a browser or a mobile app.
Short timeout, then let it through
Use a 2-second timeout. On error, timeout or unexpected answer, accept the signup: your form must never go down because of the API.
Quota reached (429)
quota_exceeded: let signups through until the reset (resets_at) or upgrade; you are warned by email at 80% and 100%. rate_limit_exceeded: honour Retry-After.
Signup or simple check
event "signup" records the signup (duplicates, reports); event "check" analyses without recording anything. Add external_id to match your accounts.
Promo offer on hold
With offer.decision "defer", grant the promo offer later: send the events (email confirmed, first purchase) to /v1/signups/{signup_id}/events.

Example: call with timeout and fallback

// Called by your server at signup.
async function checkSignup(email) {
  try {
    const res = await fetch('https://api.useksar.com/v1/check-email', {
      method: 'POST',
      headers: { 'x-api-key': process.env.KSAR_API_KEY, 'content-type': 'application/json' },
      body: JSON.stringify({ email, event: 'signup', offer: 'welcome_discount' }),
      signal: AbortSignal.timeout(2000),
    });
    if (!res.ok) return { block: false, offer: 'grant' }; // 429, 5xx : let it through
    const data = await res.json();
    return { block: data.block, offer: data.offer.decision };
  } catch {
    return { block: false, offer: 'grant' }; // timeout or network: let it through
  }
}

Errors

Error codes

HTTP	error	What to do
400	invalid_email	Syntactically invalid address: ask the user to fix it.
401	invalid_api_key	Missing, revoked or invalid key: check the environment variable.
403	insufficient_scope	The key lacks the required scope (check or admin).
403	plan_upgrade_required	Feature not included in your plan (report, CSV audit).
403	account_suspended	Account suspended: contact us; let signups through.
429	rate_limit_exceeded	Too many requests per minute: honour Retry-After.
429	quota_exceeded	Monthly quota reached: let signups through.
503	service_unavailable	Service temporarily unavailable: let signups through.

Sandbox

Try every feature without an account

A fictitious customer of your own for 24 hours: signups, rules, report in euros, file audit and GDPR erasure.

Open the sandbox API reference

One request at signup, one clear decision

Live in three steps

Create an account

Keep the key server-side

Make the first call

The fields to use

An integration that never breaks your form

Server-side only

Short timeout, then let it through

Quota reached (429)

Signup or simple check

Promo offer on hold

Error codes

Try every feature without an account