Skip to content
RocketVerifierDOCS

Websites and forms

Block bad emails on any form with RocketShield

In short

Create a shield in the dashboard, add your site's domains to it, and paste two script tags before the closing body tag. RocketShield checks every email field as the visitor types, blocks undeliverable, disposable and toxic addresses by default, and stops the form until the address passes. Each check costs 1 credit and unknown results are free.

On this page

RocketShield is a small script that verifies email fields in real time. It finds every input[type="email"] on the page, including fields added later by single-page apps, shows the result under the field, and stops the form while the address is blocked.

Cost
1 credit per check
Unknown results
Free
Key
Public rs_ shield key
Script
widget/v2.js

Install RocketShield#

  1. Create a shield

    Open RocketShield in the dashboard and create a shield. Give it a name, add every domain the form runs on under Allowed domains, and choose the blocking rules and message.

  2. Copy the key

    The dashboard shows the shield key (rs_...) and the embed code when the shield is created. Copy it then: afterwards the dashboard shows only the key's prefix. Rotate key issues a new one at any time.

  3. Paste the snippet

    Paste the embed code before the closing </body> tag of every page with a form, or in your site builder's footer code:

    HTML
    <script type="text/javascript">
      var rocketShieldConfig = {
        apikey: "rs_your_shield_key",
      };
    </script>
    <script type="text/javascript" src="https://app.rocketverifier.com/widget/v2.js"></script>
  4. Test it

    Type a sandbox address into the form, such as disposable@sandbox.rocketverifier.com or undeliverable@sandbox.rocketverifier.com. Sandbox addresses return fixed results for free on every shield.

Platform guides wrap the same snippet: Shopify, BigCommerce, Webflow and WordPress.

What gets blocked and what gets a warning#

Every result lands in one of three states. A blocked address shows the shield's message in red and stops the form; a warning shows in amber and lets the form submit; a pass shows in green.

ResultDefaultShield rule
Broken syntaxBlockedAlways on. Checked in the browser, no credit used.
undeliverable, including DNS errors and an unavailable mailbox serverBlockedAlways on.
Disposable addressBlockedBlock disposable, on by default.
Toxic address (offensive words, placeholders and keyboard mashes in the local part)BlockedBlock toxic, on by default.
Free provider, such as gmail.comPassBlock free domain, off by default. Turn it on for B2B forms.
Role address, such as info@ or sales@Warning (risky)Block role-based, off by default.
Catch-all domainWarning (risky)Block catch all, off by default.
unknownPassBlock unknown, off by default.
Any other risky resultWarningNone.
deliverablePassNone.

The blocked message is the shield's message; the dashboard fills in "Valid business email is required." for new shields.

Options#

Rules, message and behaviour are set on the shield in the dashboard, so you change them without touching the site. The script loads them from the shield every time a page opens.

Shield settingDefaultWhat it does
Allowed domainsRequiredHostnames the key works on. example.com also covers its subdomains, and *.example.com covers subdomains explicitly. A request from any other site is refused.
Blocking rulesSee the table aboveWhich results stop the form.
Blocked message"Valid business email is required."Shown under the field and as the browser's validation message.
Prevent form submitOnStops the form while an email field is blocked. Off shows the message without stopping the form.
Field selectorEmptyA CSS selector for the fields to check. Empty checks every input[type="email"].
Rate limit25Checks per page view per hour, 1 to 100. See below.
Hide "Powered by RocketVerifier"OffRemoves the badge under the field.
Debug modeOffLogs the loaded settings and each result to the browser console.

The script waits 500 ms after the last keystroke before it checks, and checks again when the field loses focus.

Make rules stricter for one site#

rocketShieldConfig accepts overrides that can only tighten the shield's rules, which is useful when one shield serves several sites:

HTML
<script type="text/javascript">
  var rocketShieldConfig = {
    apikey: "rs_your_shield_key",
    blockFreeProvider: true,
    blockRoleBased: true,
    blockedMessage: "Please use your work email.",
  };
</script>
OptionEffect
apikeyRequired. The shield key.
blockDisposable, blockRoleBased, blockFreeProvider, blockCatchAll, blockUnknown, blockToxictrue turns the rule on for this page. false has no effect, so a page can never loosen the shield.
blockedMessageReplaces the message on this page, up to 200 characters.

Check extra fields#

Add data-rocketshield to any input to check it too, for example a text field that holds an email:

HTML
<input type="text" name="work_email" data-rocketshield />

React to results in your own code#

RocketShield fires two events on the input, and both bubble up to the form:

JavaScript
document.addEventListener("rocketshield:verified", (event) => {
  const { email, result } = event.detail;
  console.log(email, result.status, result.score);
});

document.addEventListener("rocketshield:blocked", (event) => {
  analytics.track("signup_email_blocked", { reason: event.detail.result.reason });
});

result has email, status, reason, score, provider, domain (name, acceptAll, disposable, free) and the booleans is_disposable, is_free_provider, is_catch_all, is_role_based and is_toxic.

The script also exposes window.RocketShield:

MethodWhat it does
verify(email)Checks an address and returns the result. Cached per page.
isValid(email)true when a checked address passes the rules.
getResult(email)The cached result, or null.
clearCache()Forgets cached results.
init()Scans the page for new fields.
getConfig()The settings loaded from the shield.
versionThe script version.

Rate limit#

The rate limit caps how many addresses one page view checks: 25 per hour by default, set from 1 to 100 on the shield. The count lives in the page, counts only real checks (cached results and syntax errors are free), and starts again an hour after the page opened. When a page reaches the limit, further addresses are not checked and the form submits normally.

Shield requests are not throttled by IP on the server; the allowed domains and this per-page limit are what protect your credits. Pair RocketShield with a CAPTCHA or your own server-side throttle on forms that attract bots.

Pricing#

  • 1 credit for every deliverable, undeliverable and risky result, the same as the API.
  • Free: unknown results, addresses on your own suppression list, sandbox addresses, syntax errors and repeat checks of the same address in a page.
  • When the balance is below 1 credit, checks stop and forms submit normally until you buy credits.

The dashboard shows each shield's checks, blocked and allowed counts.

Troubleshooting#

  • Nothing happens: open the console with debug mode on. A missing apikey logs a warning and the script does nothing.
  • Checks fail on one site: the site's hostname is not in Allowed domains. Add the exact domain, including staging hosts such as store.myshopify.com or site.webflow.io.
  • A field is not checked: it is not type="email". Add data-rocketshield, or set a field selector on the shield.
  • Server-side check needed too: see verify at signup.

Frequently asked questions

Is the shield key a secret?

No. The rs_ key is public by design and only works from the domains listed on the shield. Never put a secret rv_live_ API key in a web page.

What happens if the API is unreachable or my credits run out?

The form keeps working. RocketShield clears its message and lets the visitor submit, so an outage never blocks real signups. Keep a server-side check for addresses that must be verified.

Does retyping the same address cost again?

No. Results are cached in the page, so the same address is checked once per page view.

Can a visitor bypass RocketShield?

A visitor who turns off JavaScript skips any browser check. For signups that matter, verify again on your server with the API or use a platform plugin that checks on submit, such as WordPress or Magento.

Updated 11 November 2026Suggest an edit