Poll a pending verification

GET /v1/email-verifications/{id}?timeout=30

Returns the same two shapes as the create call: 200 with status: "completed" and the result once the check has finished, or 202 with status: "pending" and a fresh poll_after_ms while it is still in flight.

Query parameters

Parameter	Type	Default	Description
timeout	integer	none	Seconds to hold the request open waiting for the result, from 1 to 90. Values above 90 are treated as 90. A value that is not a positive whole number returns 400 {"error":"Invalid timeout"}.

Without timeout the call answers immediately with the current state, so wait poll_after_ms between calls. With timeout it returns 200 as soon as the result lands, or 202 (with a Location header) if the check is still running when the timeout runs out. One call with timeout=30 replaces a polling loop for most addresses.

cURL

curl "https://api.tryverifyemail.com/v1/email-verifications/5f1c9d2e-8b1a-4f5e-9c3d-2a7b6e4d1f08?timeout=30" \
  -H "Authorization: Bearer sk_your_api_key"

Node.js

async function verify(email) {
  const headers = {
    Authorization: `Bearer ${process.env.VERIFYEMAIL_API_KEY}`,
    "Content-Type": "application/json",
  };
  let res = await fetch("https://api.tryverifyemail.com/v1/email-verifications?timeout=25", {
    method: "POST",
    headers,
    body: JSON.stringify({ email }),
  });
  let body = await res.json();
  while (body.status === "pending") {
    await new Promise((r) => setTimeout(r, body.poll_after_ms));
    res = await fetch(
      `https://api.tryverifyemail.com/v1/email-verifications/${body.id}?timeout=25`,
      { headers },
    );
    body = await res.json();
  }
  return body.result;
}

Python

import os, time, requests

BASE = "https://api.tryverifyemail.com/v1/email-verifications"
HEADERS = {"Authorization": f"Bearer {os.environ['VERIFYEMAIL_API_KEY']}"}

def verify(email):
    params = {"timeout": 25}
    body = requests.post(BASE, headers=HEADERS, params=params, json={"email": email}).json()
    while body["status"] == "pending":
        time.sleep(body["poll_after_ms"] / 1000)
        body = requests.get(f"{BASE}/{body['id']}", headers=HEADERS, params=params).json()
    return body["result"]

An id that is not yours, or that never existed, reads as pending rather than 404. Ids are unguessable, so only poll ids you received from a create call.

Polling is one of three ways to collect a verdict after a 202. You can also send the same POST again, which returns the same id and costs no second credit only while the check is still pending (once it has finished, a repeat POST starts a new check and costs a new credit), or read your history.

See also

• Verify an email — the create call that hands you the id
• The result object — what a completed check returns
• Verify a single email — overview