# Verify emails at signup

Source: https://docs.rocketverifier.com/guides/signup-verification

> Check every new address before you create the account. Drop in the RocketShield script for instant feedback with no backend code, and call POST /v1/verify from your server with a 5 second timeout to enforce the decision. Block undeliverable, disposable and toxic addresses, offer did_you_mean for typos, and accept unknown results so a slow mail server never stops a real signup.

A fake or mistyped address at signup costs you twice: the person never gets your welcome email, and every later bounce hurts your sender reputation. Checking the address while the person is still on the page fixes both.

## Pick an approach

Use RocketShield for instant feedback in the browser, the server-side check to enforce the rule, or both together.

| | RocketShield widget | Server-side `POST /v1/verify` |
| --- | --- | --- |
| Where it runs | In the browser, on your form | On your server, before you create the account |
| Setup | Paste one script tag | One HTTP call in your signup handler |
| Credential | Public `rs_` key, locked to your domains | Secret API key, never in the browser |
| Feedback | As the person types, under the field | On submit, from your own error message |
| Stops bots posting directly to your backend | No | Yes |
| Best for | No-code sites, WordPress, Shopify, Webflow | Apps with their own signup endpoint |

The strongest setup uses both: RocketShield helps people fix mistakes before they submit, and the server check enforces the decision for every request that reaches your backend.

## Add RocketShield

Create a shield in the dashboard under **RocketShield**, add the domains it runs on, and paste the embed code before `</body>`:

HTML:

```html
<script>
  var rocketShieldConfig = {
    apikey: "rs_your_public_key",
  };
</script>
<script src="https://app.rocketverifier.com/widget/v2.js"></script>
```

RocketShield finds the email fields on the page, verifies as the person types and blocks the submit for the result types you choose in the shield's settings, such as disposable, undeliverable or toxic addresses. The [RocketShield guide](https://docs.rocketverifier.com/integrations/widget) covers every option, styling and platform plugins, including [WordPress](https://docs.rocketverifier.com/integrations/wordpress).

## Set a latency budget

A signup check has to be fast, and it has to give up gracefully. Plan for these times:

| Path | Typical time |
| --- | --- |
| Decided by syntax, DNS, list checks or cache | Under 400 ms |
| Live SMTP mailbox check | 1 to 3 seconds |
| Your ceiling, with `timeout: 5` | 5 seconds |

Send `timeout` in the request body, in seconds (3 to 60, default 10, capped at 30). When the mail server has not answered by then, the API returns `unknown`, which is free, and you accept the signup. Give your own HTTP client a few seconds more than `timeout`, so the API always answers first.

## Decide what to block and what to warn

Block only what is certainly wrong or harmful, warn when the person can fix it, and accept everything else. Accepting an `unknown` result is always right at signup: the person is real until proven otherwise.

| Result | Action | Message to show |
| --- | --- | --- |
| `deliverable` | Accept | |
| `undeliverable` with `did_you_mean` | Block | "Did you mean maya@gmail.com?" |
| `undeliverable` (any other) | Block | "This address can't receive email. Please check it." |
| `disposable` | Block | "Please use a permanent email address." |
| `risky` + `toxic`, `possible_trap`, `do_not_mail` | Block | "Please use a different email address." |
| `risky` + `possible_typo` | Warn, let them continue | "Did you mean maya@gmail.com?" |
| `risky` + `catch_all` with `catch_all_verdict: "avoid"` | Warn | "Please double-check this address." |
| `risky` (any other) | Accept | |
| `unknown` | Accept, re-check later | |

