Email verification in Node.js

const KEY = process.env.ZAPBOUNCE_KEY;

async function verify(email) {
  const res = await fetch("https://app.zapbounce.com/api/v1/verify", {
    method: "POST",
    headers: {
      "X-API-Key": KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ emails: [email] }),
    signal: AbortSignal.timeout(10_000), // fetch has no default. Set one.
  });

  if (!res.ok) {
    const err = await res.json(); // { statusCode, code, message, requestId }
    throw Object.assign(new Error(err.message), { code: err.code, status: res.status, requestId: err.requestId });
  }
  const { results } = await res.json();
  return results[0];
}

const r = await verify("ada@example.com");

switch (r.status) {
  case "valid":     await send(r.email); break;
  case "catch_all": await queueSeparately(r.email); break;   // accepts every address
  case "unknown":   await retryTomorrow(r.email); break;     // credit refunded, not a verdict
  default:          await suppress(r.email);
}

if (r.flags.includes("disposable")) await suppress(r.email);

const API = "https://app.zapbounce.com/api/v1";
const headers = { "X-API-Key": KEY, "Content-Type": "application/json" };
const DONE = new Set(["completed", "partial", "failed", "cancelled"]);

async function submitJob(emails) {
  const res = await fetch(`${API}/jobs`, {
    method: "POST",
    headers: { ...headers, "Idempotency-Key": crypto.randomUUID() }, // a lost response must not bill twice
    body: JSON.stringify({ emails, source: "api" }), // up to 50,000 per job
    signal: AbortSignal.timeout(30_000),
  });
  return res.json();
}

/** There is no webhook: poll the job until it reaches a terminal status. */
async function waitForJob(id, everyMs = 5000) {
  for (;;) {
    const job = await fetch(`${API}/jobs/${id}`, { headers, signal: AbortSignal.timeout(30_000) })
      .then((r) => r.json());
    if (DONE.has(job.status)) return job;
    await new Promise((r) => setTimeout(r, everyMs));
  }
}

/** Async iterator over the pages, so callers can for-await without buffering. */
async function* jobRows(id) {
  let page = 1, totalPages = 1;
  do {
    const res = await fetch(`${API}/jobs/${id}/emails?page=${page}&pageSize=100`, {
      headers,
      signal: AbortSignal.timeout(30_000),
    }).then((r) => r.json());

    yield* res.items;
    totalPages = res.meta.totalPages;
  } while (page++ < totalPages);
}

const { id } = await submitJob(emails);
await waitForJob(id);
for await (const row of jobRows(id)) {
  await db.contacts.update(row.email, { verdict: row.status });
}

async function withRetry(fn, attempts = 5) {
  for (let i = 0; ; i++) {
    try {
      return await fn();
    } catch (err) {
      // CREDITS_INSUFFICIENT (422) will fail the same way forever. Do not burn retries on it.
      if (err.code === "CREDITS_INSUFFICIENT" || err.status === 400) throw err;
      if (i >= attempts - 1) throw err;

      // RATE_LIMITED (429) carries no Retry-After. Back off from the window length instead.
      const windowS = err.windowSeconds ?? 1;
      // Jitter matters: a fleet retrying in lockstep just rebuilds the spike.
      const wait = Math.min(2 ** i * 500 * windowS, 60_000) * (0.5 + Math.random());
      await new Promise((r) => setTimeout(r, wait));
    }
  }
}
// In verify(), on a 429 add: windowSeconds: Number(res.headers.get("X-RateLimit-Window-Seconds"))

// AbortError from a timeout is not a bad address. At signup, fail open.
try {
  return await withRetry(() => verify(email));
} catch (err) {
  if (err.name === "TimeoutError" || err.name === "AbortError") {
    return { email, status: "unknown", reasonCode: "TIMEOUT", flags: [] };
  }
  throw err;
}