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.
• ZBGetFileResponse – When the API returns JSON (e.g. file not ready), the SDK uses Success, Message, and Error and invokes the failure callback with the error 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.

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

• 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
    });

• 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


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

From the parent repository root (the folder that contains all SDKs and docker-compose.yml):

docker compose build csharp
docker compose run --rm csharp

Test (local)

dotnet test

Build

dotnet build

Publish

Prerequisites: NuGet API key from https://www.nuget.org/account/apikeys
If the .NET SDK is not installed, the script uses Docker (requires the repo to be inside the SDKs monorepo with docker-compose.yml at the parent directory).

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

Or run manually:

dotnet restore && dotnet build -c Release && dotnet test --no-build -c Release
dotnet pack ZeroBounceSDK/ZeroBounceSDK.csproj -c Release --no-build
dotnet nuget push ZeroBounceSDK/bin/Release/ZeroBounce.SDK.*.nupkg \
  --api-key $NUGET_API_KEY --source https://api.nuget.org/v3/index.json

For version bump and more detail, see the sdk-docs (NuGet) guide.