C# SDK
You can find our C# SDK, example usage, and documentation on our official GitHub page below:
Was this page helpful?
You can find our C# SDK, example usage, and documentation on our official GitHub page below:
Was this page helpful?
You can install by searching for ZeroBounce.SDK in the NuGet package manager browser, or run:
dotnet add package ZeroBounce.SDK
From the Visual Studio Package Manager Console:
Install-Package ZeroBounce.SDK
Import the sdk in your file, and the namespaces the examples below use:
using System;
using System.Collections.Generic;
using System.Diagnostics; // Debug.WriteLine in the examples below
using Newtonsoft.Json.Linq; // JObject / JToken results of the newer endpoints
using ZeroBounceSDK;
Initialize the sdk with your api key and preferred api:
ZeroBounce.Instance.Initialize("<YOUR_API_KEY>", ZBApiURL.ApiDefaultURL);
Then you can use any of the SDK methods, for example:
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
});
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
});
ZeroBounce.Instance.GetCredits(
response =>
{
Debug.WriteLine("GetCredits success response " + response);
// your implementation
},
error =>
{
Debug.WriteLine("GetCredits failure error " + error);
// your implementation
});
var startDate = new DateTime(2024, 01, 01); // The start date of when you want to view API usage
var endDate = new DateTime(2024, 01, 31); // The end date of when you want to view API usage
ZeroBounce.Instance.GetApiUsage(startDate, endDate,
response =>
{
Debug.WriteLine("GetApiUsage success response " + response);
// ... your implementation
},
error =>
{
Debug.WriteLine("GetApiUsage failure error " + error);
// ... your implementation
});
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
});
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
});
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
});
var filePath = "<FILE_PATH>"; // The csv or txt file
var options = new ZeroBounce.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. Left unset, it is not sent.
options.RemoveDuplicate = false; // If you want the system to remove duplicate emails (true or false, default is true). Left unset, it is not sent and the API removes duplicates. 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 phase 2 (catch-all) after phase 1 — [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.
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 download_type and activity_data (validation only for activity_data):
var fileId = "<FILE_ID>";
var localDownloadPath = "<FILE_DOWNLOAD_PATH>";
ZeroBounce.Instance.GetFile(
fileId,
localDownloadPath,
new ZeroBounce.GetFileOptions
{
DownloadType = ZBDownloadType.Combined,
ActivityData = true
},
response => { /* ... */ },
error => { /* ... */ });
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
});
Completevar 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
});
var filePath = "<FILE_PATH>"; // The csv or txt file
var options = new ZeroBounce.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
// AllowPhase2 is not used for scoring sendfile.
ZeroBounce.Instance.ScoringSendFile(
filePath,
options,
response =>
{
Debug.WriteLine("SendFile success response " + response);
// ... your implementation
},
error =>
{
Debug.WriteLine("SendFile failure error " + error);
// ... your implementation
});
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
});
var fileId = "<FILE_ID>";
var localDownloadPath = "<FILE_DOWNLOAD_PATH>";
ZeroBounce.Instance.ScoringGetFile(
fileId,
localDownloadPath,
new ZeroBounce.GetFileOptions { DownloadType = ZBDownloadType.Phase2 },
response => { /* ... */ },
error => { /* ... */ });
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
});
Completevar 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
});
Validate takes a ZBValidateOptions. An option left null is not sent, and
booleans go on the wire as the strings "true"/"false".
var options = new ZBValidateOptions
{
Timeout = 30, // 3-60 seconds
ActivityData = true, // fills ActiveInDays / ActiveFirstSeen
VerifyPlus = true,
DomainInfo = true, // fills DomainWebsiteExists / DomainRegistrantCompanyName
GreylistProcessing = true,
CallbackUrl = "https://example.com/greylist",
UsePost = true // form-encoded POST /v2/validate instead of GET
};
ZeroBounce.Instance.Validate("<EMAIL>", "", options,
response => Console.WriteLine(response.Status),
error => Console.WriteLine(error));
CallbackUrl is where the greylist retry posts its result, so it is rejected
without GreylistProcessing = true — before any request is sent. While that
retry is still running the API answers with a Message instead of a result,
which lands on response.Message.
ValidateBatch takes the same ZBValidateOptions, but sends only Timeout
(10-120 seconds there), ActivityData and VerifyPlus. It ignores UsePost,
DomainInfo, GreylistProcessing and CallbackUrl without checking them.
Queue a job on a file that already sits in your Amazon S3 bucket, or on your
SFTP/FTP server. See the S3
and SFTP docs.
These live on the bulkapi host without the /v2 path.
The examples from here on pass ok and error for the two callbacks. Any
lambda or method of the right type will do; for example:
void ok<T>(T response) => Console.WriteLine(response);
void error(string message) => Console.WriteLine(message);
var zb = ZeroBounce.Instance;
// Amazon S3. FileName is the full path, as returned by ListS3Files.
// FileName and ReturnUrl are required on every one of these jobs.
var s3 = new ZeroBounce.BulkFileJobOptions
{
FileName = "lists/leads.csv",
HasHeaderRow = true,
ReturnUrl = "https://example.com/zerobounce-done"
};
zb.EmailFinderS3File(s3, ok, error);
zb.DomainSearchS3File(s3, ok, error);
// Validate and score take the same two required fields, plus their own.
zb.ValidateS3File(new ZeroBounce.ValidateS3FileOptions
{
FileName = "lists/leads.csv",
ReturnUrl = "https://example.com/zerobounce-done",
HasHeaderRow = true,
EmailAddressColumn = 1
}, ok, error);
zb.ScoreS3File(new ZeroBounce.ScoreS3FileOptions
{
FileName = "lists/leads.csv",
ReturnUrl = "https://example.com/zerobounce-done",
HasHeaderRow = true
}, ok, error);
zb.ExportS3File("<FILE_ID>", "bucket-out", ok, error);
// SFTP/FTP. The server, path and protocol come from your ZeroBounce settings.
// The docs list FileName as optional for ValidateSFTPFile, but the live API
// requires it there too.
var sftp = new ZeroBounce.BulkFileJobOptions
{
FileName = "my_file.txt",
HasHeaderRow = true,
ReturnUrl = "https://example.com/zerobounce-done"
};
zb.ValidateSFTPFile(sftp, ok, error);
zb.ScoreSFTPFile(sftp, ok, error);
zb.EmailFinderSFTPFile(sftp, ok, error);
zb.DomainSearchSFTPFile(sftp, ok, error);
// Note the field: this one takes export_path, not export_bucket.
// null uses the export path from your settings.
zb.ExportSFTPFile("<FILE_ID>", "/exports", ok, error);
Runs on its own host, authenticates with an Authorization: Bearer header, and
sends camelCase JSON bodies. It spends the account's inbox-test credits.
var zb = ZeroBounce.Instance;
zb.GetInboxPlacementProviders(ok, error);
zb.GetInboxPlacementTestTypes(ok, error);
zb.CreateInboxPlacementTest("Launch",
new ZeroBounce.CreateInboxPlacementTestOptions
{
TestType = 1,
SenderEmail = "news@example.com",
WebhookUrl = "https://example.com/ipt-webhook"
},
ok, error);
// Send your campaign to the seeds you got back, then read the results.
zb.GetInboxPlacementTest("<TEST_ID>", ok, error);
zb.ListInboxPlacementTests(
new ZeroBounce.ListInboxPlacementTestsOptions { Status = "finished", Page = 1 }, ok, error);
zb.SetInboxPlacementWebhook("https://example.com/ipt-webhook", ok, error);
zb.GetInboxPlacementWebhook(ok, error);
zb.DeleteInboxPlacementTest("<TEST_ID>", ok, error);
The list evaluator and the Inbox Placement Tester are separate hosts, so overriding the main base URL alone leaves them pointing at the live API.
ZeroBounce.Instance.SetListEvaluatorBaseUrl("https://bulkapi.zerobounce.net/v2/listevaluator");
ZeroBounce.Instance.SetInboxPlacementBaseUrl("https://bulkapi.zerobounce.net/api/ipt");