Zero Bounce C# SDK

This SDK contains methods for interacting easily with the ZeroBounce API. More information about ZeroBounce can be found in the official documentation.

INSTALLATION

You can install by searching for ZeroBounce.SDK in the NuGet Package Manager, or run:

Install-Package ZeroBounce.SDK

USAGE

Import the SDK:

using ZeroBounceSDK;

Initialize the wrapper with your API key and preferred API base URL:

ZeroBounce.Instance.Initialize("<YOUR_API_KEY>", ZBApiURL.ApiDefaultURL);

You can also use a custom base URL (e.g. for testing). Trailing slashes are removed automatically:

ZeroBounce.Instance.Initialize("<YOUR_API_KEY>", "https://api.zerobounce.net/v2");

Note: Initialize throws ZBClientException if the API key is null or whitespace. Other client-side validations (e.g. empty email_batch, empty file_id, or using both domain and company_name together in Email Finder/Domain Search) are reported via the failure callback.

Response types and enums

• ZBConfidence – Used in Email Finder and Domain Search for confidence levels: High, Medium, Low, Unknown, Undetermined. Exposed on ZBEmailFinderResponse.EmailConfidence, ZBDomainSearchResponse.Confidence, and ZBDomainFormat.Confidence.
• ZBValidateStatus / ZBValidateSubStatus – Validation result status and sub-status. Used on ZBValidateResponse and on each ZBValidateBatchResponseRow in batch validate responses. See the API docs for allowed values.
• ZBGetApiUsageResponse – Includes per-status and per–sub-status counts (e.g. SubStatusMxForward, SubStatusAlternate, SubStatusAllowed, SubStatusBlocked, SubStatusGold).
• ZBFileStatusResponse – Includes ErrorReason for file processing errors when present, and FilePhase2Status (file_phase_2_status) when the bulk API returns it (e.g. after optional phase 2 processing).
• ZBDownloadType – Phase1, Phase2, or Combined for bulk getfile download_type (validation and scoring).
• ZBGetFileResponse – When the API returns JSON (e.g. file not ready or an error with HTTP 200), the SDK treats Success, Message, ErrorMessage, and Error as error signals and invokes the failure callback with the first non-empty message.

Examples

You can now use any of the SDK methods, for example:

• Validate an email address

var email = "<EMAIL_ADDRESS>";   // The email address you want to validate
var ipAddress = "127.0.0.1";     // The IP Address the email signed up from (Optional)

ZeroBounce.Instance.Validate(email, ipAddress,
    response =>
    {
        Debug.WriteLine("Validate success response " + response);
        // ... your implementation
    },
    error =>
    {
        Debug.WriteLine("Validate failure error " + error);
        // ... your implementation
    });

• Validate a batch of email addresses

var email = "<EMAIL_ADDRESS>";   // The email address you want to validate
var ipAddress = "127.0.0.1";     // The IP Address the email signed up from (Optional)

List<ZBValidateEmailRow> emailBatch = new List<ZBValidateEmailRow>
{ 
    new ZBValidateEmailRow { EmailAddress = email, IpAddress = ipAddress }
};
ZeroBounce.Instance.ValidateBatch(emailBatch,
    response =>
    {
        Debug.WriteLine(response.EmailBatch[0].Address);
        // ... your implementation
    },
    error =>
    {
        Debug.WriteLine("Validate failure error " + error);
        // ... your implementation
    });

• Check how many credits you have left on your account

ZeroBounce.Instance.GetCredits(
    response =>
    {
        Debug.WriteLine("GetCredits success response " + response);
        // your implementation
    },
    error =>
    {
        Debug.WriteLine("GetCredits failure error " + error);
        // your implementation
    });

• Check your API usage for a given period of time

var startDate = new DateTime(2024, 01, 01); // Start date (yyyy-MM-dd)
var endDate = new DateTime(2024, 01, 31);   // End date (yyyy-MM-dd)

ZeroBounce.Instance.GetApiUsage(startDate, endDate,
    response =>
    {
        Debug.WriteLine("GetApiUsage success response " + response);
        // ... your implementation
    },
    error =>
    {
        Debug.WriteLine("GetApiUsage failure error " + error);
        // ... your implementation
    });

• Use the Activity API endpoint to gather insights into your subscribers' overall email engagement

var email = "valid@example.com";    // Subscriber email address

ZeroBounce.Instance.GetActivity(email,
    response =>
    {
        Debug.WriteLine("GetActivity success response " + response);
        // ... your implementation
    },
    error =>
    {
        Debug.WriteLine("GetActivity failure error " + error);
        // ... your implementation
    });