[Reading results](https://docs.rocketverifier.com/results) explains every `sub_status` behind these rules.

## Offer typo suggestions

`did_you_mean` holds a full corrected address, such as `maya@gmail.com` for `maya@gmial.com`. Show it as a one-click fix, and let the person decide.

- Never rewrite the address silently: the suggestion fixes the domain, and only the person knows their mailbox.
- After they accept the suggestion, verify the new address too.
- On a `possible_typo` warning, let them keep the original. Some typo-like domains are real.

## Protect the check from abuse

A public signup form is an open door. Keep the verification behind it cheap and safe:

- **Check on submit, not on every keystroke,** and only after a basic syntax check in your own code.
- **Rate limit your signup endpoint** per IP address, and put a captcha in front of it if bots find it.
- **Send an `Idempotency-Key`** derived from the address and the day. Repeat submissions of the same address return the stored result for 24 hours and are not charged again.
- **Give the signup service its own key** with only the `verify:single` scope, a monthly credit limit and, on servers with fixed addresses, an IP allowlist. A runaway loop stops at the cap. See [authentication](https://docs.rocketverifier.com/authentication).
- **Let the verdict catch bots.** `toxic` flags machine-generated local parts, and `do_not_mail` flags known complainers.

## Full server example

This handler verifies the address with a 5 second budget, applies the table above, and fails open when the API cannot answer.

Node.js:

```js
// npm install express
import crypto from "node:crypto";
import express from "express";

const app = express();
app.use(express.json());

const BLOCK = new Set(["disposable", "toxic", "possible_trap", "do_not_mail"]);
const MESSAGES = {
  disposable: "Please use a permanent email address.",
  default: "This address can't receive email. Please check it.",
  abuse: "Please use a different email address.",
};

async function verifyEmail(email) {
  const day = new Date().toISOString().slice(0, 10);
  const idempotencyKey = crypto.createHash("sha256").update(`${email}:${day}`).digest("hex");
  try {
    const res = await fetch("https://api.rocketverifier.com/v1/verify", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.ROCKETVERIFIER_API_KEY}`,
        "Content-Type": "application/json",
        "Idempotency-Key": idempotencyKey,
        "RocketVerifier-Version": "2026-11-01",
      },
      body: JSON.stringify({ email, timeout: 5 }),
      signal: AbortSignal.timeout(8000),
    });
    if (!res.ok) return null; // 4xx/5xx: fail open
    return await res.json();
  } catch {
    return null; // network error or timeout: fail open
  }
}

function decide(r) {
  if (!r || r.status === "unknown") return { action: "accept", recheck: true };
  if (r.status === "deliverable") return { action: "accept" };
  if (r.did_you_mean && r.status === "undeliverable") {
    return { action: "block", message: `Did you mean ${r.did_you_mean}?`, suggestion: r.did_you_mean };
  }
  if (r.sub_status === "disposable") return { action: "block", message: MESSAGES.disposable };
  if (r.status === "undeliverable") return { action: "block", message: MESSAGES.default };
  if (BLOCK.has(r.sub_status)) return { action: "block", message: MESSAGES.abuse };
  if (r.sub_status === "possible_typo") {
    return { action: "warn", message: `Did you mean ${r.did_you_mean}?`, suggestion: r.did_you_mean };
  }
  if (r.sub_status === "catch_all" && r.catch_all_verdict === "avoid") {
    return { action: "warn", message: "Please double-check this address." };
  }
  return { action: "accept" };
}

app.post("/signup", async (req, res) => {
  const email = String(req.body.email ?? "").trim().toLowerCase();
  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) {
    return res.status(422).json({ error: "Enter a valid email address." });
  }

  const decision = decide(await verifyEmail(email));
  if (decision.action === "block") {
    return res.status(422).json({ error: decision.message, suggestion: decision.suggestion });
  }
  if (decision.action === "warn" && !req.body.confirmed) {
    return res.status(409).json({ warning: decision.message, suggestion: decision.suggestion });
  }

  const user = await createUser({ email, password: req.body.password });
  if (decision.recheck) await queueRecheck(user.id, email);
  return res.status(201).json({ id: user.id });
});

app.listen(3000);
```

Python:

```python
# pip install flask rocketverifier
import hashlib
import os
import re
from datetime import date

from flask import Flask, jsonify, request
from rocketverifier import RocketVerifier, RocketVerifierError

app = Flask(__name__)
rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"], timeout=10, max_retries=0)

BLOCK = {"disposable", "toxic", "possible_trap", "do_not_mail"}
EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")

def verify_email(email: str):
    key = hashlib.sha256(f"{email}:{date.today().isoformat()}".encode()).hexdigest()
    try:
        return rv.verify(email, idempotency_key=key, timeout=5)
    except RocketVerifierError:
        return None  # network error, rate limit, credits or server error: fail open

