Email verification in cURL

export ZAPBOUNCE_KEY="zb_live_..."

# One address.
curl -sS --fail-with-body https://app.zapbounce.com/api/v1/verify \
  -H "X-API-Key: $ZAPBOUNCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["ada@example.com"]}' | jq '.results[0]'

# Just the verdict, for a shell condition.
verdict=$(curl -sS https://app.zapbounce.com/api/v1/verify \
  -H "X-API-Key: $ZAPBOUNCE_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"emails\":[\"$1\"]}" | jq -r '.results[0].status')

case "$verdict" in
  valid)     echo "send" ;;
  catch_all) echo "segment separately: the domain accepts everything" ;;
  unknown)   echo "no verdict, credit refunded, try again tomorrow" ;;
  *)         echo "suppress" ;;
esac

API=https://app.zapbounce.com/api/v1

# Submit a job from a file of addresses, one per line (up to 50,000).
job_id=$(jq -R -s -c 'split("\n") | map(select(length > 0))' contacts.txt \
  | jq -c '{emails: ., source: "api"}' \
  | curl -sS --fail-with-body $API/jobs \
      -H "X-API-Key: $ZAPBOUNCE_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d @- | jq -r '.id')
echo "job $job_id"

# Poll until it finishes. There is no webhook.
until case "$(curl -sS $API/jobs/$job_id -H "X-API-Key: $ZAPBOUNCE_KEY" | jq -r '.status')" in
        completed|partial|failed|cancelled) true ;; *) false ;; esac; do
  sleep 10
done

# Page the rows into one JSONL file.
page=1
while :; do
  body=$(curl -sS "$API/jobs/$job_id/emails?page=$page&pageSize=100" \
    -H "X-API-Key: $ZAPBOUNCE_KEY")
  echo "$body" | jq -c '.items[]' >> results.jsonl
  [ "$page" -ge "$(echo "$body" | jq -r '.meta.totalPages')" ] && break
  page=$((page + 1))
done

# What came back unresolved (its credit was refunded).
jq -r 'select(.status == "unknown") | .email' results.jsonl | wc -l

# Or stream the whole job as CSV: email,status,reason_code,mx,smtp_code,checked_at
curl -sS --fail-with-body $API/jobs/$job_id/export \
  -H "X-API-Key: $ZAPBOUNCE_KEY" -o results.csv

# --fail-with-body: non-zero exit AND the error body, which -f alone swallows.
# --max-time: a timeout (exit 28) is not a bad address, so fail open as unknown.
if ! response=$(curl -sS --fail-with-body --max-time 10 \
      https://app.zapbounce.com/api/v1/verify \
      -H "X-API-Key: $ZAPBOUNCE_KEY" \
      -H "Content-Type: application/json" \
      -d '{"emails":["ada@example.com"]}'); then
  [ $? -eq 28 ] && { echo '{"status":"unknown","reasonCode":"TIMEOUT"}'; exit 0; }
  code=$(echo "$response" | jq -r '.code')            # body: statusCode, code, message, requestId
  request_id=$(echo "$response" | jq -r '.requestId')
  echo "failed: $code (requestId=$request_id)" >&2
  [ "$code" = "CREDITS_INSUFFICIENT" ] && exit 2      # 422, retrying will not help
  exit 1
fi

# Retry with backoff on a 429. There is no Retry-After header, so wait on the
# window length from X-RateLimit-Window-Seconds.
attempt=0
while [ $attempt -lt 5 ]; do
  http_code=$(curl -sS -D /tmp/zb.headers -o /tmp/zb.json -w '%{http_code}' \
    https://app.zapbounce.com/api/v1/verify \
    -H "X-API-Key: $ZAPBOUNCE_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"emails\":[\"$1\"]}")
  [ "$http_code" = "200" ] && break
  [ "$(jq -r '.code' /tmp/zb.json)" = "CREDITS_INSUFFICIENT" ] && { echo "out of credits" >&2; exit 2; }
  window=$(grep -i '^x-ratelimit-window-seconds:' /tmp/zb.headers | tr -dc '0-9')
  sleep $(( ${window:-1} * (2 ** attempt) ))
  attempt=$(( attempt + 1 ))
done
jq '.results[0]' /tmp/zb.json