zerobounce-sdk 1.2.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05ca50ba9671572511cbd49f67ab96fd7b2956e7143ccbcc03e4a53daaed8601
-  data.tar.gz: 863f281ff04f36fc68b7d87468056c58ceff7426318c86f6c4030bfd3f036b29
+  metadata.gz: 2dc83468988043fa3a7907c8c9cbfac6185cc54f6e02d56c89e0be0cd1f1d24b
+  data.tar.gz: 410e9b0308a04ba30400123609247b6216c3005b5843ae6a8eb41951ea178171
 SHA512:
-  metadata.gz: 0577e5dbe7e0d013efc8da85ba6691df0adc88c5e519be4453696f40b14fb89374b7afcdd20ef053ceeff287965a3f3639489cc84752407ca6540e8a0ec1af91
-  data.tar.gz: c5d789f36349693e1a5dce55db8613e4ccd9017864ec7617bedb837cb5d36f049b4387163183773282abc45e4c451eb53aa85119f99ea0bd549e95eeff2f4241
+  metadata.gz: 2c650c338d1ebcf6222fd047b99682bec4e0f6da937e8b06cc2d2dfcb47db975f3ba3b39c909f91ddd7b8c1ab4ae38087dc4c9bfcce166a95ad130de9f34c3e1
+  data.tar.gz: cf4b1948a0eb8017cf4e0c1a07658f013d10b0effc35b4483d299df1bbf2117bd7f7dab40ba9bddeb744272217739e31ad9dc95711d4d32d143a5692d49d54df

data/.dockerignore

@@ -0,0 +1,17 @@
+# Keep .git so gemspec `git ls-files` works during `bundle install` in the image.
+
+# Docs and tooling not needed to run specs in the image
+*.md
+documentation*.md
+.spec
+.rspec_status
+coverage/
+tmp/
+pkg/
+vendor/bundle
+
+# OS & env
+.DS_Store
+Thumbs.db
+.env
+.env.*

data/.env.example

@@ -0,0 +1,3 @@
+# ZeroBounce API key (standard). Get your key at https://www.zerobounce.net/docs/api-dashboard
+# Copy this file to .env and set your key.
+ZEROBOUNCE_API_KEY=your_api_key_here

data/.github/auto_assign.yml

@@ -0,0 +1,5 @@
+addReviewers: false
+addAssignees: true
+assignees:
+  - franciscbalint
+numberOfAssignees: 1

data/.github/dependabot.yml

@@ -0,0 +1,35 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#versioning-strategy
+
+version: 2
+updates:
+  # Keep the Ruby dependencies up to date
+  - package-ecosystem: "bundler"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    target-branch: "develop"
+    labels:
+      - "ruby dependencies"
+    groups:
+      bundler:
+        applies-to: version-updates
+        patterns:
+          - "*"
+
+  # Keep the Github Actions dependencies up to date
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    target-branch: "develop"
+    labels:
+      - "github dependencies"
+    groups:
+      github:
+        applies-to: version-updates
+        patterns:
+          - "*"

data/.github/workflows/auto_assign_ci.yaml

@@ -0,0 +1,21 @@
+name: Auto Assign
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - synchronize
+      - reopened
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  add-assignee:
+    name: Auto assign (me only)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: kentaro-m/auto-assign-action@v2.0.2
+        with:
+          configuration-path: ".github/auto_assign.yml"

data/.github/workflows/codeql.yml

@@ -0,0 +1,105 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "develop" ]
+  pull_request:
+    branches: [ "develop" ]
+  schedule:
+    - cron: '19 14 * * 4'
+
+permissions:
+  security-events: write
+  packages: read
+  actions: read
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: ruby
+          build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v6
+
+    # Add any setup steps before running the `github/codeql-action/init` action.
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    # or others). This is typically only required for manual builds.
+    # - name: Setup runtime (example)
+    #   uses: actions/setup-example@v1
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - name: Run manual build steps
+      if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v4
+      with:
+        category: "/language:${{matrix.language}}"

data/.github/workflows/sdk_ci.yml

@@ -0,0 +1,29 @@
+# Run RSpec tests (VCR cassettes; no live API key needed for recorded specs).
+name: SDK CI
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    env:
+      ZEROBOUNCE_API_KEY: "invalid_key_for_tests"
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2"
+          bundler-cache: true
+
+      - name: Run specs
+        run: bundle exec rspec

