API Reference · v1

FoxGuard Widget

Drop-in real-time email validation for any HTML form. Add two script tags before </head> — FoxGuard auto-discovers every [type="email"] input and validates as the user types. No backend changes. Supports a free public tier (4 req/day) and unlimited with an API key. The key is public in your page HTML, so lock it to your domains when you create it — off-domain requests are rejected with 403.

Base URLapi.verifox.ai/v1Rate limit60 req/minFormatJSON over HTTPSLatency~380ms

Get Started Free

Guide

Parameter	Type	Required	Description
`apiKey`	`string`	Optional · undefined	Your FoxGuard widget API key. Without a key, falls back to the public tier (4 verifications/day per device). Get yours at verifox.ai/dashboard/foxguard.
`apiUrl`	`string`	Optional · "https://api.verifox.ai"	Verifox API base URL the widget calls. Auto-detected from the widget.js <script src>, so you rarely need to set it — override only for self-hosted or proxied setups.
`selector`	`string`	Optional · "input[type=\"email\"]"	CSS selector targeting the email inputs to protect. Supports any valid CSS selector — multiple with commas.
`blockDisposable`	`boolean`	Optional · true	Reject throwaway / temporary email services (Mailinator, Guerrilla Mail, 10MinuteMail, and 10,000+ others).
`blockFree`	`boolean`	Optional · false	Reject free consumer email providers: Gmail, Yahoo, Outlook, Hotmail, iCloud, etc. Use for B2B sign-up forms that require work emails.
`blockSubmit`	`boolean`	Optional · true	Automatically prevent the enclosing <form> from submitting while a blocked email (invalid / disposable / free) is present. Set false to handle submission yourself via onInvalid or data-verifox-status.
`redHighlight`	`boolean`	Optional · true	Apply a red border and light red background to the input field when validation fails. Matches the field's existing border-radius.
`showTooltip`	`boolean`	Optional · true	Show the verdict as plain text directly below the email input on validation failure (or success if messages.valid is set). Set false for icon-only.
`showIcon`	`boolean`	Optional · true	Show a small status icon inside the right edge of the email field (checking, valid, risky, blocked, disposable). The widget adds right padding so text never runs under it. Set false for text-only.
`lang`	`"en" \| "it" \| "es" \| "fr" \| "de"`	Optional · "en"	Language for the built-in default messages. Ignored if you provide custom messages.* values.
`messages.invalid`	`string`	Optional · "Please enter a valid email address"	Custom tooltip copy shown when the address is not a real, deliverable email. Invalid addresses are always blocked.
`messages.disposable`	`string`	Optional · "Disposable emails are not allowed"	Custom tooltip copy shown when a disposable email is detected and blockDisposable is true.
`messages.free`	`string`	Optional · "Please use a work email address"	Custom tooltip copy shown when a free provider is detected and blockFree is true.
`messages.valid`	`string`	Optional · undefined	Optional success message shown below the input when the email passes all checks. Leave empty to show nothing on success.
`messages.warning`	`string`	Optional · undefined	Shown for catch-all or risky emails that pass but may have deliverability issues.
`onValid`	`(e: { email: string; result: object }) => void`	Optional · undefined	Callback fired when an email passes all validation checks. Use it to unlock form submit or show custom UI.
`onInvalid`	`(e: { email: string; reason: string; result: object }) => void`	Optional · undefined	Callback fired when an email is blocked. reason is one of: 'disposable' \| 'free' \| 'invalid'. Use it to disable form submit.
`onWarning`	`(e: { email: string; result: object }) => void`	Optional · undefined	Callback fired for risky emails that are not outright blocked (catch-all, role accounts).

apiKeystringopt

Your FoxGuard widget API key. Without a key, falls back to the public tier (4 verifications/day per device). Get yours at verifox.ai/dashboard/foxguard.

apiUrlstringopt

Verifox API base URL the widget calls. Auto-detected from the widget.js <script src>, so you rarely need to set it — override only for self-hosted or proxied setups.

selectorstringopt

