Skip to content
RocketVerifierDOCS

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 widgetServer-side POST /v1/verify
Where it runsIn the browser, on your formOn your server, before you create the account
SetupPaste one script tagOne HTTP call in your signup handler
CredentialPublic rs_ key, locked to your domainsSecret API key, never in the browser
FeedbackAs the person types, under the fieldOn submit, from your own error message
Stops bots posting directly to your backendNoYes
Best forNo-code sites, WordPress, Shopify, WebflowApps 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
<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:

PathTypical time
Decided by syntax, DNS, list checks or cacheUnder 400 ms
Live SMTP mailbox check1 to 3 seconds
Your ceiling, with timeout: 55 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.

ResultActionMessage to show
deliverableAccept
undeliverable with did_you_meanBlock"Did you mean maya@gmail.com?"
undeliverable (any other)Block"This address can't receive email. Please check it."
disposableBlock"Please use a permanent email address."
risky + toxic, possible_trap, do_not_mailBlock"Please use a different email address."
risky + possible_typoWarn, 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
unknownAccept, 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_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.
  • 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.

// 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);

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 with an rv_test_ key to exercise every branch for free:

AddressExpected action
deliverable@sandbox.rocketverifier.comAccept
undeliverable@sandbox.rocketverifier.comBlock
disposable@sandbox.rocketverifier.comBlock, permanent address message
admin@sandbox.rocketverifier.comAccept (role address)
risky@sandbox.rocketverifier.comAccept (catch-all, send_with_caution)
unknown@sandbox.rocketverifier.comAccept 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