Widget install and troubleshooting

The SendSure widget lets you validate addresses before a form submission reaches your app or CRM. A correct install is mostly about loading the script once and targeting the right field.

Choose an install path

There are two common paths:

1. Direct embed in your site template
2. Google Tag Manager when marketing or growth teams control deployment

Use one or the other for a given page. Running both usually creates duplicate initialization and inconsistent behavior.

Platform quick starts

Every platform uses the same two-script embed from the dashboard's Widget page — only where you paste it changes.

React / Next.js

Add the config and loader with next/script in your root layout (App Router) or _app (Pages Router). Because the widget scans the DOM once on load, call window.SendSure.rescan() after client-side route changes or whenever a form mounts dynamically — otherwise late-rendered inputs are never attached.

WordPress

Paste the snippet into your theme header using a Custom HTML block or a header-scripts plugin. WPForms, Contact Form 7, and Elementor forms work automatically — the widget auto-detects email inputs.

Webflow

Site settings → Custom Code → Head, paste the snippet, then publish. Webflow form email fields are auto-detected.

Shopify

Edit your theme code and paste the snippet into theme.liquid just before </head>. The widget attaches to newsletter and checkout-adjacent forms automatically.

Configuration reference

All options live on window.SendSureConfig next to your API key:

• blockGeneric (default true) — block free providers like Gmail and Yahoo
• showFeedback (default true) — show inline validation messages below the input
• preventSubmit (default true) — block form submission for invalid addresses
• branding (default true) — show a small "by SendSure" link in the feedback message; set false to hide it
• debounceMs (default 600) — delay before verifying while the visitor types
• selector (default auto-detect) — CSS selector to target specific inputs

Slow verifications and request dedup

Two behaviors are built in and need no configuration:

• Deferred results. If a verification takes longer than the server's deadline (rare — usually a slow receiving mail server), the widget shows a soft "Taking longer than usual — you can continue." message. It never blocks the form for this, and it automatically re-checks once a few seconds later to pick up the finished verdict.
• Request dedup. The widget caches results per page session and shares in-flight requests, so repeated checks of the same address (typing, blur, submit) cost one credit per unique email per page session — never one per event.

Direct embed checklist

Make sure the script loads after the form field exists in the DOM, or initialize only after the page is interactive.

Confirm:

• the page includes the correct API key or widget config
• the form selector matches the real form
• the email input selector matches the real field
• no second script injects another instance

GTM checklist

When installing through GTM:

• fire on the intended pages only
• verify the tag is not duplicated in another container
• inspect the final rendered page to confirm only one widget script exists

GTM issues often look like product issues, but the failure is usually in tag timing or duplicate load behavior.

Why validation does not fire

The most common causes are:

• the form selector does not match after a frontend refactor
• the email field name changed
• the script loaded before the field rendered
• the form is replaced dynamically after the widget attaches

If your UI is client-rendered, recheck any delayed or dynamically mounted form components.

How to test the install

Run these checks in order:

1. Open the page and confirm the script is present.
2. Type a known-invalid address and confirm the widget intercepts the form.
3. Try a valid-looking address and confirm normal submission still works.
4. Check the browser console for duplicate initialization or selector errors.

When to ask for help

If validation still does not fire, capture:

• the page URL
• whether you used direct embed or GTM
• the form framework or site builder
• any console errors

Then open the support widget. That context cuts debugging time dramatically.