documentation.md

WE DO NOT RECOMMEND USING THIS SDK ON A FRONT-END ENVIRONMENT AS THE API KEY WILL BE VISIBLE

INSTALLATION

npm install @zerobounce/zero-bounce-sdk

USAGE

Add the script

<script src="<PATH_TO_SCRIPT/zeroBounceSDK.js"></script>

<script>
const zeroBounce = new ZeroBounceSDK();
</script>

OR

Add npm module

const ZeroBounceSDK = require('@zerobounce/zero-bounce-sdk')

const zeroBounce = new ZeroBounceSDK();

Initialize the sdk with your api key and your preferred api:

zeroBounce.init("<YOUR_API_KEY>", ZeroBounceSDK.ApiURL.DEFAULT_API_URL);

NOTE: all the methods are asynchronous they have to be used with async / await or .then.catch

Examples

Then you can use any of the SDK methods, for example:

• ####### Check how many credits you have left on your account

try {
  const response = await zeroBounce.getCredits();
} catch (error) {
  console.error(error);
}

• ####### Validate an email address

const email = "<EMAIL_ADDRESS>"; // The email address you want to validate

// Using options object (recommended)
try {
  const response = await zeroBounce.validateEmail(email, {
    ip_address: "127.0.0.1", // The IP Address the email signed up from (Optional)
    timeout: 10, // Validation timeout in seconds, 3-60 (Optional)
  });
} catch (error) {
  console.error(error);
}

// Legacy syntax (still supported for backwards compatibility)
// const response = await zeroBounce.validateEmail(email, "127.0.0.1");

• Validate with domain info and greylist processing

// domainInfo adds domain_website_exists and domain_registrant_company_name.
// greylistProcessing re-runs a greylisted address instead of returning unknown.
// callbackUrl is only allowed together with greylistProcessing: true.
try {
  const response = await zeroBounce.validateEmail("<EMAIL_ADDRESS>", {
    domainInfo: true,
    greylistProcessing: true,
    callbackUrl: "https://example.com/zerobounce-callback",
  });
  // While the greylist retry is still running the API returns a message
  // instead of a result; call validateEmail again in about 30 minutes.
  console.log(response.message, response.domain_website_exists);
} catch (error) {
  console.error(error);
}

• S3 and SFTP/FTP bulk jobs

// Amazon S3: https://www.zerobounce.net/docs/api-integrations/amazon-s3-bulk-api
await zeroBounce.emailFinderS3file({ file_name: "lists/leads.csv", has_header_row: true });
await zeroBounce.domainSearchS3file({
  file_name: "lists/leads.csv",
  has_header_row: true,
  remove_duplicates: true,
  return_url: "https://example.com/zerobounce-done",
});

// SFTP/FTP: https://www.zerobounce.net/docs/api-integrations/sftp_bulk_api
// The server, path and protocol come from your ZeroBounce settings.
// file_name is optional for validateSFTPfile only.
await zeroBounce.validateSFTPfile({ has_header_row: true });
await zeroBounce.scoreSFTPfile({ file_name: "my_file.txt", has_header_row: true });
await zeroBounce.emailFinderSFTPfile({ file_name: "my_file.txt", has_header_row: true });
await zeroBounce.domainSearchSFTPfile({ file_name: "my_file.txt", has_header_row: true });

// Without export_path the path from your settings is used.
await zeroBounce.exportSFTPfile({ file_id: "<FILE_ID>", export_path: "/exports" });

• Inbox Placement Tester

// Lives on https://bulkapi.zerobounce.net/api/ipt and spends inbox test credits.
try {
  const providers = await zeroBounce.getInboxPlacementProviders();
  const testTypes = await zeroBounce.getInboxPlacementTestTypes();

  // testType 1 (Email) needs senderEmail; 2 is Unique ID and 3 is Auto Alias.
  const created = await zeroBounce.createInboxPlacementTest({
    name: "October campaign",            // required, at most 64 characters
    testType: 1,
    senderEmail: "news@example.com",
    providers: [{ id: 1, maxSeeds: 5 }], // optional per-provider seed cap
    webhookUrl: "https://example.com/ipt-webhook",
  });

  // Send your campaign to created.emailAddressList, then read the results.
  const result = await zeroBounce.getInboxPlacementTest(created.id);

  const tests = await zeroBounce.listInboxPlacementTests({
    status: "finished",
    page: 1,
    pageSize: 25,
  });

  await zeroBounce.setInboxPlacementWebhook("https://example.com/ipt-webhook");
  const webhook = await zeroBounce.getInboxPlacementWebhook();
  await zeroBounce.deleteInboxPlacementTest(created.id);
} catch (error) {
  console.error(error);
}

