How to add email validation to your signup form

Checking an address as it is typed is the best place to catch problems: the person is still there and can fix it. Here is a pattern that works for most forms.

The architecture

Don't call the verification API from the browser. Your API key would be visible to anyone. Instead:

1. The browser submits the form to your server.
2. Your server calls the verification API with the secret key.
3. Your server decides what to do and replies to the browser.

The request

curl -X POST https://YOUR-HOST/api/v1/verify \
  -H "Authorization: Bearer ev_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "maria@gmial.com"}'

The response includes the fields you need:

{
  "status": "risky",
  "score": 65,
  "reason": "possible_typo",
  "suggestion": "maria@gmail.com",
  "disposable": false,
  "role": false
}

Server-side example (Node)

async function checkEmail(email) {
  const res = await fetch("https://YOUR-HOST/api/v1/verify", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MAILSURE_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email }),
    signal: AbortSignal.timeout(5000),
  });
  if (!res.ok) return { status: "unknown" }; // fail open
  return res.json();
}

Decide what each result does

Result	Suggested action
valid	Accept
invalid	Reject, ask for another address
risky with a suggestion	Show "Did you mean …?" and let the user accept or keep theirs
risky and disposable	Reject if you offer a trial or coupon, otherwise accept
risky (role, catch-all)	Accept, but tag the contact
unknown	Accept. The check didn't complete

Three rules that save you pain

1. Fail open. If the API is slow or errors, let the signup through and verify later. A verification outage must never stop customers from signing up.
2. Set a short timeout. Five seconds is plenty for the user waiting on the form.
3. Never block on unknown. It means "couldn't tell", not "bad".

Handle limits properly

Honour 429 responses by waiting for the Retry-After header, and treat 402 as "out of credits" (alert yourself, accept the signup). The API docs list every status code.

Keep the form friendly

Explain errors in plain words ("That domain doesn't seem to receive email") rather than "invalid". If you suggest a correction, make it one click. And never reveal more than you need to: a message about the address, not about your fraud rules.

Related: real-time vs bulk verification and stopping fake signups.