Email validation · Use cases · Signup forms
Use case
Signup form email validation, before the account exists.
One call on submit tells you whether the address is real, mistyped, disposable or a shared inbox. You allow, challenge or block the registration, and the user never receives a message from the check.
At the form
One request, four possible answers.
Try one address.
The same endpoint your form would call. 10 free checks a day, no key and nothing sent to the address.
Or try
What an unchecked signup costs you.
Dead accounts from mistyped emails
Free-tier seats handed to abusers
A user table that lies
Wasted activation sends
How it works at the form.
Three steps, on submit, once per registration.
User submits the registration form
Your backend calls the API
You act on the verdict, then create the account
What to do with each verdict.
The API returns the status and the per-signal detail behind it. The decision stays yours.
Status
What it means
What to do at the form
Format, MX, and SMTP all confirm the mailbox accepts mail.
Allow. Create the account and send the activation email.
Deliverable but unconfirmed at the mailbox. Catch-all domains land here.
Challenge. Create the account but add friction: require email confirmation before granting full access. Do not hard-block a real customer over a catch-all domain.
Bad format, no MX records, or the server rejected the address. The mailbox does not exist.
Block. Reject the submission at the form and ask the user to correct the address. This is where typos like name@gmial.com get caught.
The destination server would not give a clear answer, usually because it blocks verification probes.
Allow with a soft flag. Confirm the address with your activation email instead of blocking a registration you cannot judge.
Four rules for the form itself.
Validate on submit, not on every keystroke
No message is ever sent to the user
Handle unknown gracefully
Catch typos while the user is still there
What does the API response look like?
One POST from your form handler. The status drives your branch; the signals underneath tell you why.
// in your registration handler
const check = await fetch(
"https://api.trueguard.io/v2/email/validation",
{
method: "POST",
headers: {
"X-API-KEY": process.env.TRUEGUARD_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({ email })
}
).then((r) => r.json());
if (check.deliverability.status === "invalid") {
return reject("Please check your email address");
}{
"email": "name@gmail.com",
"rawEmail": "name@gmail.com",
"syntax": { "isValid": true },
"deliverability": {
"status": "safe",
"isSmtpValid": true,
"isMxValid": true,
"isCatchall": false,
"isInboxFull": false,
"isDeliverable": true,
"isDisabled": false,
"mxRecords": [
"gmail-smtp-in.l.google.com",
"alt1.gmail-smtp-in.l.google.com",
"alt2.gmail-smtp-in.l.google.com",
"alt3.gmail-smtp-in.l.google.com",
"alt4.gmail-smtp-in.l.google.com"
]
},
"domain": {
"name": "gmail.com",
"age": 11363,
"isLive": true,
"isRisky": false
},
"quality": {
"isDisposable": false,
"isFree": true,
"isRole": false,
"isSubaddress": false
}
}Frequently asked questions.
Still deciding? Contact support or read the API reference.
Should I validate on keystroke or on submit?
On submit. Validating on every keystroke fires against half-typed addresses, feels noisy, and burns quota. On submit the check runs once, against the value the user actually intends to use.
Does the user get an email from the check?
No. The SMTP step is a handshake that stops before delivery. We ask the destination server whether it will accept the address and stop there. Nothing is queued, sent, or delivered.
What should I do with an unknown result?
Never hard-block on it. Unknown means the mail server blocked the check or did not answer clearly, not that the user did anything wrong. Let the account through with a soft flag and lean on your activation email.
How much latency does this add to registration?
Median response is under a second. Slow destination mail servers push it higher, so set a timeout in your form handler and decide what happens on timeout: usually allow with a flag rather than block a real customer.
Can I block disposable addresses but allow free providers?
Yes. The response carries separate flags for disposable and free provider, so you can block throwaway domains while letting Gmail and Outlook through untouched.
Is this different from the checkbox confirmation email?
It runs before the account exists. Confirmation emails only tell you an address was reachable after you already created the row and sent a message. Validation at the form stops the row being created at all.
Clean signups from the first one.
100 validations a month, free, no card. Add one call to your form handler and the fake addresses stop becoming accounts.
Get your free API keyNo credit card required.