• Point an API at a different base URL

// The list evaluator and the Inbox Placement Tester have their own base URLs,
// separate from the main and bulk hosts.
zeroBounce.init("<YOUR_API_KEY>", ZeroBounceSDK.ApiURL.DEFAULT_API_URL, {
  listEvaluatorBaseURL: "https://bulkapi.zerobounce.net/v2/listevaluator",
  inboxPlacementBaseURL: "https://bulkapi.zerobounce.net/api/ipt",
});

• ####### Get api usage from a start date to an end date

const startDate = "2018-01-01"; // The start date of when you want to view API usage
const endDate = "2023-12-12"; // The end date of when you want to view API usage

try {
  const response = await zeroBounce.getApiUsage(startDate, endDate);
} catch (error) {
  console.error(error);
}

• ####### Validate a list of emails

const emailBatch = [
  { email_address: "<EMAIL_ADDRESS>" },
  { email_address: "<EMAIL_ADDRESS>" },
]; // an array containing a list of email objects {email_address: "example@example.com"}

try {
  const response = await zeroBounce.validateBatch(emailBatch);
} catch (error) {
  console.error(error);
}

• ####### Get data about an email activity

const email = "<EMAIL_ADDRESS>"; // The email address you want to get the activity for

try {
  const response = await zeroBounce.getEmailActivity(email);
} catch (error) {
  console.error(error);
}

• ####### Send a csv file containing email addresses to be validated

// Parameters
// ----------
// file: File
//     The csv or txt file to be submitted.
// email_address_column: number
//     The column index of the email address in the file. Index starts from 1.
// return_url: str or null (Optional)
//     The URL will be used to call back when the validation is completed.
// first_name_column: number or null (Optional)
//     The column index of the first name column.
// last_name_column: number or null (Optional)
//     The column index of the last name column.
// gender_column: number or null (Optional)
//     The column index of the gender column.
// ip_address_column: number or null (Optional)
//     The IP Address the email signed up from.
// has_header_row: Boolean (Optional)
//     If the first row from the submitted file is a header row.
// remove_duplicate: Boolean (Optional)
//     If you want the system to remove duplicate emails.
// allowPhase2: Boolean (Optional)
//     When set, sends allow_phase_2 (validation bulk only). See v2 send file API.
const payload = {
  file: "<FILE>",
  email_address_column: "<NUMBER_OF_COLUMN>", //example 3
  return_url: "<RETURN_URL>", // (Optional)
  first_name_column: "<NUMBER_OF_COLUMN>", //example 3 (Optional)
  last_name_column: "<NUMBER_OF_COLUMN>", //example 3 (Optional)
  gender_column: "<NUMBER_OF_COLUMN>", //example 3 (Optional)
  ip_address_column: "<NUMBER_OF_COLUMN>", //example 3 (Optional)
  has_header_row: true / false, // (Optional)
  remove_duplicate: true / false, // (Optional)
  allowPhase2: true, // (Optional)
};

try {
  const response = await zeroBounce.sendFile(payload);
} catch (error) {
  console.error(error);
}

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

Bulk API v2: ZeroBounceSDK.ZBDownloadType provides PHASE_1, PHASE_2, and COMBINED for getFile / getScoringFile. File status responses may include file_phase_2_status. For getFile, pass an optional second argument { downloadType, activityData } (validation only for activityData; getScoringFile does not send activity_data). If the API returns a JSON error body with HTTP 200, the SDK returns a parsed object instead of treating the body as CSV.

• ####### Send a csv file containing email addresses to get the scoring of the emails

// Parameters
// ----------
// file: File
//     The csv or txt file to be submitted.
// email_address_column: number
//     The column index of the email address in the file. Index starts from 1.
// return_url: str or null (Optional)
//     The URL will be used to call back when the validation is completed.
// has_header_row: Boolean (Optional)
//     If the first row from the submitted file is a header row.
// remove_duplicate: Boolean (Optional)
//     If you want the system to remove duplicate emails.
const payload = {
  file: "<FILE>",
  email_address_column: "<NUMBER_OF_COLUMN>", //example 3
  return_url: "<RETURN_URL>", // (Optional)
  has_header_row: true / false,
  remove_duplicate: true / false, // (Optional)
};

try {
  const response = await zeroBounce.sendScoringFile(payload);
} catch (error) {
  console.error(error);
}

• ####### The completion status of a previously sent file

const fileId = "<FILE_ID>"; // The id of a previously sent file

