Zero bounce API - pascal SDK

This library is a wrapper for the ZeroBounce API v2.

For more information about the API, visit https://www.zerobounce.net/docs/.

In order to run this library, the zero-bounce API which requires an API key. Check this guide to see how to grab yours.

Package's units

The methods implemented in this library can raise ZbException.

• ZbUtility - contains utility methods
  • ZBInitialize - set the API key (and API base URL) to be used within the all SDK's methods

        // ApiURL can be ZbApiURLDefault, ZbApiURLUSA, ZbApiURLEU
        ZBInitialize('YOUR__API__KEY', ZbApiURLDefault)
    

  • ZbException - exception containing data about the response context
• ZbGeneric - contains general purpose methods
  • ZbGetCredits (returns integer) - fetch account's credits
  • ZbGetApiUsage (returns TApiUsage) - fetch account's (overall or specific) API usage
  • ZbActivityData (returns integer) - fetch the amount of days an email inbox has been active
  • ZbFindEmailByDomain (returns TZbFindEmailResponse) - identifies and validates a person’s primary email address via domain
  • ZbFindEmailByCompanyName (returns TZbFindEmailResponse) - identifies and validates a person’s primary email address via company name
  • ZbDomainSearchByDomain (returns TZbDomainSearchResponse) - detects possible email address patterns used by a domain
  • ZbDomainSearchByCompanyName (returns TZbDomainSearchResponse) - detects possible email address patterns used by a company
• ZbValidation - fetch validation information about emails
  • ZbValidateEmail (returns TZbValidationResult) - validate one email
  • ZbBatchValidateEmails (retrns TZBBatchValidation) - validate a list of emails
• ZbBulk - bulk email validation or AI scoring (bulk base URL: https://bulkapi.zerobounce.net/v2; see v2 send file, v2 file status, v2 get file)
  • TZbBulkParams - column indexes and flags for file submit; set AllowPhase2Specified and AllowPhase2 to send allow_phase_2 on validation sendfile only (not AI scoring).
  • TZbGetFileOptions / PTZbGetFileOptions - optional download_type (DownloadType) and validation-only activity_data (ActivityDataSpecified + ActivityData); pass @Options as the second argument to result-fetch functions, or nil for defaults.
  • Constants in ZbUtility: ZB_DOWNLOAD_TYPE_PHASE_1, ZB_DOWNLOAD_TYPE_PHASE_2, ZB_DOWNLOAD_TYPE_COMBINED.
  • Bulk Email validation:
    • ZbBulkValidationFileSubmit (returns TZBFileFeedback) - submit for bulk validation a file contents, containing emails
    • ZbBulkValidationFileStatusCheck (returns TZBFileStatus) - check the status of a submitted file
    • ZbBulkValidationResultFetch (returns TZBBulkResponse) - fetch the validation result; optional Options: PTZbGetFileOptions = nil
    • ZbBulkValidationResultDelete (returns TZBFileFeedback) - delete file submitted for bulk validation
  • AI scoring:
    • ZbAiScoringFileSubmit (returns TZBFileFeedback) - submit for AI scoring a file contents, containing emails
    • ZbAiScoringFileStatusCheck (returns TZBFileStatus) - check the status of a submitted file
    • ZbAiScoringResultFetch (returns TZBBulkResponse) - fetch the scoring result; optional Options: PTZbGetFileOptions = nil (activity_data is not sent for scoring getfile)
    • ZbAiScoringResultDelete (returns TZBFileFeedback) - delete file submitted for AI scoring
  • For getfile, if the response body is JSON error data (including some HTTP 200 cases), TZBBulkResponse.HasContent is false and Feedback is filled; otherwise HasContent is true and Content holds the file text. Helper: ZbGetFileJsonIndicatesError in ZbStructures.
• ZbStructures - contains structures returned by the methods enumerated above (TZbFileStatus includes FilePhase2Status / file_phase_2_status when the API returns it)

Usage

Delphi

In order to run this package, one must install Delphi IDE.

Open Delphi IDE, File > Open, browse for ./packages/ZeroBounce.dpk (or ./packages/zb.groupproj), click "Open package".

Minimal Indy example (no package): For a self-contained single-email validation example using Indy (IdHTTP, IdSSLOpenSSL), see examples/delphi-api-v2/. Build ValidateEmailExample.dpr there; no SDK package install required.

In order to run example snippets or your own project using the zero-bounce package, first install the package into Delphi:

• open package (described above)
• locate projects window (or CTRL+ALT+F11)
• right click on the project ("ZeroBounce.bpl") > Compile
• right click on the project > Install

After installing, the example projects (./examples/delphi/Examples.groupproj) should run successfully. If that still doesn't happen, follow the steps below.

To run the ZeroBounce SDK with any other Dephi project:

• open desired project
• Project > Options (or SHIFT+CTRL+F11) > Packages > Runtime Packages
• enable "Link with runtime packages"
• [optional] click on the three dots from "Runtime packages", browse to C:\Users\Public\Documents\Embarcadero\Studio\{INSTALLED VERSION}\Bpl, select "Any file (.)" from bottom-right, select ZeroBounce.bpl file
• you can now import project's units

Free Pascal

In order to run this package, one must install Lazarus IDE.

Open Lazarus IDE, File > Open, browse for ./packages/zerobounce.lpk (relative to repository root), click "Open package".

In order to run unit tests, example snippets or your own project with the zero-bounce package, first install it into lazarus:

• open package (described above)
• locate package window (titled with "Package ZeroBounce {version}")
• Compile
• Use > Install

After installing, opening either tests (./tests/unit_tests.lpi) or example snippets (any *.lpi file from ./examples/fpc/ folder) should work running.

To run ZeroBounce SDK with any other FPC project:

• open desired project
• Project > Project inspector > Add > New requirement
• pick "ZeroBounce" from the list
• it should now appear in "Required Packages"
• you can now import project's units

Testing

Unit tests (FPCUnit) can be run via Docker or locally.

Docker: from the sdk-docs/ folder in the SDKs monorepo:

cd sdk-docs
docker compose build pascal
docker compose run --rm pascal

The repository includes a .dockerignore to keep the image build context small. You can also run docker build -t zerobounce-pascal-sdk:test . from this directory.

Local (console): with FPC and fp-units-fcl installed: fpc -Fu./src -Fu./tests -Mobjfpc -O2 tests/unit_tests_console.lpr -FE. then ./unit_tests_console --all.

Local (GUI): open tests/unit_tests.lpr in Lazarus and run (Run → Run).

See TESTING.md for all SDK test commands.

Publish

1. Bump version in packages/zerobounce.lpk, commit, tag (vX.Y.Z), push tag.
2. Actions → Publish → Run workflow with that tag.

No package registry — GitHub release only. Pin the tag via clone or submodule.