data/.gitignore

@@ -62,3 +62,9 @@ build-iPhoneSimulator/
 # Log files
 output.err
 output.log
+
+.DS_Store
+Thumbs.db
+.idea/
+.cursor/
+.env

data/CODE_OF_CONDUCT.md

@@ -54,12 +54,7 @@ further defined and clarified by project maintainers.
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at afrase91@gmail.com. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project team at **integrations@zerobounce.net**. All complaints will be reviewed and investigated promptly and fairly. The project team is obligated to maintain confidentiality with regard to the reporter of an incident.
 
 Project maintainers who do not follow or enforce the Code of Conduct in good
 faith may face temporary or permanent repercussions as determined by other

data/CONTRIBUTING.md

@@ -1 +1,112 @@
-TODO fill this out
+# Contributing to Zero Bounce Ruby SDK
+
+Thank you for your interest in contributing. This document explains how to get set up, run tests, and submit changes.
+
+## Code of Conduct
+
+By participating in this project, you agree to uphold our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Getting Started
+
+### Prerequisites
+
+* Ruby 3.2+ (see [.ruby-version](.ruby-version))
+* [Bundler](https://bundler.io/) ~> 2.4
+
+### Setup
+
+```bash
+git clone https://github.com/zerobounce/zero-bounce-ruby.git
+cd zero-bounce-ruby
+bundle install
+```
+
+### Running Tests
+
+Tests use [RSpec](https://rspec.info/) with [VCR](https://github.com/vcr/vcr) for recorded HTTP interactions. Use the placeholder key so cassettes match:
+
+```bash
+ZEROBOUNCE_API_KEY=vcr_test_key bundle exec rspec
+```
+
+Or copy `.env.example` to `.env`, set `ZEROBOUNCE_API_KEY=vcr_test_key`, then:
+
+```bash
+bundle exec rspec
+```
+
+**With Docker:**
+
+```bash
+docker build -t zerobounce-ruby-test .
+docker run --rm zerobounce-ruby-test
+```
+
+### Code Style
+
+The project uses [RuboCop](https://github.com/rubocop/rubocop). Run before submitting:
+
+```bash
+bundle exec rubocop
+```
+
+## How to Contribute
+
+### Reporting Bugs
+
+Open an [issue](https://github.com/zerobounce/zero-bounce-ruby/issues) and include:
+
+* Ruby version (`ruby -v`)
+* Steps to reproduce
+* Expected vs actual behavior
+* Relevant code or error messages
+
+### Suggesting Changes
+
+* Check existing issues and pull requests first.
+* Open an issue to discuss larger changes or API design before coding.
+
+### Submitting Changes
+
+1. **Fork** the repository and create a branch from `main`:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** and add or update tests where relevant.
+
+3. **Run the suite** and RuboCop:
+   ```bash
+   ZEROBOUNCE_API_KEY=vcr_test_key bundle exec rspec
+   bundle exec rubocop
+   ```
+
+4. **Commit** with a clear message (e.g. `Add X`, `Fix Y`).
+
+5. **Push** your branch and open a **Pull Request** against `main`.
+
+6. In the PR description, briefly explain what changed and why. Link any related issues.
+
+Maintainers will review and may request changes. Once approved, your PR can be merged.
+
+## Project Layout
+
+* `lib/` – SDK source (entry point: `lib/zerobounce.rb`)
+* `spec/` – RSpec tests and VCR cassettes (`spec/cassettes/`)
+* `data/` – Sample CSV files for batch validation and scoring examples
+
+## Re-recording VCR Cassettes
+
+If you change or add API calls and need to re-record cassettes:
+
+1. Use a valid Zero Bounce API key (e.g. from [dashboard](https://www.zerobounce.net/docs/api-dashboard)).
+2. Set `ZEROBOUNCE_API_KEY` and run the specs; VCR will record new HTTP interactions.
+3. Replace any real API key in the new cassette files with `vcr_test_key` before committing, so the repo never contains real credentials.
+
+## Questions
+
+* [Zero Bounce API docs](https://www.zerobounce.net/docs/)
+* [Project homepage](https://zerobounce.net)
+* Contact: **integrations@zerobounce.net**
+
+Thanks for contributing.

data/Dockerfile

@@ -0,0 +1,17 @@
+# ZeroBounce Ruby SDK – test image (Ruby 3.2)
+FROM ruby:3.2-alpine
+
+RUN apk add --no-cache build-base git
+
+WORKDIR /app
+
+COPY . .
+# Gemfile.lock expects Bundler 2.4.x (see gemspec); Ruby 3.2 image may ship Bundler 4.x.
+RUN gem install bundler -v 2.4.22 && \
+    bundle config set --local path 'vendor/bundle' && \
+    bundle _2.4.22_ install
+
+# Dummy key for VCR/cassette-based specs; override with env for live API
+ENV ZEROBOUNCE_API_KEY="${ZEROBOUNCE_API_KEY:-invalid_key_for_tests}"
+
+CMD ["bundle", "_2.4.22_", "exec", "rspec"]

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    zerobounce-sdk (1.2.0)
+    zerobounce-sdk (2.1.0)
       dotenv
       rest-client (~> 2.1)
 
@@ -11,6 +11,8 @@ GEM
     addressable (2.8.4)
       public_suffix (>= 2.0.2, < 6.0)
     ast (2.4.2)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
     coderay (1.1.3)
     crack (0.4.5)
       rexml
@@ -105,6 +107,8 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  base64
+  bigdecimal
   bundler (~> 2.4.6)
   pry (~> 0.14.1)
   rake (~> 13.0)
@@ -121,4 +125,4 @@ DEPENDENCIES
   zerobounce-sdk!
 
 BUNDLED WITH
-   2.4.6
+   2.4.22

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 ZeroBounce
+Copyright (c) 2026 ZeroBounce
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/LICENSE.txt

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2018 Aaron Frase
+Copyright (c) 2026 ZeroBounce
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ 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 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.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -189,10 +189,13 @@ Zerobounce.api_usage(Date.today, Date.today)
  "sub_status_mailbox_quota_exceeded"=>0,
  "sub_status_forcible_disconnect"=>0,
  "sub_status_failed_smtp_connection"=>0,
+ "sub_status_accept_all"=>0,
  "sub_status_mx_forward"=>0,
  "sub_status_alternate"=>0,
- "sub_status_blocked"=>0,
  "sub_status_allowed"=>0,
+ "sub_status_blocked"=>0,
+ "sub_status_gold"=>0,
+ "sub_status_role_based_accept_all"=>0,
  "start_date"=>"4/28/2023",
  "end_date"=>"4/28/2023"}
 ```
@@ -378,10 +381,13 @@ Send file
     last_name_column: 3,
     gender_column: 4,
     has_header_row: true,
-    return_url: nil         # results callback url
+    return_url: nil,        # results callback url
+    allow_phase_2: true      # optional; validation bulk sendfile only (omit or nil to skip)
  # Zerobounce.validate_file_send(validate_file_path, email_address_column: 1, gender_column: 4)
 ```
 
+Bulk validation uses `https://bulkapi.zerobounce.net/v2`. See [v2 send file](https://www.zerobounce.net/docs/email-validation-api-quickstart/v2-send-file), [v2 file status](https://www.zerobounce.net/docs/email-validation-api-quickstart/v2-file-status), and [v2 get file](https://www.zerobounce.net/docs/email-validation-api-quickstart/v2-get-file).
+
 Check file
 ```ruby
 file_id = "75d854a6-565c-49f9-b4c8-b3344480ec4c"
@@ -394,6 +400,7 @@ Zerobounce.validate_file_check(file_id)
  "upload_date"=>"2023-04-28T15:25:41Z",
  "file_status"=>"Greylisted",
  "complete_percentage"=>"0%",
+ "file_phase_2_status"=>"N/A",  # when present (validation bulk v2)
  "error_reason"=>nil,
  "return_url"=>nil}
 ```
@@ -406,6 +413,18 @@ Zerobounce.validate_file_get(file_id)
 => "\"email\",\"first\",\"last\",\"gender\",\"ip\",\"ZB Status\",\"ZB Sub Status\",\"ZB Account\",\"ZB Domain\",\"ZB First Name\",\"ZB Last Name\",\"ZB Gender\",\"ZB Free Email\",\"ZB MX Found\",\"ZB MX Record\",\"ZB SMTP Provider\",\"ZB Did You Mean\"\n\"disposable@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"disposable\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"invalid@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"mailbox_not_found\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"valid@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"valid\",\"\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"toxic@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"toxic\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"donotmail@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"role_based\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"spamtrap@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"spamtrap\",\"\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"abuse@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"abuse\",\"\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"unknown@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"mail_server_temporary_error\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"catch_all@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"catch-all\",\"\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"antispam_system@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"antispam_system\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"does_not_accept_mail@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"does_not_accept_mail\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"exception_occurred@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"exception_occurred\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"failed_smtp_connection@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"failed_smtp_connection\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"failed_syntax_check@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"failed_syntax_check\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"forcible_disconnect@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"forcible_disconnect\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"global_suppression@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"global_suppression\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"greylisted@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"greylisted\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"leading_period_removed@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"valid\",\"leading_period_removed\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"mail_server_did_not_respond@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"mail_server_did_not_respond\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"mail_server_temporary_error@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"mail_server_temporary_error\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"mailbox_quota_exceeded@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"mailbox_quota_exceeded\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"mailbox_not_found@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"mailbox_not_found\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"no_dns_entries@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"no_dns_entries\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"possible_trap@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"possible_trap\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"possible_typo@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"possible_typo\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"role_based@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"role_based\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"timeout_exceeded@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"timeout_exceeded\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"unroutable_ip_address@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"unroutable_ip_address\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"free_email@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"valid\",\"\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"True\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"role_based_catch_all@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"role_based_catch_all\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n"
 ```
 
+Optional [v2 get file](https://www.zerobounce.net/docs/email-validation-api-quickstart/v2-get-file) query parameters use `Zerobounce::GetFileOptions` and `Zerobounce::DownloadType` (`PHASE_1`, `PHASE_2`, `COMBINED`). Set `activity_data` for validation `validate_file_get` only; it is not sent for `scoring_file_get`.
+
+```ruby
+opts = Zerobounce::GetFileOptions.new(
+  download_type: Zerobounce::DownloadType::COMBINED,
+  activity_data: true
+)
+csv = Zerobounce.validate_file_get(file_id, opts)
+```
+
+Non-success HTTP responses or JSON error bodies (including some HTTP 200 responses with `"success": false`) raise `RuntimeError` with the API message. To inspect a raw body string, use `Zerobounce.get_file_json_indicates_error?(body)`.
+
 Delete file
 ```ruby
 file_id = "75d854a6-565c-49f9-b4c8-b3344480ec4c"
@@ -459,13 +478,15 @@ file_id = "89fb7262-b845-4fa1-aa25-e486347ec64e"
 => "89fb7262-b845-4fa1-aa25-e486347ec64e"
 Zerobounce.scoring_file_get(file_id)
 => "\"email\",\"ZeroBounceQualityScore\"\r\n\"disposable@example.com\",\"0\"\r\n\"invalid@example.com\",\"10\"\r\n\"valid@example.com\",\"10\"\r\n\"toxic@example.com\",\"2\"\r\n\"donotmail@example.com\",\"0\"\r\n\"spamtrap@example.com\",\"0\"\r\n\"abuse@example.com\",\"10\"\r\n\"unknown@example.com\",\"10\"\r\n\"catch_all@example.com\",\"10\"\r\n\"antispam_system@example.com\",\"0\"\r\n\"does_not_accept_mail@example.com\",\"0\"\r\n\"exception_occurred@example.com\",\"0\"\r\n\"failed_smtp_connection@example.com\",\"0\"\r\n\"failed_syntax_check@example.com\",\"0\"\r\n\"forcible_disconnect@example.com\",\"0\"\r\n\"global_suppression@example.com\",\"0\"\r\n\"greylisted@example.com\",\"0\"\r\n\"leading_period_removed@example.com\",\"0\"\r\n\"mail_server_did_not_respond@example.com\",\"0\"\r\n\"mail_server_temporary_error@example.com\",\"0\"\r\n\"mailbox_quota_exceeded@example.com\",\"0\"\r\n\"mailbox_not_found@example.com\",\"0\"\r\n\"no_dns_entries@example.com\",\"0\"\r\n\"possible_trap@example.com\",\"0\"\r\n\"possible_typo@example.com\",\"0\"\r\n\"role_based@example.com\",\"0\"\r\n\"timeout_exceeded@example.com\",\"0\"\r\n\"unroutable_ip_address@example.com\",\"0\"\r\n\"free_email@example.com\",\"0\"\r\n\"role_based_catch_all@example.com\",\"0\""
+# Optional second argument: GetFileOptions with download_type only (activity_data is not sent for scoring getfile)
+# Zerobounce.scoring_file_get(file_id, Zerobounce::GetFileOptions.new(download_type: Zerobounce::DownloadType::PHASE_2))
 ```
 
 Delete file
 ```ruby
 file_id = "89fb7262-b845-4fa1-aa25-e486347ec64e"
 => "89fb7262-b845-4fa1-aa25-e486347ec64e"
-Zerobounce.validate_file_delete(file_id)
+Zerobounce.scoring_file_delete(file_id)
 => {"success"=>false, "message"=>"File cannot be found."}
 ```
 
@@ -705,14 +726,29 @@ gem install bundler -v "~>2.4.6"
 bundle install
 ```
 
-### Run tests
+### Run tests with Docker
+From the **parent repository root** (the folder that contains all SDKs and `docker-compose.yml`):
+
+```bash
+docker compose build ruby
+docker compose run --rm ruby
+```
+
+Or from this directory:
+
+```bash
+docker build -t zb-ruby-sdk .
+docker run --rm zb-ruby-sdk
+```
+
+### Run tests (local)
 ```bash
 bundle exec rspec
 ```
 
 You should see an output like this
 ```bash
-running mock tests
+running tests
 .....................................................
 
 Finished in 6.81 seconds (files took 0.40587 seconds to load)
@@ -720,24 +756,20 @@ Finished in 6.81 seconds (files took 0.40587 seconds to load)
 ```
 
 ### Test parameters
-The tests use the following environment parameters:
-ZEROBOUNCE_API_KEY {<zerobounce-api-key-value>} this key is used in mock tests as a valid key sample (any value will work for mock tests)
-INCORRECT_API_KEY {any non whitespace string value that is not a valid key} used for tests where the requests are meant to fail due to the API key value.
+The tests use the following environment parameter:
+- **ZEROBOUNCE_API_KEY** – Your API key; used in mock tests as the valid key sample (any value will work for mock tests).
 
-To set them
+An invalid API key for error-handling tests is hardcoded in the spec; no env var is required.
+
+To set your key:
 ```bash
-export ZEROBOUNCE_API_KEY=99e7ef20ceea4480a173b07b1be75371
-export INCORRECT_API_KEY=thiskeyisinvalidorotherwiseincorrect
+export ZEROBOUNCE_API_KEY=your_api_key_here
 ```
 
-A .env.sample file is provided.
+A .env.example file is provided.
 
-Tests use webmock and vcr for mocking HTTP requests. This means that actual requests were made and recorded in the spec/cassettes with an (at the time) valid API key used for testing purposes. This key has been invalidated in the meantime, however it is provided in the .env.sample file for the mock tests to work. If you do not wish to use this key for mocks, you can replace it with any value in the .yml files under spec/cassettes or delete all of them and rerun the tests so that vcr records them with a new key.
+Tests use webmock and vcr for mocking HTTP requests. This means that actual requests were made and recorded in the spec/cassettes with an (at the time) valid API key used for testing purposes. This key has been invalidated in the meantime, however it is provided in the .env.example file for the mock tests to work. If you do not wish to use this key for mocks, you can replace it with any value in the .yml files under spec/cassettes or delete all of them and rerun the tests so that vcr records them with a new key.
 
-### Publish
-```bash
-gem signin
-gem build zerobounce.spec
-gem push zerobounce-sdk-<version>.gem
-gem search zerobounce-sdk --remote
-```
+## Publish
+
+See the [sdk-docs (RubyGems)](../sdk-docs/rubygems/) guide in the SDKs repo for build and `gem push` steps.

data/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you think you've found a security issue, please report it privately instead of opening a public issue.
+
+**Email:** integrations@zerobounce.net (use a subject like `[zero-bounce-ruby] Security`).
+
+We'll look into reports as we can. If the issue is in the Zero Bounce API or service rather than this SDK, we may forward it to the right team.
+
+## Supported Versions
+
+We focus on the current release line for fixes. Using the [latest version](https://rubygems.org/gems/zerobounce-sdk) is recommended.
+
+## Tips for Using This SDK
+
+* Don't commit API keys or `.env` files—use environment variables or a secrets manager.
+* Keep dependencies up to date with `bundle install` and upgrade when new versions are released.
+* The client uses HTTPS by default; avoid overriding to non-HTTPS in production.
+
+Thanks for helping keep things secure.