try {
  const response = await zeroBounce.getFileStatus(fileId);
} catch (error) {
  console.error(error);
}

• ####### The completion status of a previously sent scoring file

const fileId = "<FILE_ID>"; // The id of a previously sent file

try {
  const response = await zeroBounce.getScoringFileStatus(fileId);
} catch (error) {
  console.error(error);
}

• ####### Get the file with the validated data

const fileId = "<FILE_ID>"; // The id of a previously sent file

try {
  const response = await zeroBounce.getFile(fileId);
} catch (error) {
  console.error(error);
}

Optional query parameters (see v2 get file API):

await zeroBounce.getFile(fileId, {
  downloadType: ZeroBounceSDK.ZBDownloadType.COMBINED,
  activityData: true,
});

• ####### Get the file with the scoring data

const fileId = "<FILE_ID>"; // The id of a previously sent file

try {
  const response = await zeroBounce.getScoringFile(fileId);
} catch (error) {
  console.error(error);
}

await zeroBounce.getScoringFile(fileId, {
  downloadType: ZeroBounceSDK.ZBDownloadType.PHASE_2,
});

• ####### Delete the file with the validated data

const fileId = "<FILE_ID>"; // The id of a previously sent file

try {
  const response = await zeroBounce.deleteFile(fileId);
} catch (error) {
  console.error(error);
}

• ####### Delete the file with the scoring data

const fileId = "<FILE_ID>"; // The id of a previously sent file

try {
  const response = await zeroBounce.deleteScoringFile(fileId);
} catch (error) {
  console.error(error);
}

• ####### Email finder - Test a variety of patterns and combinations in real time until it identifies a valid business email.

// Parameters
// ----------
// domain: String
//     The email domain for which to find the email format. 
// company_name: String
//     The company name for which to find the email format.
// first_name: String
//     The first name of the person whose email format is being searched.
// middle_name: String or null (Optional)
//     The middle name of the person whose email format is being searched.
// last_name: String or null (Optional)
//     The last name of the person whose email format is being searched.

const domainPayload = {
  domain: "<DOMAIN>",
  first_name: "<FIRST_NAME>",
  middle_name: "<MIDDLE_NAME>",
  last_name: "<LAST_NAME>"
}

const companyNamePayload = {
  company_name: "<COMPANY_NAME>",
  first_name: "<FIRST_NAME>",
  middle_name: "<MIDDLE_NAME>",
  last_name: "<LAST_NAME>"
}

try {
  const domainResponse = await zeroBounce.findEmailByDomain(domainPayload);
  const companyNameResponse = await zeroBounce.findEmailByCompanyName(companyNamePayload);
} catch (error) {
  console.error(error);
}

• ####### Domain Search - Find the domain based on a given domain name or company name

// Parameters
// ----------
// domain: String
//     The domain name for which to find the email format. 
// company_name: String
//     The company name for which to find the email format.

const domainPayload = {
  domain: "<DOMAIN>"
}

const companyNamePayload = {
  company_name: "<COMPANY_NAME>"
}

try {
  const domainResponse = await zeroBounce.findEmailFormatByDomain(domainPayload);
  const companyNameResponse = await zeroBounce.findEmailFormatByCompanyName(companyNamePayload);
} catch (error) {
  console.error(error);
}

Any of the following email addresses can be used for testing the API, no credits are charged for these test email addresses:

• disposable@example.com
• invalid@example.com
• valid@example.com
• toxic@example.com
• donotmail@example.com
• spamtrap@example.com
• abuse@example.com
• unknown@example.com
• catch_all@example.com
• antispam_system@example.com
• does_not_accept_mail@example.com
• exception_occurred@example.com
• failed_smtp_connection@example.com
• failed_syntax_check@example.com
• forcible_disconnect@example.com
• global_suppression@example.com
• greylisted@example.com
• leading_period_removed@example.com
• mail_server_did_not_respond@example.com
• mail_server_temporary_error@example.com
• mailbox_quota_exceeded@example.com
• mailbox_not_found@example.com
• no_dns_entries@example.com
• possible_trap@example.com
• possible_typo@example.com
• role_based@example.com
• timeout_exceeded@example.com
• unroutable_ip_address@example.com
• free_email@example.com

You can use this IP to test the GEO Location in the API.

• 99.110.204.1

Development

After checking out the repo run tests

npm test

You should see an output like this

Test Suites: 1 passed, 1 total
Tests:       54 passed, 54 total
Snapshots:   0 total
Time:        2.596 s, estimated 3 s
Ran all test suites.