• Use the Email Finder API endpoint to identify the correct email format when you provide a name and email domain or company name.

var domain = "example.com";  // The email domain for which to find the email format.
var companyName = "Example"; // The company name for which to find the email format.
var firstName = "john";      // The first name of the person whose email format is being searched.
var middleName = "";         // The middle name of the person whose email format is being searched. [optional]
var lastName = "doe";        // The last name of the person whose email format is being searched. [optional]

ZeroBounce.Instance.FindEmailByDomain(domain, firstName, middleName, lastName,
    response =>
    {
        Debug.WriteLine("EmailFinder success response " + response);
        // ... your implementation
    },
    error =>
    {
        Debug.WriteLine("EmailFinder failure error " + error);
        // ... your implementation
    });

ZeroBounce.Instance.FindEmailByCompanyName(companyName, firstName, middleName, lastName,
    response =>
    {
        Debug.WriteLine("EmailFinder success response " + response);
        // ... your implementation
    },
    error =>
    {
        Debug.WriteLine("EmailFinder failure error " + error);
        // ... your implementation
    });

• Use the Domain Search API endpoint to identify the email domain when you provide a domain or company name.

var domain = "example.com";  // The email domain for which to find the email format.
var companyName = "Example"; // The company name for which to find the email format.

ZeroBounce.Instance.FindDomainByDomain(domain,
    response =>
    {
        Debug.WriteLine("DomainSearch success response " + response);
        // ... your implementation
    },
    error =>
    {
        Debug.WriteLine("DomainSearch failure error " + error);
        // ... your implementation
    });

ZeroBounce.Instance.FindDomainByCompanyName(companyName,
    response =>
    {
        Debug.WriteLine("DomainSearch success response " + response);
        // ... your implementation
    },
    error =>
    {
        Debug.WriteLine("DomainSearch failure error " + error);
        // ... your implementation
    });

• The SendFile endpoint allows you to submit a file for bulk email validation

var filePath = "<FILE_PATH>"; // The csv or txt file
var options = new SendFileOptions();

options.ReturnUrl = "https://domain.com/called/after/processing/request";
options.EmailAddressColumn=3;           // The index of "email" column in the file. Index starts at 1
options.FirstNameColumn = 4;            // The index of "first name" column in the file
options.LastNameColumn = 5;             // The index of "last name" column in the file
options.GenderColumn = 6;               // The index of "gender" column in the file
options.IpAddressColumn = 7;            // The index of "IP address" column in the file
options.HasHeaderRow = true;            // If this is `true` the first row is considered as table headers
options.RemoveDuplicate = false;        // If you want the system to remove duplicate emails (true or false, default is true). Please note that if we remove more than 50% of the lines because of duplicates (parameter is true), system will return a 400 bad request error as a safety net to let you know that more than 50% of the file has been modified.
// Optional: request catch-all (phase 2) after phase 1 when Verify+ rules apply — see [v2 send file](https://www.zerobounce.net/docs/email-validation-api-quickstart/v2-send-file)
options.AllowPhase2 = true;

ZeroBounce.Instance.SendFile(
    filePath,
    options,
    response =>
    {
        Debug.WriteLine("SendFile success response " + response);
        // ... your implementation
    },
    error =>
    {
        Debug.WriteLine("SendFile failure error " + error);
        // ... your implementation
    });

Bulk validation uses https://bulkapi.zerobounce.net/v2. See v2 send file, v2 file status, and v2 get file.

• The GetFile endpoint downloads the validation results for a file submitted via SendFile

var fileId = "<FILE_ID>";                       // The returned file ID when calling sendfile API
var localDownloadPath = "<FILE_DOWNLOAD_PATH>"; // The location where the downloaded file will be saved

ZeroBounce.Instance.GetFile(fileId, localDownloadPath,
    response =>
    {
        Debug.WriteLine("GetFile success response " + response);
        // ... your implementation
    },
    error =>
    {
        Debug.WriteLine("GetFile failure error " + error);
        // ... your implementation
    });

Optional query parameters (validation getfile only for ActivityData; scoring ScoringGetFile ignores ActivityData):

ZeroBounce.Instance.GetFile(
    fileId,
    localDownloadPath,
    new ZeroBounce.GetFileOptions
    {
        DownloadType = ZBDownloadType.Combined,  // phase_1 | phase_2 | combined — see v2 get file docs
        ActivityData = true                      // optional; [activity data](https://www.zerobounce.net/docs/activity-data)
    },
    response => { /* ... */ },
    error => { /* ... */ });

