Vetto API documentation

<script src="https://usevetto.com/v.js" data-site="pk_xxxxxxxxxxxxxxxxxxxx" defer></script>

<script src="https://usevetto.com/v.js" data-site="pk_xxxxxxxxxxxxxxxxxxxx"
        data-forms="#signup-form" defer></script>

curl -X POST https://usevetto.com/v1/check \
  -H "Authorization: Bearer $VETTO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@mailinator.com"}'

{
  "ok": true,
  "verdict": "block",
  "message": "Please use a permanent email address. Temporary inboxes are not accepted.",
  "suggestion": null,
  "reasons": [{ "code": "disposable", "action": "block" }],
  "tags": [],
  "repeat": 0,
  "token": null,
  "branding": false
}

// Fail open: a timeout or network error never blocks a real signup.
export async function vettoVerdict(email) {
  try {
    const res = await fetch('https://usevetto.com/v1/check', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.VETTO_SECRET_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email }),
      signal: AbortSignal.timeout(2500),
    });
    const v = await res.json();
    return v.ok ? v.verdict : 'allow';
  } catch {
    return 'allow';
  }
}

curl -X POST https://usevetto.com/v1/verify \
  -H "Authorization: Bearer $VETTO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "<vetto_token from the form>", "email": "jane@gmail.com"}'

{
  "ok": true,
  "valid": true,
  "reason": null,
  "verdict": "allow",
  "reasons": [],
  "repeat": 0,
  "expiresAt": 1792336800
}

import { createHmac, createHash, timingSafeEqual } from 'node:crypto';

// token = base64url(payload JSON) + "." + base64url(HMAC-SHA256(secretKey, firstPart))
export function verifyVettoToken(token, email, secretKey) {
  const [body, sig] = String(token || '').split('.');
  if (!body || !sig) return false;
  const expected = createHmac('sha256', secretKey).update(body).digest('base64url');
  if (expected.length !== sig.length || !timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) return false;
  const p = JSON.parse(Buffer.from(body, 'base64url').toString());
  const h = createHash('sha256').update(email.trim().toLowerCase()).digest('hex');
  return p.x > Date.now() / 1000 && p.v !== 'block' && p.h === h;
}

curl -X POST https://usevetto.com/v1/audit \
  -H "Content-Type: application/json" \
  -d '{"domains": ["mailinator.com", "gmail.com", "doesnotexist-xyz-123.com"]}'

{
  "ok": true,
  "results": {
    "mailinator.com": { "status": "skipped", "mx": [], "disposable": true },
    "gmail.com": { "status": "ok", "mx": [], "disposable": false },
    "doesnotexist-xyz-123.com": { "status": "nxdomain", "mx": [], "disposable": false }
  }
}