Verify email domains in Node.js, step by step

Node ships a global fetch, based on the undici HTTP client ². The check is one POST with a JSON body holding either email or domain, and your key in the Authorization header.

1curl -X POST https://YOUR_API_HOST/v1/email-domain-check \
2  -H "Authorization: Bearer $LOOKVALID_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"email":"info@example.com"}'

A fetch() promise does not reject when the server answers with an error status such as 404 or 504. It rejects only when the request itself fails, for example on a network error, and a handler must check Response.ok or Response.status ¹. So two kinds of failure need two code paths: an exception for the network, and a status check for everything the API says.

The API answers HTTP 200 whether or not it found something. For a domain that does not exist in DNS, the body has found: false and a reason, and nothing is charged. Do not route that through your error path: it is a result, and for a signup form it usually means "ask the person to retype the address".

Every failure uses one envelope: an error object with code, message, fix, docs_url, retryable and request_id. Branch on code, and use retryable rather than guessing from the status. Each code has a page under errors.

Status 429 means the client has sent too many requests in a given amount of time, and the server may say how long to wait with Retry-After ⁴. That field holds either an HTTP-date or a number of seconds ³. Our API sends whole seconds, and the function reads them. Successful responses also carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (a Unix time in seconds), which let a batch job slow down before it is refused. The current limit is on the rate limits page.

1const API = 'https://YOUR_API_HOST';
2const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
3​
4export async function checkEmail(email, maxAttempts = 4) {
5  for (let attempt = 1; ; attempt++) {
6    let res;
7    try {
8      res = await fetch(API + '/v1/email-domain-check', {
9        method: 'POST',
10        headers: {
11          Authorization: 'Bearer ' + process.env.LOOKVALID_API_KEY,
12          'Content-Type': 'application/json',
13        },
14        body: JSON.stringify({ email }),
15      });
16    } catch (networkError) {
17      if (attempt >= maxAttempts) throw networkError;
18      await sleep(500 * 2 ** attempt);
19      continue;
20    }
21    const body = await res.json().catch(() => ({}));
22    if (res.status === 200) return body;
23    const err = body.error ?? {};
24    if (res.status === 429 && attempt < maxAttempts) {
25      await sleep((Number(res.headers.get('Retry-After')) || 1) * 1000);
26      continue;
27    }
28    if (err.retryable && attempt < maxAttempts) {
29      await sleep(500 * 2 ** attempt);
30      continue;
31    }
32    throw Object.assign(new Error(err.message ?? 'request failed'), { code: err.code, status: res.status, requestId: err.request_id });
33  }
34}
35​
36console.log(await checkEmail('info@example.com'));

1. Save the function as an ES module, for example check.mjs.
2. Export LOOKVALID_API_KEY in your shell.
3. Run node check.mjs and read the found and data fields.

For the full response fields, open the email domain check product page, or start from the quickstart.