How do I customize the widget?

Field targeting:

By default (autoAttach: true), the widget attaches to all inputs of type email and any input whose name or id contains “email”. You can narrow or fully control this:

• • fieldSelector: "#myField" — attach only to elements matching this CSS selector
• • autoAttach: false — disable auto-attach entirely; call VerifySwift.attachToField(el) manually

// Manual attach example
var VerifySwiftConfig = { siteKey: "YOUR_SITE_KEY", autoAttach: false };

// After page load:
VerifySwift.attachToField(document.getElementById("signupEmail"));

See also How do I integrate into my forms? for the data-verifyswift-ignore and data-verifyswift HTML attributes.

Blocking rules:

These flags control which email types are rejected. When a siteKey is present, the rules are enforced server-side as well as in the widget — they cannot be bypassed by disabling JavaScript. Defaults are shown.

• • blockDisposable: true — Block known disposable providers (Mailinator, Guerrilla Mail, etc.)
• • blockDisposablePatterns: true — Block Gmail-style aliases on free providers — usernames containing a dot or + sign (e.g. [email protected]). See Alias fine-tuning below to allow specific patterns back in.
• • blockRole: false — Block role-based addresses (info@, admin@, support@, sales@, noreply@, etc.)
• • blockFree: false — Block free email providers (Gmail, Yahoo, Outlook, etc.)
• • blockRelay: true — Block email relay/forwarding services that hide the real destination

var VerifySwiftConfig = {
  siteKey: "YOUR_SITE_KEY",
  blockRole: true,
  blockFree: true,
  blockRelay: false // relay blocking is on by default; disable if needed
};

Alias fine-tuning:

When blockDisposablePatterns is true (the default), any free-provider username containing a dot or + is blocked. Use these options to selectively allow patterns back:

• • allowPlus: true — Allow + tags (e.g. [email protected])
• • allowDots: true — Allow dots (e.g. [email protected])
• • allowMultipleDots: true — Allow multiple consecutive dots in the username
• • customUsernamePattern: "regex" — Provide your own regex; usernames that do not match are blocked

var VerifySwiftConfig = {
  blockDisposablePatterns: true,
  allowDots: true, // [email protected] passes
  allowPlus: false // [email protected] is still blocked
};

Typo suggestions:

showSuggestions: true (default) — when the API detects a likely domain typo (e.g. gmial.com), the widget shows a clickable “Did you mean gmail.com?” prompt beneath the field. Clicking it corrects the value and triggers a fresh validation. Set to false to disable entirely.

Timing:

• • debounceMs: 500 — How many milliseconds to wait after the user stops typing before triggering validation. Minimum is 300ms. Lower values give faster feedback; higher values reduce API calls on slow connections.
• • pollInterval: 10000 — For Send to Verify integrations only: how often (in ms) the widget polls the server to check whether the visitor has sent their confirmation email. Default is 10 seconds.

Status messages (customMessages):

All user-facing messages can be overridden. Only keys you specify are replaced; the rest use their defaults. The placeholders {suggestion} and {address} are substituted at runtime.

Free widget messages:

• • invalidSyntax — default: “Please enter a valid email address”
• • noMx — default: “This email domain cannot receive emails”
• • disposable — default: “Disposable email addresses are not allowed”
• • disposablePattern — default: “Email aliases (+ or dots) are not allowed”
• • roleAccount — default: “Role-based email addresses are not allowed”
• • freeProvider — default: “Please use a business email address”
• • relay — default: “Email relay services are not allowed”
• • suggestion — default: “Did you mean {suggestion}?”
• • apiError — default: “Validation service unavailable”

Integration mode messages:

• • checking — default: “Checking...”
• • verified — default: “✓ Email verified”
• • sendTo — default: “✉ Send an email from this address to {address} to verify”

var VerifySwiftConfig = {
  siteKey: "YOUR_SITE_KEY",
  customMessages: {
    checking: "Validating…",
    verified: "All good!",
    freeProvider: "Please use your work email address."
  }
};

Integration error messages (integrationErrors):

In integration mode, the server returns an error code when verification fails. The widget maps each code to a user-facing message. Override individual codes via integrationErrors — unspecified codes keep their defaults.

• • invalid — default: “This email address doesn’t exist.”
• • invalid_syntax — default: “Invalid email format.”
• • no_mx_records — default: “Email domain doesn’t accept mail.”
• • disposable — default: “Disposable email addresses are not allowed.”
• • risky — default: “Email address could not be verified.”
• • catch_all — default: “Email address could not be verified.”
• • inbox_full — default: “Email inbox is full.”
• • spamtrap — default: “Email address is not allowed.”
• • invalid_key — default: “Invalid site key or unauthorized domain.”
• • service_unavailable — default: “Verification service unavailable. Please try again.”
• • awaiting_confirmation — default: “Please verify your email before submitting.”
• • free_provider — default: “Please use a business email address.” — returned when blockFree: true and the server confirms a free provider
• • role_account — default: “Role-based email addresses are not allowed.” — returned when blockRole: true
• • relay — default: “Email relay services are not allowed.” — returned when blockRelay: true
• • disposable_pattern — default: “Email aliases are not allowed.” — returned when blockDisposablePatterns: true and the username contains a dot or +
• • invalid_pattern — default: “Email format not allowed.” — returned when customUsernamePattern is set and the username does not match

var VerifySwiftConfig = {
  siteKey: "YOUR_SITE_KEY",
  integrationErrors: {
    invalid: "We couldn’t find that address. Please double-check it.",
    catch_all: "We’re unable to confirm this address automatically.”
  }
};

Callbacks:

Two callbacks let you react to validation events in your own JavaScript code:

• • onValidate: function(email, result) — fired after every validation call with the email string and the raw API result object. Useful for analytics or conditional UI.
• • onSuggestion: function(original, suggestion) — fired when the widget detects and displays a typo suggestion, with the original value and the suggested correction.

var VerifySwiftConfig = {
  siteKey: "YOUR_SITE_KEY",
  onValidate: function(email, result) {
    console.log("Validated:", email, result);
  },
  onSuggestion: function(original, suggestion) {
    console.log("Suggested", suggestion, "for", original);
  }
};