email-validation-sdk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cef3267cdbc0f471acc37793832fa635ad5fae74f6a12e885dd852ee9f2e6673
+  data.tar.gz: 8bf364214be99dc1b0faef104424c0585ac41808b3034b8b26dbde4596e41858
+SHA512:
+  metadata.gz: 986d270b3fb54ceef83d8cd1ea279ddd57d4cc5b20136978a58c87d1c41a6de1321442cb69a175d368ddb1037c6b594e15dd1268c08b097af30d4170cd276178
+  data.tar.gz: 0751cdba9c258ca15890e9d94a862e061292b95c50b73d8b43ac0deb1f420ba6618a9c03726e060dd4e5f81a453210b5885a6c68e9cb2032059537a1f1f59f2f

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to the Ruby SDK (`email-validation-sdk`). The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the SDK uses [Semantic Versioning](https://semver.org/):
+a new vocabulary value, option or operation is a minor release; a removed or renamed public symbol is a major one.
+
+## [1.0.0] - 2026-11-04
+
+First version, with the same behaviour as the JavaScript and Python SDKs (API v1).
+
+### Added
+
+- The entry file is `email_validation_sdk.rb` (`require "email_validation_sdk"`), so the gem never collides with the
+  unrelated `email_validation` gem on the load path.
+
+- `EmailValidation::Client` with `validate`, `credits`, `usage` and `status`, and `client.bulk` with `create`, `get`,
+  `start`, `cancel`, `results` (whole body or streamed in chunks with a block, optional `range`) and `wait`.
+- Immutable `Data` models (`ValidationResult`, `Credits`, `UsageResponse`, `BulkJob`, `ServiceStatus`,
+  `WebhookEvent` …) that keep unknown enum values as raw strings and re-encode the API's JSON.
+- Error classes under `EmailValidation::Error` with `status`, `code`, `request_id` and `retry_after`.
+- Automatic retries of `429` / `503` answers (honouring `Retry-After`, capped by `max_retry_wait`) and of `GET`
+  requests after a network failure; never for `key_daily_cap`.
+- `EmailValidation.verify_webhook` / `sign_webhook` (Standard Webhooks scheme, constant-time comparison).
+- Vocabulary constants (`STATUSES`, `REASONS`, `REASONS_BY_STATUS`, `REASON_INFO`, `ACTIONS`, `SMTP_PROVIDERS`,
+  `BULK_JOB_STATUSES`, `ERROR_CODES`, `WEBHOOK_EVENTS` …), named-value modules and `sandbox_address`.
+- `NetHttpTransport` (standard library, keep-alive pool, no redirects) and a pluggable transport interface.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Email Validation LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,327 @@
+# email-validation.org Ruby SDK
+
+Official Ruby client for the [email-validation.org](https://email-validation.org) API: validate single addresses, read
+credits, usage and service status, run bulk jobs and verify webhook signatures. Immutable result models, typed errors,
+automatic retries for answers that are never charged, and no runtime dependencies (only the standard library:
+`net/http`, `json`, `openssl`). Ruby 3.2 or later.
+
+Documentation: https://email-validation.org/docs/sdks/ruby/
+
+## Install
+
+```bash
+gem install email-validation-sdk
+```
+
+or in your `Gemfile`:
+
+```ruby
+gem "email-validation-sdk", require: "email_validation_sdk"
+```
+
+The gem is required as `email_validation_sdk` (not `email_validation`, which is an unrelated gem) and lives in the
+`EmailValidation` module.
+
+## Quick start
+
+```ruby
+require "email_validation_sdk"
+
+client = EmailValidation::Client.new(api_key: ENV.fetch("EV_API_KEY"))
+
+result = client.validate("accepted@sandbox.email-validation.org") # free test address
+puts result.status  # => valid
+puts result.reason  # => accepted
+puts result.action  # => send
+```
+
+Addresses at `sandbox.email-validation.org` are free and answer the reason in their local part
+(`catch_all@…`, `no_mailbox@…`, `timeout@…`); `EmailValidation.sandbox_address("catch_all")` builds one.
+
+Build the client once and share it: it is safe to use from several threads and keeps connections alive.
+`client.close` releases them.
+
+## Client options
+
+```ruby
+client = EmailValidation::Client.new(
+  api_key: ENV.fetch("EV_API_KEY"), # required; never logged or shown by #inspect
+  base_url: "https://api.email-validation.org", # default
+  timeout: 30,          # seconds per attempt (connect + whole response), default 30
+  max_retries: 2,       # retries after the first attempt, default 2
+  max_retry_wait: 10    # longest single wait (seconds) the client accepts before giving up, default 10
+)
+```
+
+EU data residency (validated and stored in the EU): pass `base_url: EmailValidation::EU_BASE_URL` to call `https://api-eu.email-validation.org`
+instead of the default `https://api.email-validation.org`. See https://email-validation.org/docs/eu-data-residency/.
+
+A missing key, a key containing whitespace, a `base_url` that is not `http://` or `https://`, or a non-positive
+`timeout` raises `ArgumentError` at construction.
+
+## Methods
+
+### `client.validate(email, ip_address: nil, timeout: nil, fresh: nil)` → `ValidationResult`
+
+Checks one address. Costs 1 credit, except `unknown` results and local answers (malformed and sandbox addresses),
+which are free (`result.credits_used` is `0` or `1`).
+
+- `ip_address`: where the signup came from (optional).
+- `timeout`: seconds the service may spend on the check (5–15, server default 15). This is not the client's
+  per-attempt `timeout`, which should stay a few seconds above it.
+- `fresh: true` checks the address again even when it was checked in the last 12 months (by default the earlier
+  definite result may be returned; `processed_at` is when the answer was produced).
+
+```ruby
+result = client.validate("someone@example.com", ip_address: "203.0.113.7", timeout: 10)
+case result.action
+when EmailValidation::Action::SEND then puts "safe to send"
+when EmailValidation::Action::SEND_WITH_CAUTION then puts "send carefully"
+when EmailValidation::Action::REMOVE then puts "drop it"
+when EmailValidation::Action::RETRY_LATER then puts "try again later"
+end
+puts result.did_you_mean if result.did_you_mean
+```
+
+`ValidationResult` fields: `email`, `status`, `reason`, `action`, `account`, `domain`, `did_you_mean`, `free_email`,
+`role_account`, `disposable`, `catch_all_domain`, `mx_found`, `mx_record`, `smtp_provider`, `domain_age_days`,
+`processed_at`, `credits_used`, `request_id`.
+
+### `client.credits` → `Credits`
+
+```ruby
+credits = client.credits
+puts credits.balance, credits.debt, credits.pending
+credits.lots.each { |lot| puts "#{lot.remaining} expire at #{lot.expires_at}" } # soonest-expiring first
+```
+
+### `client.usage(from: nil, to: nil, group_by: nil)` → `UsageResponse`
+
+Dates are `"YYYY-MM-DD"` strings (UTC) or `Date` objects. `group_by` is `"day"` (default) or `"key"`.
+
+```ruby
+usage = client.usage(from: "2026-10-01", to: "2026-10-20")
+puts usage.totals.credits_used
+usage.items.each { |day| puts "#{day.date}: #{day.credits_used}" }            # UsageDay
+
+by_key = client.usage(group_by: "key")
+by_key.items.each { |key| puts "#{key.name || "(deleted key)"}: #{key.credits_used}" } # UsageByKey
+```
+
+### `client.status` → `ServiceStatus`
+
+```ruby
+status = client.status
+puts status.status            # operational, degraded or outage
+puts status.components.api    # also website, bulk, sign_in, payments, support
+```
+
+### Bulk jobs: `client.bulk`
+
+A key with the `bulk` scope can validate lists of up to 100,000 addresses (JSON) or files up to 100 MB.
+
+```ruby
+# From a list (sent as JSON) …
+job = client.bulk.create(emails: ["accepted@sandbox.email-validation.org", "no_mailbox@sandbox.email-validation.org"])
+
+# … or from a CSV / plain-text file: a String, an IO or a Pathname.
+job = client.bulk.create(file: Pathname.new("newsletter.csv"), column: "email", has_header: true)
+job = client.bulk.create(file: File.open("list.txt", "rb"), content_type: "text/plain")
+
+job = client.bulk.wait(job.id, interval: 5, timeout: 3600) do |progress|
+  puts "#{progress.status}: #{progress.processed}/#{progress.unique_emails || "?"}"
+end
+
+if job.status == EmailValidation::BulkJobStatus::COMPLETED
+  csv = client.bulk.results(job.id, filter: %w[valid catch_all])          # whole body as a String
+  File.open("results.csv", "wb") do |file|                             # or streamed in chunks
+    client.bulk.results(job.id) { |chunk| file.write(chunk) }
+  end
+end
+```
+
+| Method | Request | Returns |
+|---|---|---|
+| `bulk.create(emails: nil, file: nil, content_type: "text/csv", column: nil, has_header: nil, start: nil, webhook_endpoint_id: nil)` | `POST /v1/bulk` | `BulkJob` |
+| `bulk.get(job_id)` | `GET /v1/bulk/{id}` | `BulkJob` |
+| `bulk.start(job_id)` | `POST /v1/bulk/{id}/start` (credits are held now) | `BulkJob` |
+| `bulk.cancel(job_id)` | `DELETE /v1/bulk/{id}` (unused credits return) | `BulkJob` |
+| `bulk.results(job_id, filter: nil, columns: nil, escape_formulas: nil, range: nil) { \|chunk\| … }` | `GET /v1/bulk/{id}/results` | CSV `String`, or `nil` with a block |
+| `bulk.wait(job_id, interval: 5, timeout: nil, on_progress: nil) { \|job\| … }` | polls `bulk.get` | `BulkJob` |
+
+- `create`: pass exactly one of `emails:` (an Array) or `file:`; `start: false` keeps the job in `ready` until you call
+  `start`. A file given as an IO is read whole, so a retry can resend the same bytes.
+- `results`: `filter` is `"all"`, one status, or an Array of statuses; `columns` is `"original"` (default) or
+  `"email_only"`; `escape_formulas` defaults to `true` on the server. The CSV is returned unchanged (never parsed).
+  `range: "bytes=0-1048575"` fetches one part of the file to resume a download; only `filter: "all"` (or one status
+  with `escape_formulas: false`) with `columns: "original"` can be served in parts, and any other shape raises
+  `InvalidRequestError` instead of returning the whole file.
+- `wait` returns once the job is `completed`, `failed`, `cancelled` or `expired`, or once it is `ready` with an
+  `error_code` (its start was refused, e.g. `insufficient_credits`: buy credits, then call `start`). Check
+  `job.status` before downloading. A job created with `start: false` waits in `ready` until you call `start`, so call
+  `start` before `wait`. `interval` is at least 1 second; when `timeout` (seconds) passes, `wait` raises
+  `ConnectionError` with code `timeout`.
+- A job id is checked locally before any request (`job_` followed by 22 letters and digits); a malformed one raises
+  `InvalidRequestError` with status `0`.
+
+`BulkJob` fields: `id`, `status`, `filename`, `total_rows`, `unique_emails`, `duplicates`, `syntax_invalid`,
+`local_answered`, `processed`, `credits_reserved`, `credits_charged`, `counts`, `error_code`, `webhook_endpoint_id`,
+`created_at`, `started_at`, `finished_at`, `expires_at`; helpers `terminal?` and `stuck?`.
+
+### Models
+
+Results are immutable `Data` objects with the API's field names. `to_h` returns the API's fields (nested models
+converted, `nil` kept) and `to_json` re-encodes the API's JSON. Times are kept as the API's ISO 8601 UTC strings
+(`Time.iso8601(result.processed_at)` parses one). Unknown fields are ignored and unknown values (a reason or provider
+added after this SDK version) are kept as the raw string, so compare with the constants rather than assuming a closed
+list.
+
+## Errors
+
+Every failure raises a subclass of `EmailValidation::Error` (a `StandardError`). Branch on the class or on `code`,
+never on `message` (it is for people and may change).
+
+```ruby
+begin
+  client.validate("accepted@sandbox.email-validation.org")
+rescue EmailValidation::InsufficientCreditsError
+  puts "Out of credits: buy a pack."
+rescue EmailValidation::RateLimitError => e
+  puts "Rate limited (#{e.code}); retry in #{e.retry_after || "a few"} seconds."
+rescue EmailValidation::ConnectionError => e
+  puts "No answer (#{e.code})." # connection_error or timeout
+rescue EmailValidation::Error => e
+  puts "#{e.kind} #{e.status} #{e.code} #{e.request_id}"
+end
+```
+
+Every error has `status` (HTTP status, `0` when no answer arrived or the SDK refused the call before sending),
+`code`, `message`, `request_id` (quote it to support), `retry_after` (seconds or `nil`) and `cause`.
+
+| Class | When | Codes |
+|---|---|---|
+| `InvalidRequestError` | 400, 411, 413, other 4xx, local checks (status 0), a range answered without 206 | `invalid_request`, `length_required`, `payload_too_large` |
+| `AuthenticationError` | 401 | `unauthorized` |
+| `InsufficientCreditsError` | 402 (nothing charged) | `insufficient_credits` |
+| `PermissionDeniedError` | 403 | `forbidden`, `forbidden_origin` |
+| `NotFoundError` | 404 | `not_found` |
+| `ConflictError` | 409 | `conflict` |
+| `RateLimitError` | 429 | `rate_limited`, `abuse_throttled`, `key_daily_cap` |
+| `ServiceUnavailableError` | 503 | `service_unavailable`, `upstream_capacity` |
+| `ServerError` | 500, other 5xx, any other unexpected status (a 3xx redirect is never followed) | `internal_error` |
+| `ConnectionError` | no answer: network failure, attempt timeout, `bulk.wait` deadline | `connection_error`, `timeout` |
+| `Error` (base) | a 2xx answer that is not JSON | `unexpected_response` |
+
+An answer without our JSON error envelope (or with an unknown code) has code `unexpected_response`. Argument mistakes
+(e.g. `emails:` and `file:` together, an unknown `filter`) raise `ArgumentError` before any request. Ruby has no
+cancellation mechanism for blocking calls, so the `aborted` code is not used by this SDK.
+
+## Retries and timeouts
+
+- `429` and `503` answers are never charged, so they are retried for every method, honouring `Retry-After`, up to
+  `max_retries` times, unless the wait would be longer than `max_retry_wait` seconds. `key_daily_cap` is never
+  retried (it resets the next day).
+- Network failures and timeouts are retried only for `GET` requests. A validation, bulk upload, start or cancel that
+  reached the service may already have been charged or applied, so it is not sent again.
+- Nothing else is retried. Without `Retry-After` the wait is exponential with jitter (0.25–0.5 s, 0.5–1 s, 1–2 s …,
+  at most 8 s).
+- `timeout` bounds each attempt (connect, TLS and the whole response), not the whole call. For very large result
+  downloads, raise it or fetch the file in parts with `range:`.
+- Redirects are never followed, so the `Authorization` header never travels to another host.
+
+## Verify webhooks
+
+Deliveries are signed with the [Standard Webhooks](https://www.standardwebhooks.com/) scheme. Pass the raw body (before
+any JSON parsing), the request headers and the endpoint's secret:
+
+```ruby
+# Rack / Sinatra / Rails
+payload = request.body.read
+event = EmailValidation.verify_webhook(payload, request.env, ENV.fetch("EV_WEBHOOK_SECRET"))
+
+case event.type
+when "bulk.completed", "bulk.failed" then puts "#{event.data.job_id}: #{event.data.status}"
+when "credits.low" then puts "Balance #{event.data.balance} is under #{event.data.threshold}"
+when "credits.expiring" then puts "#{event.data.credits} credits expire at #{event.data.expires_at}"
+when "webhook.test" then puts "Test from endpoint #{event.data.endpoint_id}"
+end
+```
+
+- Headers: any Hash-like object with header names in any case, or a Rack env (`HTTP_WEBHOOK_ID` keys).
+- Failures raise `EmailValidation::WebhookVerificationError` (missing headers, a timestamp outside `tolerance`
+  seconds (default 300), an invalid secret, no matching signature or a body that is not JSON). Answer `400` then.
+- Deduplicate on the `webhook-id` header (retries reuse it) and answer `2xx` quickly; do slow work afterwards.
+- `webhook.test` events come from "Send test" in the dashboard.
+- `EmailValidation.sign_webhook(msg_id, timestamp, payload, secret)` returns a `v1,<base64>` signature, to test your
+  endpoint locally. Both functions are also available as `EmailValidation::Webhooks.verify` / `.sign`.
+
+## Constants
+
+```ruby
+EmailValidation::STATUSES                    # ["valid", "invalid", "catch_all", "unknown", "disposable"]
+EmailValidation::REASONS                     # all 30 reasons, grouped by status in REASONS_BY_STATUS
+EmailValidation::REASONS_BY_STATUS["catch_all"]  # ["catch_all", "role_catch_all", "forwarding_domain"]
+EmailValidation::REASON_INFO["catch_all"]    # { status: "catch_all", action: "send_with_caution" }
+EmailValidation::ACTIONS                     # ["send", "send_with_caution", "remove", "retry_later"]
+EmailValidation::SMTP_PROVIDERS              # ["google", "microsoft", …, "other"]
+EmailValidation::BULK_JOB_STATUSES           # ["analyzing", "ready", …, "expired"]
+EmailValidation::TERMINAL_BULK_JOB_STATUSES  # ["completed", "failed", "cancelled", "expired"]
+EmailValidation::BULK_JOB_ERROR_CODES        # { "invalid_csv" => "failed", …, "insufficient_credits" => "ready", … }
+EmailValidation::ERROR_CODES                 # the 15 API error codes, in the API's order
+EmailValidation::CLIENT_ERROR_CODES          # ["connection_error", "timeout", "unexpected_response", "aborted"]
+EmailValidation::WEBHOOK_EVENTS              # ["bulk.completed", "bulk.failed", "credits.low", …]
+EmailValidation::DEFAULT_BASE_URL            # "https://api.email-validation.org"
+EmailValidation::EU_BASE_URL                 # "https://api-eu.email-validation.org" (EU data residency)
+EmailValidation::SANDBOX_DOMAIN              # "sandbox.email-validation.org"
+EmailValidation::DEFAULT_WEBHOOK_TOLERANCE   # 300
+EmailValidation.status?("valid")             # true
+EmailValidation.reason?("catch_all")         # true
+EmailValidation.sandbox_address("no_mailbox") # "no_mailbox@sandbox.email-validation.org"
+
+# Named values: Status, Reason, Action, SmtpProvider, BulkJobStatus, ErrorCode, WebhookEventType
+EmailValidation::Status::VALID               # "valid"
+EmailValidation::Reason::CATCH_ALL           # "catch_all"
+EmailValidation::ErrorCode::RATE_LIMITED     # "rate_limited"
+EmailValidation::WebhookEventType::CREDITS_LOW # "credits.low"
+```
+
+## Bring your own HTTP client
+
+The client talks to a transport: any object with `call(request)` that returns an `EmailValidation::HttpResponse`, or
+raises `EmailValidation::TransportError` (with `timeout: true` for a timeout) when no answer arrived. `request` has
+`method`, `url`, `headers` (lower-case names), `body` (a binary String or `nil`) and `timeout` (seconds per attempt).
+The default is `EmailValidation::NetHttpTransport` (Net::HTTP with a keep-alive pool; it honours the standard proxy
+environment variables like Net::HTTP does).
+
+```ruby
+class LoggingTransport
+  def initialize(inner = EmailValidation::NetHttpTransport.new)
+    @inner = inner
+  end
+
+  def call(request, &on_head)
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    @inner.call(request, &on_head).tap do |response|
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+      warn "#{request.method} #{request.url} -> #{response.status} in #{elapsed.round(3)}s"
+    end
+  end
+
+  def close
+    @inner.close
+  end
+end
+
+client = EmailValidation::Client.new(api_key: ENV.fetch("EV_API_KEY"), transport: LoggingTransport.new)
+```
+
+A transport you pass in is not closed by `client.close`. Streaming is optional: when `call` receives a block, call it
+with `(status, headers)` once the response head arrives; if it returns a callable, pass each body chunk to it and
+return an `HttpResponse` with an empty body. A transport that ignores the block still works (the body is handed over
+in one piece). `request.inspect` never shows the headers or the body.
+
+## Privacy
+
+The API key is sent only in the `Authorization` header. It never appears in a URL, in an error message, or in the
+`inspect`/`to_s`/`pp` output of the client, its config or a request. The SDK writes nothing to stdout or stderr and
+has no telemetry.

data/lib/email_validation_sdk/bulk.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module EmailValidation
+  # Bulk jobs, reached as +client.bulk+. Needs a key with the +bulk+ scope.
+  class Bulk
+    JOB_ID = /\Ajob_[0-9A-Za-z]{22}\z/
+    CONTENT_TYPES = %w[text/csv text/plain].freeze
+    FILTERS = (["all"] + STATUSES).freeze
+    BAD_JOB_ID = "Not a bulk job id (expected job_ followed by 22 letters and digits)."
+    NOT_RANGEABLE = 'This download cannot be fetched in parts: use filter: "all" (or one status with ' \
+                    'escape_formulas: false) and columns: "original" with a range.'
+    private_constant :JOB_ID, :CONTENT_TYPES, :FILTERS, :BAD_JOB_ID, :NOT_RANGEABLE
+
+    # Wraps an exception raised by the caller's chunk block, so a transport never mistakes it for a network error.
+    class SinkError < StandardError
+      attr_reader :original
+
+      def initialize(original)
+        super("results block raised #{original.class}")
+        @original = original
+      end
+    end
+    private_constant :SinkError
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Creates a job (HTTP 202) and returns its BulkJob. Pass exactly one of:
+    # - +emails+: an Array of addresses, sent as JSON (up to 100,000 addresses / 4 MB);
+    # - +file+: the CSV or plain-text file as a String, an IO (read whole, so retries can resend it) or a Pathname
+    #   (up to 100 MB), with +content_type+ "text/csv" (default) or "text/plain".
+    #
+    # Options: +column+ (1–512 or a header name), +has_header+, +start+ (server default true; with +false+ the job
+    # waits in "ready" until #start), +webhook_endpoint_id+.
+    def create(emails: nil, file: nil, content_type: "text/csv", column: nil, has_header: nil, start: nil,
+               webhook_endpoint_id: nil)
+      raise ArgumentError, "pass exactly one of emails: or file:" if emails.nil? == file.nil?
+      raise ArgumentError, 'content_type must be "text/csv" or "text/plain"' unless
+        CONTENT_TYPES.include?(content_type)
+
+      query = { "column" => column, "has_header" => has_header, "start" => start,
+                "webhook_endpoint_id" => webhook_endpoint_id }
+      unless emails.nil?
+        raise ArgumentError, "emails must be an Array of addresses, not a String" if emails.is_a?(String)
+        raise ArgumentError, "emails must be an Array of addresses" unless emails.respond_to?(:to_a)
+
+        return @client.request_model(BulkJob, "POST", "/v1/bulk", query: query, json: { "emails" => emails.to_a })
+      end
+      @client.request_model(BulkJob, "POST", "/v1/bulk", query: query, body: read_file(file),
+                                                         content_type: content_type)
+    end
+
+    # The job's current state.
+    def get(job_id)
+      @client.request_model(BulkJob, "GET", job_path(job_id))
+    end
+
+    # Starts a job waiting in "ready"; credits are held now.
+    def start(job_id)
+      @client.request_model(BulkJob, "POST", job_path(job_id, "/start"))
+    end
+
+    # Cancels a job; unused credits are returned.
+    def cancel(job_id)
+      @client.request_model(BulkJob, "DELETE", job_path(job_id))
+    end
+
+    # Downloads the result CSV (UTF-8, returned unchanged; never parsed).
+    #
+    # - +filter+: "all", one status, or an Array of statuses.
+    # - +columns+: "original" (default) or "email_only".
+    # - +escape_formulas+: server default true.
+    # - +range+: e.g. "bytes=0-1048575", to fetch one part of the file (resume a download). Only
+    #   +filter: "all"+ (or one status with +escape_formulas: false+) and +columns: "original"+ can be served in parts;
+    #   any other shape raises InvalidRequestError instead of returning the whole file.
+    #
+    # Without a block it returns the whole body as a String. With a block it yields the body in chunks (binary
+    # Strings) as they arrive and returns nil, so a large file never sits in memory:
+    #
+    #   File.open("results.csv", "wb") { |f| client.bulk.results(job_id) { |chunk| f.write(chunk) } }
+    def results(job_id, filter: nil, columns: nil, escape_formulas: nil, range: nil, &block)
+      query = { "filter" => results_filter(filter), "columns" => columns, "escape_formulas" => escape_formulas }
+      headers = range ? { "range" => range } : nil
+      path = job_path(job_id, "/results")
+      return download(path, query, headers, range) unless block
+
+      stream_download(path, query, headers, range, block)
+    end
+
+    # Polls a job until it is completed, failed, cancelled or expired, or until it is "ready" with an +error_code+
+    # (its start was refused, e.g. +insufficient_credits+: buy credits, then call #start). Returns the last BulkJob;
+    # check its +status+ before downloading results.
+    #
+    # - +interval+: seconds between polls (default 5, also when nil; at least 1).
+    # - +timeout+: seconds before giving up with ConnectionError (code +timeout+); default none.
+    # - +on_progress+ (or a block): called with every polled BulkJob.
+    #
+    # A job created with +start: false+ waits in "ready" until you call #start, so call #start before #wait.
+    def wait(job_id, interval: 5, timeout: nil, on_progress: nil, &block)
+      job_path(job_id)
+      progress = on_progress || block
+      interval = [(interval || 5).to_f, 1.0].max
+      deadline = timeout.nil? ? nil : monotonic + timeout
+      loop do
+        job = get(job_id)
+        progress&.call(job)
+        return job if job.terminal? || job.stuck?
+        if deadline && monotonic + interval > deadline
+          raise ConnectionError.new("Bulk job #{job.id} is still #{job.status}.", status: 0, code: "timeout")
+        end
+
+        @client.sleep_for(interval)
+      end
+    end
+
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    private
+
+    def job_path(job_id, suffix = "")
+      unless job_id.is_a?(String) && JOB_ID.match?(job_id)
+        raise InvalidRequestError.new(BAD_JOB_ID, status: 0, code: "invalid_request")
+      end
+
+      "/v1/bulk/#{job_id}#{suffix}"
+    end
+
+    def results_filter(value)
+      return nil if value.nil?
+
+      parts = value.is_a?(Array) ? value.map(&:to_s) : [value.to_s]
+      parts.each do |part|
+        raise ArgumentError, "unknown filter: #{part.inspect} (use \"all\" or a status)" unless FILTERS.include?(part)
+      end
+      parts.join(",")
+    end
+
+    def read_file(file)
+      case file
+      when String then file
+      when Pathname then File.binread(file)
+      else
+        raise ArgumentError, "file must be a String, an IO or a Pathname" unless file.respond_to?(:read)
+
+        data = file.read
+        raise ArgumentError, "file returned no data" if data.nil?
+
+        data
+      end
+    end
+
+    def download(path, query, headers, range)
+      response = @client.perform("GET", path, query: query, accept: "text/csv", headers: headers)
+      refuse_whole_file(response.status, response.header("x-request-id")) if range && response.status != 206
+      response.body.dup.force_encoding(Encoding::UTF_8)
+    end
+
+    def stream_download(path, query, headers, range, block)
+      stream = Stream.new(range, block)
+      response = @client.perform("GET", path, query: query, accept: "text/csv", headers: headers, stream: stream)
+      refuse_whole_file(response.status, response.header("x-request-id")) if range && response.status != 206
+      # A transport without streaming support buffered the body: hand it over in one piece.
+      block.call(response.body) unless stream.head_seen? || response.body.empty?
+      nil
+    rescue SinkError => e
+      raise e.original, cause: e.original.cause
+    end
+
+    def refuse_whole_file(status, request_id)
+      raise InvalidRequestError.new(NOT_RANGEABLE, status: status, code: "invalid_request", request_id: request_id)
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # Decides, when the response head arrives, where the body goes: the caller's block for an accepted 2xx, nowhere
+    # for a whole file answered to a range request (it is discarded), and the buffer for error answers.
+    class Stream
+      def initialize(range, block)
+        @range = range
+        @block = block
+        @head_seen = false
+        @started = false
+      end
+
+      def on_head(status, _headers)
+        return nil unless (200..299).cover?(status)
+
+        @head_seen = true
+        return ->(_chunk) {} if @range && status != 206
+
+        lambda do |chunk|
+          @started = true
+          begin
+            @block.call(chunk)
+          rescue StandardError => e
+            raise SinkError, e
+          end
+        end
+      end
+
+      def head_seen?
+        @head_seen
+      end
+
+      def started?
+        @started
+      end
+    end
+    private_constant :Stream
+  end
+end