# Block bad emails on any form with RocketShield

Source: https://docs.rocketverifier.com/integrations/widget

> 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.

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.

## Install RocketShield

**Step 1. Create a shield**

Open [RocketShield](https://app.rocketverifier.com/dashboard/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.

**Step 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.

**Step 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:

```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>
```

**Step 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](https://docs.rocketverifier.com/integrations/shopify), [BigCommerce](https://docs.rocketverifier.com/integrations/bigcommerce), [Webflow](https://docs.rocketverifier.com/integrations/webflow) and [WordPress](https://docs.rocketverifier.com/integrations/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.

| Result | Default | Shield rule |
| --- | --- | --- |
| Broken syntax | Blocked | Always on. Checked in the browser, no credit used. |
| `undeliverable`, including DNS errors and an unavailable mailbox server | Blocked | Always on. |
| Disposable address | Blocked | **Block disposable**, on by default. |
| Toxic address (offensive words, placeholders and keyboard mashes in the local part) | Blocked | **Block toxic**, on by default. |
| Free provider, such as gmail.com | Pass | **Block 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 domain | Warning (`risky`) | **Block catch all**, off by default. |
| `unknown` | Pass | **Block unknown**, off by default. |
| Any other `risky` result | Warning | None. |
| `deliverable` | Pass | None. |

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 setting | Default | What it does |
| --- | --- | --- |
| Allowed domains | Required | Hostnames 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 rules | See the table above | Which results stop the form. |
| Blocked message | "Valid business email is required." | Shown under the field and as the browser's validation message. |
| Prevent form submit | On | Stops the form while an email field is blocked. Off shows the message without stopping the form. |
| Field selector | Empty | A CSS selector for the fields to check. Empty checks every `input[type="email"]`. |
| Rate limit | 25 | Checks per page view per hour, 1 to 100. See below. |
| Hide "Powered by RocketVerifier" | Off | Removes the badge under the field. |
| Debug mode | Off | Logs 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:

```html
<script type="text/javascript">
  var rocketShieldConfig = {
    apikey: "rs_your_shield_key",
    blockFreeProvider: true,
    blockRoleBased: true,
    blockedMessage: "Please use your work email.",
  };
</script>
```

| Option | Effect |
| --- | --- |
| `apikey` | Required. The shield key. |
| `blockDisposable`, `blockRoleBased`, `blockFreeProvider`, `blockCatchAll`, `blockUnknown`, `blockToxic` | `true` turns the rule on for this page. `false` has no effect, so a page can never loosen the shield. |
| `blockedMessage` | Replaces 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:

```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:

```js
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`:

| Method | What 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. |
| `version` | The 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](https://docs.rocketverifier.com/api/verify#credits).
- **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](https://app.rocketverifier.com/dashboard/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](https://docs.rocketverifier.com/guides/signup-verification).

## 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.
