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

Verifox.init() Options

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

Render a tooltip message directly below the email input on validation failure (or success if messages.valid is set).

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

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

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    redHighlight: true,13    lang: "en",14    messages: {15      disposable: "Disposable emails are not allowed.",16      free: "Please use a work email address.",17      valid: "Email looks good!",18      warning: "This email may not be deliverable."19    },20    onValid: function(e) { console.log("valid", e.email); },21    onInvalid: function(e) { console.log("blocked", e.email, e.reason); }22  });23</script>
200 - Response
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>
200 - Response
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-disposable="..."           // Override disposable message9data-verifox-msg-free="..."                 // Override free-email message10data-verifox-msg-valid="..."               // Override valid message11data-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});
200 - Response
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.

Query Parameters

emailstring*

Email address to validate

api_keystring*

Your FoxGuard widget API key (from dashboard)

1curl -X GET "https://api.verifox.ai/v1/widget/[email protected]&api_key=foxkey_your_full_key" \2  -H "X-API-Key: vfx_your_api_key"
200 - Response
1{2  "success": true,3  "result": {4    "email": "[email protected]",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}
POST

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.

Request Body

emailstring*

Email address to verify

fingerprintstringopt

Browser fingerprint string for rate limiting. If omitted, falls back to IP-based limiting.

1curl -X POST "https://api.verifox.ai/v1/widget/public-verify" \2  -H "X-API-Key: vfx_your_api_key" \3  -H "Content-Type: application/json" \4  -d '{"email": "[email protected]", "fingerprint": "fp_abc123"}'
200 - Response
1{2  "success": true,3  "remaining": 3,4  "result": {5    "email": "[email protected]",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}