Email validation · Integrations · JavaScript
Integration guide
Email validation in JavaScript.
In this guide
How do I validate an email with JavaScript?
No SDK to install. Native fetch is available in Node 18 and up and in every current browser runtime.
Node.js, in your request handler
async function validateEmail(email) {
const res = 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 })
}
);
if (!res.ok) throw new Error(`Trueguard ${res.status}`);
return res.json();
}
const result = await validateEmail("founder@yourcompany.com");
if (result.deliverability.status === "invalid") {
// reject the submission
}One header, one body field
Set X-API-KEY to your key and POST a JSON body with a single email field. HTTPS only. The response carries the seven signals plus one deliverability status.
Response fields you will branch on
deliverability.statussafe, risky, invalid or unknown. This is the field to branch on.
syntax.isValidRFC 5322 format check. Deterministic, so a false here is always a typo or a malformed address.
quality.isDisposableTrue for throwaway providers. Usually a hard block at signup.
deliverability.isCatchallTrue when the domain accepts any address. The status is then risky, unless a second check confirmed or ruled out the mailbox.
quality.isRoleinfo@, support@, sales@. Route these differently rather than rejecting them.
Run it once before you write any code.
The same endpoint the snippet above calls. 10 free checks a day, no key needed.
Or try
Where should the call live in a JavaScript app?
Your API key is a secret. Where you put this call decides whether it stays one.
Browser (client-side)
Never call the endpoint from the browser. Anything in front-end JavaScript ships your API key to every visitor, and the quota is then spendable by anyone who opens devtools. If you need a check from the client, proxy it through your own route.
Server-side (recommended)
Call it from your Node handler, Next.js route handler, Express middleware or serverless function. The key stays in an environment variable, and you control the decision on the response before the account or lead is written.
What the endpoint returns
{
"email": "founder@yourcompany.com",
"syntax": { "isValid": true },
"deliverability": {
"status": "safe",
"isSmtpValid": true,
"isMxValid": true,
"isCatchall": false,
"isDeliverable": true,
"mxRecords": ["mx1.yourcompany.com"]
},
"domain": { "name": "yourcompany.com", "isLive": true, "isRisky": false },
"quality": {
"isDisposable": false,
"isFree": false,
"isRole": false,
"isSubaddress": false
}
}How do I handle errors and rate limits in JavaScript?
try {
const result = await validateEmail(email);
handle(result);
} catch (err) {
if (err.status === 429) {
// quota or rate limit: allow with a flag,
// do not block a real signup
return allowWithFlag(email);
}
if (err.status === 401) {
logger.error("Trueguard key rejected");
}
// network timeouts land here too
return allowWithFlag(email);
}Status
What to do
200Validation ran. Read deliverability.status and branch.
400Malformed request body. Check you are sending JSON with an email field.
401Missing or rejected API key. Log it loudly: every request is failing.
429Rate limit or monthly quota reached. Allow the user through with a flag and alert yourself; do not block real signups on your own quota.
5xxRetry once with a short backoff, then fall back to allowing with a flag.
Which JavaScript frameworks does this work with?
It is one HTTPS request, so anything that can make one works. These are the stacks people ask about.
Next.js signup route
Express middleware
Node list cleaner
Edge check in a Worker
What it costs once you ship.
Three tiers. The free plan needs no card and runs the production endpoint.
Standard
Popular$49.99 / month
50,000 validations / month
Overage: $0.001 per validation
Get your API keyFrequently asked questions
The full field reference lives in the API documentation.
Do I need an SDK?
No. There is no official JavaScript SDK and you do not need one: the endpoint is a single POST with one header and one body field. Native fetch covers it in Node 18+, and axios works identically if that is what your project already uses.
Can I call this from React or the browser?
Not directly. Your API key would be exposed to every visitor. Add a route in your own backend that takes the address, calls Trueguard server-side, and returns only the verdict your UI needs.
Does it work in Cloudflare Workers and Lambda?
Yes. Both provide fetch and both can hold the key as an environment secret. The call has no Node-specific dependencies.
What timeout should I set?
Median response is under a second, but a slow destination mail server can push it higher. Set a timeout around 3 to 5 seconds and decide what happens on timeout: usually allow with a flag rather than block a real user.
How do I test without spending quota?
The free tier covers 100 validations a month on the production endpoint, which is enough for integration work. Use the known example addresses in your test fixtures and assert on the status field rather than the whole body.
The same guide, other stacks
Validate emails from JavaScript in minutes.
100 validations a month, free, no card. Working code above, production endpoint, same response shape on every plan.
Get your free API keyNo credit card required.
