Verify a batch

A batch accepts exactly one input source: an inline emails array containing 1–10000 addresses, or the listId of a ready list already stored in your account. Do not send both fields. The first accepted submission returns 202; replaying the identical body with the same Idempotency-Key returns 200, replayed: true, and the same request.id.

1. Submit and capture the request ID

curl -sS https://api.bounceless.io/v1/requests -X POST \
  -H "X-Api-Key: $BOUNCELESS_API_KEY" \
  -H "Idempotency-Key: e7b10db7-ce34-4e91-a6f5-cf102b277bd8" \
  -H "Content-Type: application/json" \
  -d '{"emails":["first@example.com","second@example.com"]}' \
  > batch-submit.json

REQUEST_ID="$(jq -er '.request.id' batch-submit.json)"

jq is required by the shell examples. Keep request and result files in access-controlled storage because they contain email addresses. To submit an existing ready list instead, keep the same headers and send only its ID:

{ "listId": "00000000-0000-4000-8000-000000000815" }

The four-route GA contract does not add a list-creation route. Create or import the list in the dashboard before using this mode.

2. Poll with a bound

The status response carries request.state, request.partial, and request.finalized. Poll at a bounded interval and stop after a fixed number of attempts:

for attempt in $(seq 1 60); do
  curl -sS "https://api.bounceless.io/v1/requests/$REQUEST_ID" \
    -H "X-Api-Key: $BOUNCELESS_API_KEY" > batch-status.json
  jq '{state: .request.state, partial: .request.partial, finalized: .request.finalized, countsMayChange: .request.countsMayChange, counters, requestId}' batch-status.json
  [ "$(jq -r '.request.finalized' batch-status.json)" = "true" ] && break
  sleep 2
done

[ "$(jq -r '.request.finalized' batch-status.json)" = "true" ] || {
  echo "Batch did not finalize within the polling budget" >&2
  exit 1
}

While partial is true, result pages are a progress view, not proof that collection is complete. countsMayChange: true means later processing can still change the counters; terminal non-finalized failures can be partial while reporting countsMayChange: false. For a complete export, wait for finalized: true, then paginate.

3. Retrieve every result with the cursor

limit accepts 1–200. cursor/nextCursor is the canonical pagination contract. Continue until nextCursor is null; treat cursors as opaque. offset remains available for compatibility but should not be used for a new full export. The script below writes pages to a temporary file and replaces the final export only after a validated terminal page. It retries 429 and temporary 5xx responses within explicit attempt and delay bounds. A permanent HTTP error, invalid JSON, missing nextCursor, repeated cursor, or page-budget overrun exits non-zero and preserves any earlier completed export.

set -euo pipefail

: "${BOUNCELESS_API_KEY:?Set BOUNCELESS_API_KEY before exporting results}"
: "${REQUEST_ID:?Run the submit step and set REQUEST_ID first}"

BOUNCELESS_API_BASE="${BOUNCELESS_API_BASE:-https://api.bounceless.io}"
RESULTS_FILE="${BATCH_RESULTS_FILE:-batch-results.jsonl}"
MAX_RETRIES="${BATCH_EXPORT_MAX_RETRIES:-4}"
RETRY_DELAY_SECONDS="${BATCH_EXPORT_RETRY_DELAY_SECONDS:-2}"
MAX_RETRY_DELAY_SECONDS="${BATCH_EXPORT_MAX_RETRY_DELAY_SECONDS:-30}"
MAX_JITTER_SECONDS="${BATCH_EXPORT_MAX_JITTER_SECONDS:-1}"
MAX_PAGES="${BATCH_EXPORT_MAX_PAGES:-1000}"

require_integer() {
  case "$2" in
    ''|*[!0-9]*) echo "$1 must be a non-negative integer" >&2; exit 1 ;;
  esac
}

require_integer BATCH_EXPORT_MAX_RETRIES "$MAX_RETRIES"
require_integer BATCH_EXPORT_RETRY_DELAY_SECONDS "$RETRY_DELAY_SECONDS"
require_integer BATCH_EXPORT_MAX_RETRY_DELAY_SECONDS "$MAX_RETRY_DELAY_SECONDS"
require_integer BATCH_EXPORT_MAX_JITTER_SECONDS "$MAX_JITTER_SECONDS"
require_integer BATCH_EXPORT_MAX_PAGES "$MAX_PAGES"
[ "$MAX_RETRIES" -ge 1 ] || { echo "BATCH_EXPORT_MAX_RETRIES must be at least 1" >&2; exit 1; }
[ "$MAX_PAGES" -ge 1 ] || { echo "BATCH_EXPORT_MAX_PAGES must be at least 1" >&2; exit 1; }

TEMP_RESULTS="$(mktemp "${RESULTS_FILE}.partial.XXXXXX")"
PAGE_BODY="$(mktemp)"
PAGE_HEADERS="$(mktemp)"
cleanup() {
  rm -f "$PAGE_BODY" "$PAGE_HEADERS"
  [ -z "${TEMP_RESULTS:-}" ] || rm -f "$TEMP_RESULTS"
}
trap cleanup EXIT HUP INT TERM