ZeroBounce.Instance.ScoringGetFile(
    fileId,
    localDownloadPath,
    new ZeroBounce.GetFileOptions { DownloadType = ZBDownloadType.Phase2 },
    response => { /* ... */ },
    error => { /* ... */ });

phase_2 / combined downloads apply when phase 2 was enabled for the file and file_phase_2_status is Complete. JSON error bodies may still use HTTP 200; the SDK surfaces them via the failure callback.

• Check the status of a file uploaded via SendFile

var fileId = "<FILE_ID>";                       // The returned file ID when calling sendfile API

ZeroBounce.Instance.FileStatus(fileId,
    response =>
    {
        Debug.WriteLine("FileStatus success response " + response);
        // ... your implementation
    },
    error =>
    {
        Debug.WriteLine("FileStatus failure error " + error);
        // ... your implementation
    });

• Deletes a file submitted via SendFile. File can be deleted only when its status is Complete

var fileId = "<FILE_ID>";                       // The returned file ID when calling sendfile API

ZeroBounce.Instance.DeleteFile(fileId,
    response =>
    {
        Debug.WriteLine("DeleteFile success response " + response);
        // ... your implementation
    },
    error =>
    {
        Debug.WriteLine("DeleteFile failure error " + error);
        // ... your implementation
    });

AI Scoring API

• The ScoringSendFile endpoint allows you to submit a file for bulk AI scoring

var filePath = "<FILE_PATH>"; // The csv or txt file

var options = new SendFileOptions();

options.ReturnUrl = "https://domain.com/called/after/processing/request";
options.EmailAddressColumn=3;           // The index of "email" column in the file. Index starts at 1
options.HasHeaderRow = true;            // If this is `true` the first row is considered as table headers
// options.AllowPhase2 is not sent for scoring sendfile (validation bulk only).

ZeroBounce.Instance.ScoringSendFile(
    filePath,
    options,
    response =>
    {
        Debug.WriteLine("SendFile success response " + response);
        // ... your implementation
    },
    error =>
    {
        Debug.WriteLine("SendFile failure error " + error);
        // ... your implementation
    });

• The ScoringGetFile endpoint downloads the results for a file submitted via ScoringSendFile

var fileId = "<FILE_ID>";                       // The returned file ID when calling scoringSendfile API
var localDownloadPath = "<FILE_DOWNLOAD_PATH>"; // The location where the downloaded file will be saved

ZeroBounce.Instance.ScoringGetFile(fileId, localDownloadPath,
    response =>
    {
        Debug.WriteLine("GetFile success response " + response);
        // ... your implementation
    },
    error =>
    {
        Debug.WriteLine("GetFile failure error " + error);
        // ... your implementation
    });

• Check the status of a file uploaded via ScoringSendFile

var fileId = "<FILE_ID>";                       // The returned file ID when calling scoringSendfile API

ZeroBounce.Instance.ScoringFileStatus(fileId,
    response =>
    {
        Debug.WriteLine("FileStatus success response " + response);
        // ... your implementation
    },
    error =>
    {
        Debug.WriteLine("FileStatus failure error " + error);
        // ... your implementation
    });

• Deletes a file submitted via ScoringSendFile. File can be deleted only when its status is Complete

var fileId = "<FILE_ID>";                       // The returned file ID when calling scoringSendfile API

ZeroBounce.Instance.ScoringDeleteFile(fileId,
    response =>
    {
        Debug.WriteLine("DeleteFile success response " + response);
        // ... your implementation
    },
    error =>
    {
        Debug.WriteLine("DeleteFile failure error " + error);
        // ...your implementation
    });

DEVELOPMENT

Run tests with Docker

Preferred: from the parent SDKs folder (where docker-compose.yml lives); the C# tree is mounted into the container so you always test your working copy:

docker compose build csharp
docker compose run --rm csharp

From this directory only (no docker-compose.yml): build the toolchain image, then mount this folder at /app:

docker build -t zerobounce-csharp-sdk:tool .
docker run --rm -v "$(pwd)":/app -w /app zerobounce-csharp-sdk:tool

Test / build (local .NET SDK)

If you have the .NET SDK installed locally, you can still use dotnet test / dotnet build; NuGet publish is Docker-only — use the script below.

Publish

Always use Docker for publishing (pinned SDK, same as the documented workflow). Requires this repo inside the SDKs monorepo and a NuGet API key from https://www.nuget.org/account/apikeys.

export NUGET_API_KEY=your_api_key
./scripts/publish-nuget.sh              # publish current checkout
./scripts/publish-nuget.sh --last-tag   # checkout latest git tag and publish it

For manual docker compose steps and version bumps, see the sdk-docs (NuGet) guide.