CSS selector targeting the email inputs to protect. Supports any valid CSS selector — multiple with commas.

blockDisposablebooleanopt

Reject throwaway / temporary email services (Mailinator, Guerrilla Mail, 10MinuteMail, and 10,000+ others).

blockFreebooleanopt

Reject free consumer email providers: Gmail, Yahoo, Outlook, Hotmail, iCloud, etc. Use for B2B sign-up forms that require work emails.

blockSubmitbooleanopt

Automatically prevent the enclosing <form> from submitting while a blocked email (invalid / disposable / free) is present. Set false to handle submission yourself via onInvalid or data-verifox-status.

redHighlightbooleanopt

Apply a red border and light red background to the input field when validation fails. Matches the field's existing border-radius.

showTooltipbooleanopt

Show the verdict as plain text directly below the email input on validation failure (or success if messages.valid is set). Set false for icon-only.

showIconbooleanopt

Show a small status icon inside the right edge of the email field (checking, valid, risky, blocked, disposable). The widget adds right padding so text never runs under it. Set false for text-only.

lang"en" | "it" | "es" | "fr" | "de"opt

Language for the built-in default messages. Ignored if you provide custom messages.* values.

messages.invalidstringopt

Custom tooltip copy shown when the address is not a real, deliverable email. Invalid addresses are always blocked.

messages.disposablestringopt

Custom tooltip copy shown when a disposable email is detected and blockDisposable is true.

messages.freestringopt

Custom tooltip copy shown when a free provider is detected and blockFree is true.

messages.validstringopt

Optional success message shown below the input when the email passes all checks. Leave empty to show nothing on success.

messages.warningstringopt

Shown for catch-all or risky emails that pass but may have deliverability issues.

onValid(e: { email: string; result: object }) => voidopt

Callback fired when an email passes all validation checks. Use it to unlock form submit or show custom UI.

onInvalid(e: { email: string; reason: string; result: object }) => voidopt

Callback fired when an email is blocked. reason is one of: 'disposable' | 'free' | 'invalid'. Use it to disable form submit.

onWarning(e: { email: string; result: object }) => voidopt

Callback fired for risky emails that are not outright blocked (catch-all, role accounts).

1<!-- 1. Load the widget script -->2<script src="https://api.verifox.ai/v1/widget/widget.js"></script>34<!-- 2. Initialize with your config -->5<script>6  Verifox.init({7    apiKey: "foxkey_your_full_key",8    blockDisposable: true,9    blockFree: false,10    blockSubmit: true,11    showTooltip: true,12    showIcon: true,13    redHighlight: true,14    lang: "en",15    messages: {16      disposable: "Disposable emails are not allowed.",17      free: "Please use a work email address.",18      valid: "Email looks good!",19      warning: "This email may not be deliverable."20    },21    onValid: function(e) { console.log("valid", e.email); },22    onInvalid: function(e) { console.log("blocked", e.email, e.reason); }23  });24</script>

1// widget.js returns the FoxGuard JavaScript SDK.2// Once loaded, window.Verifox is available with these methods:34Verifox.init(options)      // Initialize — call once on page load5Verifox.reattach()         // Re-scan DOM for new inputs (SPA use)6Verifox.validate(email)    // Manually validate an email string7Verifox.destroy()          // Remove all listeners and tooltips

Guide

1<!-- Protect only the signup form's email input -->2<script>3  Verifox.init({4    apiKey: "foxkey_your_full_key",5    selector: "#signup-form input[type='email']"6  });7</script>

1// data-verifox-* attribute reference:23data-verifox-ignore="true"               // Skip this input entirely4data-verifox-block-disposable="true|false"  // Override blockDisposable5data-verifox-block-free="true|false"        // Override blockFree6data-verifox-red-highlight="true|false"     // Override redHighlight7data-verifox-show-tooltip="true|false"      // Override showTooltip8data-verifox-msg-invalid="..."              // Override invalid message9data-verifox-msg-disposable="..."           // Override disposable message10data-verifox-msg-free="..."                 // Override free-email message11data-verifox-msg-valid="..."               // Override valid message12data-verifox-msg-warning="..."             // Override warning message