CURSOR=""
SEEN_CURSORS="|"
PAGE_COUNT=0
while :; do
  PAGE_COUNT=$((PAGE_COUNT + 1))
  [ "$PAGE_COUNT" -le "$MAX_PAGES" ] || {
    echo "Batch export exceeded the $MAX_PAGES-page safety bound" >&2
    exit 1
  }

  if [ -n "$CURSOR" ]; then
    PAGE_URL="$BOUNCELESS_API_BASE/v1/requests/$REQUEST_ID/results?limit=200&cursor=$(printf '%s' "$CURSOR" | jq -sRr @uri)"
  else
    PAGE_URL="$BOUNCELESS_API_BASE/v1/requests/$REQUEST_ID/results?limit=200"
  fi

  ATTEMPT=1
  while :; do
    : > "$PAGE_BODY"
    : > "$PAGE_HEADERS"
    if ! HTTP_STATUS="$(curl --silent --show-error \
      --dump-header "$PAGE_HEADERS" \
      --output "$PAGE_BODY" \
      --write-out '%{http_code}' \
      "$PAGE_URL" \
      -H "X-Api-Key: $BOUNCELESS_API_KEY")"; then
      echo "Batch result request failed before an HTTP response" >&2
      exit 1
    fi

    case "$HTTP_STATUS" in
      200) break ;;
      429|500|502|503|504)
        [ "$ATTEMPT" -lt "$MAX_RETRIES" ] || {
          echo "Batch result page failed with HTTP $HTTP_STATUS after $ATTEMPT attempts" >&2
          exit 1
        }
        RETRY_AFTER="$(awk 'tolower($1) == "retry-after:" { gsub("\\r", "", $2); value=$2 } END { print value }' "$PAGE_HEADERS")"
        case "$RETRY_AFTER" in
          ''|*[!0-9]*) WAIT_SECONDS=$((RETRY_DELAY_SECONDS * ATTEMPT)) ;;
          *) WAIT_SECONDS="$RETRY_AFTER" ;;
        esac
        if [ "$MAX_JITTER_SECONDS" -gt 0 ]; then
          WAIT_SECONDS=$((WAIT_SECONDS + ATTEMPT % (MAX_JITTER_SECONDS + 1)))
        fi
        [ "$WAIT_SECONDS" -le "$MAX_RETRY_DELAY_SECONDS" ] || WAIT_SECONDS="$MAX_RETRY_DELAY_SECONDS"
        echo "HTTP $HTTP_STATUS; retrying in ${WAIT_SECONDS}s ($ATTEMPT/$MAX_RETRIES)" >&2
        sleep "$WAIT_SECONDS"
        ATTEMPT=$((ATTEMPT + 1))
        ;;
      *)
        ERROR_CODE="$(jq -r '.error.code? // empty' "$PAGE_BODY" 2>/dev/null || true)"
        echo "Batch result page failed with HTTP $HTTP_STATUS (${ERROR_CODE:-no structured error code})" >&2
        exit 1
        ;;
    esac
  done

  jq -e '(.results | type == "array") and has("nextCursor") and ((.nextCursor == null) or (.nextCursor | type == "string"))' "$PAGE_BODY" >/dev/null || {
    echo "Batch result page is not valid results JSON" >&2
    exit 1
  }
  jq -c '.results[]' "$PAGE_BODY" >> "$TEMP_RESULTS"
  NEXT_CURSOR="$(jq -r 'if .nextCursor == null then "" else .nextCursor end' "$PAGE_BODY")"
  [ -n "$NEXT_CURSOR" ] || break
  case "$SEEN_CURSORS" in
    *"|$NEXT_CURSOR|"*) echo "Batch result cursor repeated; refusing an incomplete export" >&2; exit 1 ;;
  esac
  SEEN_CURSORS="${SEEN_CURSORS}${NEXT_CURSOR}|"
  CURSOR="$NEXT_CURSOR"
done

mv -f -- "$TEMP_RESULTS" "$RESULTS_FILE"
TEMP_RESULTS=""
rm -f "$PAGE_BODY" "$PAGE_HEADERS"
trap - EXIT HUP INT TERM
printf 'Export complete: %s\n' "$RESULTS_FILE"

The API returns JSON. To create a CSV from the same final results with the CLI, use:

npx @bounceless/cli batch results "$REQUEST_ID" --output csv > batch-results.csv

The environment overrides in the script are operational safety bounds, not API parameters. Keep them finite and see Errors, limits, credits, and retries before changing them.

Start

Verify

Tools

API reference

Changes

Verify batch

Verify a batch

1. Submit and capture the request ID

2. Poll with a bound

3. Retrieve every result with the cursor

​Verify a batch

​1. Submit and capture the request ID

​2. Poll with a bound

​3. Retrieve every result with the cursor

Verify a batch

1. Submit and capture the request ID

2. Poll with a bound

3. Retrieve every result with the cursor