def decide(r) -> dict:
    if r is None or r.status == "unknown":
        return {"action": "accept", "recheck": True}
    if r.status == "deliverable":
        return {"action": "accept"}
    if r.did_you_mean and r.status == "undeliverable":
        return {"action": "block", "message": f"Did you mean {r.did_you_mean}?", "suggestion": r.did_you_mean}
    if r.sub_status == "disposable":
        return {"action": "block", "message": "Please use a permanent email address."}
    if r.status == "undeliverable":
        return {"action": "block", "message": "This address can't receive email. Please check it."}
    if r.sub_status in BLOCK:
        return {"action": "block", "message": "Please use a different email address."}
    if r.sub_status == "possible_typo":
        return {"action": "warn", "message": f"Did you mean {r.did_you_mean}?", "suggestion": r.did_you_mean}
    if r.sub_status == "catch_all" and r.catch_all_verdict == "avoid":
        return {"action": "warn", "message": "Please double-check this address."}
    return {"action": "accept"}

@app.post("/signup")
def signup():
    body = request.get_json(force=True)
    email = str(body.get("email", "")).strip().lower()
    if not EMAIL_RE.match(email):
        return jsonify(error="Enter a valid email address."), 422

    decision = decide(verify_email(email))
    if decision["action"] == "block":
        return jsonify(error=decision["message"], suggestion=decision.get("suggestion")), 422
    if decision["action"] == "warn" and not body.get("confirmed"):
        return jsonify(warning=decision["message"], suggestion=decision.get("suggestion")), 409

    user = create_user(email=email, password=body.get("password"))
    if decision.get("recheck"):
        queue_recheck(user.id, email)
    return jsonify(id=user.id), 201
```

`createUser` and `queueRecheck` (`create_user` and `queue_recheck`) are your own functions. The re-check job verifies the address again after its `retry_after` seconds, before you send anything important.

## Test the flow

Point the handler at [sandbox addresses](https://docs.rocketverifier.com/sandbox) with an `rv_test_` key to exercise every branch for free:

| Address | Expected action |
| --- | --- |
| `deliverable@sandbox.rocketverifier.com` | Accept |
| `undeliverable@sandbox.rocketverifier.com` | Block |
| `disposable@sandbox.rocketverifier.com` | Block, permanent address message |
| `admin@sandbox.rocketverifier.com` | Accept (role address) |
| `risky@sandbox.rocketverifier.com` | Accept (catch-all, `send_with_caution`) |
| `unknown@sandbox.rocketverifier.com` | Accept and queue a re-check |

## Next steps

- [RocketShield](https://docs.rocketverifier.com/integrations/widget)
Every widget option, styling and platform plugin.
- [Reading results](https://docs.rocketverifier.com/results)
What every status and sub_status means and costs.
- [Verify endpoint](https://docs.rocketverifier.com/api/verify)
Request fields, response fields and errors.
- [Rate limits](https://docs.rocketverifier.com/rate-limits)
How many signups per minute your plan handles.

## Frequently asked questions

### Will verification slow down my signup form?

Most answers return in under 400 milliseconds because they are decided by syntax, DNS, list checks or cache. A live mailbox check typically takes 1 to 3 seconds. Set timeout to 5 and the request never takes longer; a timeout returns unknown, which is free.

### Should I block role addresses like info@ at signup?

For B2B products, usually not, because teams sign up with shared inboxes. Block them only when every account must belong to one person. RocketShield and the decision table on this page treat them as accept by default.

### What if RocketVerifier is unreachable?

Accept the signup and queue a re-check. The example on this page fails open on network errors, rate limits and server errors, so an outage never blocks a real customer.

### Is RocketShield enough on its own?

For instant feedback, yes. To enforce the rule against bots that post to your signup endpoint directly, add the server-side check as well. The two work together.

### How much does signup verification cost?

1 credit per checked address, except unknown results and addresses on your suppression list, which are free. Repeat submissions of the same address within 24 hours are free when you send the same Idempotency-Key.
