Verify at sign-up
Stop typos, dead domains and disposable addresses at the form, without making real users wait.
The recommended pattern
- The form posts to your server. The API key never reaches the browser.
- Your server calls
POST /verifywith"mode": "basic"and a short timeout. - Reject
invalid, apply your policy to disposable domains and accept the rest. - If the call fails or times out, accept the sign-up and verify later.
- Send your confirmation email as usual.
// Decides what to do with the address typed in a sign-up form. Run it on your server.
async function checkSignupEmail(email) {
let response;
try {
response = await fetch("https://api.salchimail.com/v1/verify", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SALCHIMAIL_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ email, mode: "basic" }),
signal: AbortSignal.timeout(3000), // never keep the form waiting
});
} catch {
return "accept"; // timeout or network error: fail open and verify later
}
if (!response.ok) {
// 429, 402 or 5xx must not cost you a sign-up. A 400 or 401 is a bug on your side: log it.
console.error("SalchiMail answered", response.status, response.headers.get("X-Request-Id"));
return "accept";
}
const { verdict, reason_code } = await response.json();
if (verdict === "invalid") return "reject"; // bad syntax or a domain that cannot receive mail
if (reason_code === "disposable_domain") return "reject"; // your policy: could also be "review"
return "accept"; // "unknown" is the normal basic answer: the domain can receive mail
}
console.log(await checkSignupEmail("ana@example.com"));Timings
| Mode | Typical answer | Suggested client timeout | Where to run it |
|---|---|---|---|
basic |
Well under a second | 3 seconds | Inline, while the form is submitted |
mailbox |
Up to 30 seconds | Above 30 seconds | In a background job, after the sign-up |
basic never contacts the mail server, which is why it is fast. mailbox talks to the recipient's server: if it cannot finish in 30 seconds the API answers 503 verification_timeout and charges nothing. Do not hold a sign-up form open for a mailbox check.
If you want mailbox certainty for new users, run a mailbox verification from a background job once the account exists, and act on the result before your first campaign.
What to do with each result
Result in basic mode |
Meaning | Suggested action |
|---|---|---|
invalid · syntax_invalid |
Not an email address | Ask the user to correct it |
invalid · domain_not_found, domain_null_mx, domain_no_mail_host |
The domain cannot receive mail. Often a typo | Ask the user to check the domain |
risky · disposable_domain |
Throwaway address | Reject or ask for another address, by your policy |
risky · legacy_domain |
Domain of a discontinued provider | Ask for another address |
unknown · mailbox_not_checked |
The domain can receive mail. This is the normal answer | Accept |
unknown · dns_temporary, address_unsupported |
The check could not be done | Accept |
flags.free tells you the domain is a free webmail provider. It is informational and does not change the verdict.
To show a message to the user, map reason_code to your own copy. reason is a ready-made explanation in English or, with the header Accept-Language: es, in Spanish.
Rules that keep sign-ups safe
- Fail open. A timeout, a
429, a402or a5xxmust never cost you a real user. Accept and verify later. - Never treat
unknownasinvalid. Inbasicmodeunknownis the answer for every healthy domain. - Keep your confirmation email.
validsays the server accepts the address. It does not prove the person owns it or reads it. - Re-submits are cheap. Verifying the same address again within 30 days in
basicmode is free, so a user who submits the form twice is charged once. - Retries are safe with an
Idempotency-Key.
See Verdicts and reason codes for the complete list and Limits and errors for rate limits.