Guide

1const form = document.getElementById("signup-form");2const emailInput = document.getElementById("email");34Verifox.init({5  apiKey: "foxkey_your_full_key",6  blockDisposable: true,7  blockFree: true,8  onInvalid: function({ email, reason }) {9    // Mark the input as blocked10    emailInput.dataset.verifoxBlocked = "true";11  },12  onValid: function({ email }) {13    delete emailInput.dataset.verifoxBlocked;14  }15});1617form.addEventListener("submit", function(e) {18  // Check data attribute set by widget19  if (emailInput.dataset.verifoxStatus === "invalid") {20    e.preventDefault();21    alert("Please enter a valid work email.");22    return;23  }2425  // Or check the blocked flag you set in onInvalid26  if (emailInput.dataset.verifoxBlocked === "true") {27    e.preventDefault();28  }29});

1// After validation, FoxGuard sets these attributes on the input element:23data-verifox-status="valid"     // Email passed all checks4data-verifox-status="invalid"   // Email was blocked (disposable/free/unreachable)5data-verifox-status="warning"   // Email is risky but not blocked6data-verifox-status="pending"   // Validation in progress78// The reason string passed to onInvalid:9"disposable"   // Matched a known disposable provider10"free"         // Matched a free provider (when blockFree: true)11"invalid"      // Failed SMTP / syntax / MX check

GET

Widget Validate (API)

/v1/widget/validate

The REST endpoint the widget calls internally when an API key is present. You can also call this directly from your own JavaScript — useful for custom validation flows outside of form inputs. Does not deduct credits from your main balance.

Parameter	Type	Required	Description
`email`	`string`	Required	Email address to validate
`api_key`	`string`	Required	Your FoxGuard widget API key (from dashboard)

emailstring*

Email address to validate

api_keystring*

Your FoxGuard widget API key (from dashboard)

Try it

1curl -X GET "https://api.verifox.ai/v1/widget/validate?email=john@example.com&api_key=foxkey_your_full_key"

1{2  "success": true,3  "result": {4    "email": "john@example.com",5    "domain": "example.com",6    "status": "safe",7    "isValid": true,8    "isFree": false,9    "isRole": false,10    "isDisposable": false,11    "suggestion": null,12    "smtp": {13      "deliverable": true,14      "catchAll": false,15      "hostExists": true16    }17  }18}

Public Verify (No Auth)

/v1/widget/public-verify

Free public email verification — no API key or login required. Rate-limited to 4 verifications per day per browser fingerprint. This is what the widget uses when no apiKey is provided. Does not deduct credits.

Parameter	Type	Required	Description
`email`	`string`	Required	Email address to verify
`fingerprint`	`string`	Optional	Accepted for backwards compatibility and then ignored. The 4/day cap is keyed on client IP alone — bots rotate fingerprints to reset a per-device limit, so sending one neither raises nor lowers your remaining count.

emailstring*

Email address to verify

fingerprintstringopt

Accepted for backwards compatibility and then ignored. The 4/day cap is keyed on client IP alone — bots rotate fingerprints to reset a per-device limit, so sending one neither raises nor lowers your remaining count.

Try it

1curl -X POST "https://api.verifox.ai/v1/widget/public-verify" \2  -H "Content-Type: application/json" \3  -d '{"email": "john@example.com"}'

1{2  "success": true,3  "remaining": 3,4  "result": {5    "email": "john@example.com",6    "status": "safe",7    "isValid": true,8    "isFree": false,9    "isRole": false,10    "isDisposable": false,11    "suggestion": null,12    "domainAgeDays": 10432,13    "domainCreated": "1997-12-09T00:00:00Z",14    "smtp": {15      "deliverable": true,16      "catchAll": false,17      "hostExists": true18    }19  }20}

FoxGuard Widget

Verifox.init() Options

Widget Validate (API)

Query Parameters

Try it

Public Verify (No Auth)

Request Body

Try it