Use cases
Verify emails at signup
In short
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.
On this page
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>:
<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 covers every option, styling and platform plugins, including 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 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_typowarning, 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-Keyderived 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:singlescope, a monthly credit limit and, on servers with fixed addresses, an IP allowlist. A runaway loop stops at the cap. See authentication. - Let the verdict catch bots.
toxicflags machine-generated local parts, anddo_not_mailflags 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.
// 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);# 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), 201createUser 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 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#
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.
Updated 11 November 2026Suggest an edit