Verify at sign-up

Stop typos, dead domains and disposable addresses at the form, without making real users wait.

  1. The form posts to your server. The API key never reaches the browser.
  2. Your server calls POST /verify with "mode": "basic" and a short timeout.
  3. Reject invalid, apply your policy to disposable domains and accept the rest.
  4. If the call fails or times out, accept the sign-up and verify later.
  5. Send your confirmation email as usual.
JavaScript / TypeScript
// 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, a 402 or a 5xx must never cost you a real user. Accept and verify later.
  • Never treat unknown as invalid. In basic mode unknown is the answer for every healthy domain.
  • Keep your confirmation email. valid says 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 basic mode 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.

View this page as Markdown