# Verify at sign-up

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

## The recommended pattern

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**

```js
// 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`](https://docs.salchimail.com/idempotency.md).

See [Verdicts and reason codes](https://docs.salchimail.com/verdicts.md) for the complete list and [Limits and errors](https://docs.salchimail.com/limits-and-errors.md) for rate limits.
