Zerobounce

Ruby client for Zerobounce.net API. Developed based on this version by Aaron Frase.

Usage

Add this line to your application's Gemfile:

gem 'zerobounce-sdk'

And then execute:

$bundle

Or install it yourself as:

$gem install zerobounce-sdk

Import

require 'zerobounce'

Configuration

Setting API Key

Method 1: Using configure block (recommended)

Zerobounce.configure do |config|
  config.apikey = '<zerobounce-api-key>'
  # Optional: Set custom API URLs
  config.api_root_url = 'https://api.zerobounce.net/v2'
  config.bulk_api_root_url = 'https://bulkapi.zerobounce.net/v2'
end

Method 1a: Using ApiUrls constants (convenience)

# Global API (default)
Zerobounce.configure do |config|
  config.apikey = '<zerobounce-api-key>'
  config.api_root_url = Zerobounce::ApiUrls::DEFAULT_URL
  config.bulk_api_root_url = Zerobounce::ApiUrls::BULK_DEFAULT_URL
end

# European API (convenience)
Zerobounce.configure do |config|
  config.apikey = '<zerobounce-api-key>'
  config.api_root_url = Zerobounce::ApiUrls::EU_URL
  config.bulk_api_root_url = Zerobounce::ApiUrls::BULK_DEFAULT_URL
end

# US API (convenience)
Zerobounce.configure do |config|
  config.apikey = '<zerobounce-api-key>'
  config.api_root_url = Zerobounce::ApiUrls::US_URL
  config.bulk_api_root_url = Zerobounce::ApiUrls::BULK_DEFAULT_URL
end

Method 2: Direct configuration

Zerobounce.config.apikey = '<zerobounce-api-key>'
# Optional: Set custom API URLs
Zerobounce.config.api_root_url = 'https://api.zerobounce.net/v2'
Zerobounce.config.bulk_api_root_url = 'https://bulkapi.zerobounce.net/v2'

Method 3: Using environment variables

Create a .env file in your project root:

ZEROBOUNCE_API_KEY=your_api_key_here
ZEROBOUNCE_API_URL=https://api.zerobounce.net/v2
ZEROBOUNCE_BULK_API_URL=https://bulkapi.zerobounce.net/v2

The gem will automatically load these environment variables when initialized. No additional configuration needed in your code.

Method 4: System environment variables

Set environment variables in your system:

export ZEROBOUNCE_API_KEY=your_api_key_here
export ZEROBOUNCE_API_URL=https://api.zerobounce.net/v2
export ZEROBOUNCE_BULK_API_URL=https://bulkapi.zerobounce.net/v2

API URL Configuration Details

Default Behavior

If you don't specify api_root_url or bulk_api_root_url, the gem will use the following defaults:

• Main API: https://api.zerobounce.net/v2
• Bulk API: https://bulkapi.zerobounce.net/v2

These defaults are defined in the Zerobounce::ApiUrls class constants:

• Zerobounce::ApiUrls::DEFAULT_URL - Main API URL (Global)
• Zerobounce::ApiUrls::EU_URL - European API URL
• Zerobounce::ApiUrls::US_URL - US API URL
• Zerobounce::ApiUrls::BULK_DEFAULT_URL - Bulk API URL

Using ApiUrls Constants

You can use the predefined constants in your configuration. The EU and US URLs are provided as convenience options:

# Global API (default)
Zerobounce.configure do |config|
  config.apikey = 'your-api-key'
  config.api_root_url = Zerobounce::ApiUrls::DEFAULT_URL
  config.bulk_api_root_url = Zerobounce::ApiUrls::BULK_DEFAULT_URL
end

# European API
Zerobounce.configure do |config|
  config.apikey = 'your-api-key'
  config.api_root_url = Zerobounce::ApiUrls::EU_URL
  config.bulk_api_root_url = Zerobounce::ApiUrls::BULK_DEFAULT_URL
end

# US API
Zerobounce.configure do |config|
  config.apikey = 'your-api-key'
  config.api_root_url = Zerobounce::ApiUrls::US_URL
  config.bulk_api_root_url = Zerobounce::ApiUrls::BULK_DEFAULT_URL
end

Custom API URLs

You can override the default URLs for custom deployments or testing:

Zerobounce.configure do |config|
  config.apikey = 'your-api-key'
  # Use custom URLs (e.g., for testing or custom deployments)
  config.api_root_url = 'https://custom-api.example.com/v2'
  config.bulk_api_root_url = 'https://custom-bulk-api.example.com/v2'
end

Environment Variable Priority

The configuration follows this priority order (highest to lowest):

1. Explicitly set in code (config.api_root_url = '...')
2. Environment variables (ZEROBOUNCE_API_URL, ZEROBOUNCE_BULK_API_URL)
3. Default constants (ApiUrls::DEFAULT_URL, ApiUrls::BULK_DEFAULT_URL)

Credits

Zerobounce.credits
=> 79   # returns -1 for invalid key

Activity

Zerobounce.activity('ss@gmail.com')
=> {"found"=>true, "active_in_days"=>"180"}

Usage statistics

Zerobounce.api_usage(Date.today, Date.today)
=>
{"total"=>0,
 "status_valid"=>0,
 "status_invalid"=>0,
 "status_catch_all"=>0,
 "status_do_not_mail"=>0,
 "status_spamtrap"=>0,
 "status_unknown"=>0,
 "sub_status_toxic"=>0,
 "sub_status_disposable"=>0,
 "sub_status_role_based"=>0,
 "sub_status_possible_trap"=>0,
 "sub_status_global_suppression"=>0,
 "sub_status_timeout_exceeded"=>0,
 "sub_status_mail_server_temporary_error"=>0,
 "sub_status_mail_server_did_not_respond"=>0,
 "sub_status_greylisted"=>0,
 "sub_status_antispam_system"=>0,
 "sub_status_does_not_accept_mail"=>0,
 "sub_status_exception_occurred"=>0,
 "sub_status_failed_syntax_check"=>0,
 "sub_status_mailbox_not_found"=>0,
 "sub_status_unroutable_ip_address"=>0,
 "sub_status_possible_typo"=>0,
 "sub_status_no_dns_entries"=>0,
 "sub_status_role_based_catch_all"=>0,
 "sub_status_mailbox_quota_exceeded"=>0,
 "sub_status_forcible_disconnect"=>0,
 "sub_status_failed_smtp_connection"=>0,
 "sub_status_mx_forward"=>0,
 "sub_status_alternate"=>0,
 "sub_status_blocked"=>0,
 "sub_status_allowed"=>0,
 "start_date"=>"4/28/2023",
 "end_date"=>"4/28/2023"}

Email Validation

Validate single eMail

Zerobounce.validate('valid@example.com')
# Zerobounce.validate('valid@example.com', '192.168.0.1') # optional IP address
=>
{"address"=>"valid@example.com",
 "status"=>"valid",
 "sub_status"=>"",
 "free_email"=>false,
 "did_you_mean"=>nil,
 "account"=>nil,
 "domain"=>nil,
 "domain_age_days"=>"9692",
 "smtp_provider"=>"example",
 "mx_found"=>"true",
 "mx_record"=>"mx.example.com",
 "firstname"=>"zero",
 "lastname"=>"bounce",
 "gender"=>"male",
 "country"=>nil,
 "region"=>nil,
 "city"=>nil,
 "zipcode"=>nil,
 "processed_at"=>"2023-04-28 15:18:45.631"}

Validate batch

emails
=>
["disposable@example.com",
 "invalid@example.com",
 "valid@example.com",
 "toxic@example.com",
 "donotmail@example.com",
 "spamtrap@example.com"]

# ip_addresses
=> ["192.168.0.1", "192.168.0.1", "192.168.0.1", "192.168.0.1", "192.168.0.1", "192.168.0.1"]
# Zerobounce.validate_batch(emails, ip_addresses) # optional ip_addresses parameter

Zerobounce.validate_batch(emails)
=>
[{"address"=>"disposable@example.com",
  "status"=>"do_not_mail",
  "sub_status"=>"disposable",
  "free_email"=>false,
  "did_you_mean"=>nil,
  "account"=>nil,
  "domain"=>nil,
  "domain_age_days"=>"9692",
  "smtp_provider"=>"example",
  "mx_found"=>"true",
  "mx_record"=>"mx.example.com",
  "firstname"=>"zero",
  "lastname"=>"bounce",
  "gender"=>"male",
  "country"=>nil,
  "region"=>nil,
  "city"=>nil,
  "zipcode"=>nil,
  "processed_at"=>"2023-04-28 15:21:44.340"},
 {"address"=>"invalid@example.com",
  "status"=>"invalid",
  "sub_status"=>"mailbox_not_found",
  "free_email"=>false,
  "did_you_mean"=>nil,
  "account"=>nil,
  "domain"=>nil,
  "domain_age_days"=>"9692",
  "smtp_provider"=>"example",
  "mx_found"=>"true",
  "mx_record"=>"mx.example.com",
  "firstname"=>"zero",
  "lastname"=>"bounce",
  "gender"=>"male",
  "country"=>nil,
  "region"=>nil,
  "city"=>nil,
  "zipcode"=>nil,
  "processed_at"=>"2023-04-28 15:21:44.340"},
 {"address"=>"valid@example.com",
  "status"=>"valid",
  "sub_status"=>"",
  "free_email"=>false,
  "did_you_mean"=>nil,
  "account"=>nil,
  "domain"=>nil,
  "domain_age_days"=>"9692",
  "smtp_provider"=>"example",
  "mx_found"=>"true",
  "mx_record"=>"mx.example.com",
  "firstname"=>"zero",
  "lastname"=>"bounce",
  "gender"=>"male",
  "country"=>nil,
  "region"=>nil,
  "city"=>nil,
  "zipcode"=>nil,
  "processed_at"=>"2023-04-28 15:21:44.340"},
 {"address"=>"toxic@example.com",
  "status"=>"do_not_mail",
  "sub_status"=>"toxic",
  "free_email"=>false,
  "did_you_mean"=>nil,
  "account"=>nil,
  "domain"=>nil,
  "domain_age_days"=>"9692",
  "smtp_provider"=>"example",
  "mx_found"=>"true",
  "mx_record"=>"mx.example.com",
  "firstname"=>"zero",
  "lastname"=>"bounce",
  "gender"=>"male",
  "country"=>nil,
  "region"=>nil,
  "city"=>nil,
  "zipcode"=>nil,
  "processed_at"=>"2023-04-28 15:21:44.340"},
 {"address"=>"donotmail@example.com",
  "status"=>"do_not_mail",
  "sub_status"=>"role_based",
  "free_email"=>false,
  "did_you_mean"=>nil,
  "account"=>nil,
  "domain"=>nil,
  "domain_age_days"=>"9692",
  "smtp_provider"=>"example",
  "mx_found"=>"true",
  "mx_record"=>"mx.example.com",
  "firstname"=>"zero",
  "lastname"=>"bounce",
  "gender"=>"male",
  "country"=>nil,
  "region"=>nil,
  "city"=>nil,
  "zipcode"=>nil,
  "processed_at"=>"2023-04-28 15:21:44.340"},
 {"address"=>"spamtrap@example.com",
  "status"=>"spamtrap",
  "sub_status"=>"",
  "free_email"=>false,
  "did_you_mean"=>nil,
  "account"=>nil,
  "domain"=>nil,
  "domain_age_days"=>"9692",
  "smtp_provider"=>"example",
  "mx_found"=>"true",
  "mx_record"=>"mx.example.com",
  "firstname"=>"zero",
  "lastname"=>"bounce",
  "gender"=>"male",
  "country"=>nil,
  "region"=>nil,
  "city"=>nil,
  "zipcode"=>nil,
  "processed_at"=>"2023-04-28 15:21:44.340"}]

Batch File Validation

Send file

# sample file can be found in the files folder of this repository
 validate_file_path = File.join(Dir.pwd, 'files', 'validation.csv')
=> "/home/zb/wrappers/ruby-test/files/validation.csv"
 Zerobounce.validate_file_send(validate_file_path)
=>
{"success"=>true,
 "message"=>"File Accepted",
 "file_name"=>"validation.csv",
 "file_id"=>"75d854a6-565c-49f9-b4c8-b3344480ec4c"}
 # file_id will be required for next steps
 # optional named parameters:
    email_address_column: 1,
    first_name_column: 2,
    last_name_column: 3,
    gender_column: 4,
    has_header_row: true,
    return_url: nil         # results callback url
 # Zerobounce.validate_file_send(validate_file_path, email_address_column: 1, gender_column: 4)

Check file

file_id = "75d854a6-565c-49f9-b4c8-b3344480ec4c"
=> "75d854a6-565c-49f9-b4c8-b3344480ec4c"
Zerobounce.validate_file_check(file_id)
=>
{"success"=>true,
 "file_id"=>"75d854a6-565c-49f9-b4c8-b3344480ec4c",
 "file_name"=>"validation.csv",
 "upload_date"=>"2023-04-28T15:25:41Z",
 "file_status"=>"Greylisted",
 "complete_percentage"=>"0%",
 "error_reason"=>nil,
 "return_url"=>nil}

Get file

file_id = "75d854a6-565c-49f9-b4c8-b3344480ec4c"
=> "75d854a6-565c-49f9-b4c8-b3344480ec4c"
Zerobounce.validate_file_get(file_id)
=> "\"email\",\"first\",\"last\",\"gender\",\"ip\",\"ZB Status\",\"ZB Sub Status\",\"ZB Account\",\"ZB Domain\",\"ZB First Name\",\"ZB Last Name\",\"ZB Gender\",\"ZB Free Email\",\"ZB MX Found\",\"ZB MX Record\",\"ZB SMTP Provider\",\"ZB Did You Mean\"\n\"disposable@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"disposable\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"invalid@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"mailbox_not_found\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"valid@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"valid\",\"\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"toxic@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"toxic\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"donotmail@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"role_based\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"spamtrap@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"spamtrap\",\"\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"abuse@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"abuse\",\"\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"unknown@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"mail_server_temporary_error\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"catch_all@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"catch-all\",\"\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"antispam_system@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"antispam_system\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"does_not_accept_mail@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"does_not_accept_mail\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"exception_occurred@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"exception_occurred\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"failed_smtp_connection@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"failed_smtp_connection\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"failed_syntax_check@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"failed_syntax_check\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"forcible_disconnect@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"forcible_disconnect\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"global_suppression@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"global_suppression\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"greylisted@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"greylisted\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"leading_period_removed@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"valid\",\"leading_period_removed\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"mail_server_did_not_respond@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"mail_server_did_not_respond\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"mail_server_temporary_error@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"mail_server_temporary_error\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"mailbox_quota_exceeded@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"mailbox_quota_exceeded\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"mailbox_not_found@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"mailbox_not_found\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"no_dns_entries@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"no_dns_entries\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"possible_trap@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"possible_trap\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"possible_typo@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"possible_typo\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"role_based@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"role_based\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"timeout_exceeded@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"unknown\",\"timeout_exceeded\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"unroutable_ip_address@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"invalid\",\"unroutable_ip_address\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"free_email@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"valid\",\"\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"True\",\"true\",\"mx.example.com\",\"example\",\"\"\n\"role_based_catch_all@example.com\",\"First\",\"Last\",\"male\",\"127.0.0.1\",\"do_not_mail\",\"role_based_catch_all\",\"\",\"\",\"zero\",\"bounce\",\"male\",\"False\",\"true\",\"mx.example.com\",\"example\",\"\"\n"

Delete file

file_id = "75d854a6-565c-49f9-b4c8-b3344480ec4c"
=> "75d854a6-565c-49f9-b4c8-b3344480ec4c"
Zerobounce.validate_file_delete(file_id)
=>
{"success"=>true,
 "message"=>"File Deleted",
 "file_name"=>"validation.csv",
 "file_id"=>"75d854a6-565c-49f9-b4c8-b3344480ec4c"}

AI Scoring

Send file

scoring_file_path = File.join(Dir.pwd, 'files', 'scoring.csv')
=> "/home/odin/zb/wrappers/ruby-test/files/scoring.csv"
Zerobounce.scoring_file_send(scoring_file_path)
=>
{"success"=>true,
 "message"=>"File Accepted",
 "file_name"=>"scoring.csv",
 "file_id"=>"89fb7262-b845-4fa1-aa25-e486347ec64e"}
# file_id will be required for the next steps
# optional named parameters
    email_address_column: 1,
    has_header_row: true,
    return_url: nil         # results callback url
# Zerobounce.scoring_file_send(scoring_file_path, email_address_column: 1)

File check

file_id = "89fb7262-b845-4fa1-aa25-e486347ec64e"
=> "89fb7262-b845-4fa1-aa25-e486347ec64e"
Zerobounce.scoring_file_check(file_id)
=>
{"success"=>true,
 "file_id"=>"89fb7262-b845-4fa1-aa25-e486347ec64e",
 "file_name"=>"scoring.csv",
 "upload_date"=>"2023-04-28T16:57:18Z",
 "file_status"=>"Complete",
 "complete_percentage"=>"100% Complete.",
 "return_url"=>nil}

Get file

file_id = "89fb7262-b845-4fa1-aa25-e486347ec64e"
=> "89fb7262-b845-4fa1-aa25-e486347ec64e"
Zerobounce.scoring_file_get(file_id)
=> "\"email\",\"ZeroBounceQualityScore\"\r\n\"disposable@example.com\",\"0\"\r\n\"invalid@example.com\",\"10\"\r\n\"valid@example.com\",\"10\"\r\n\"toxic@example.com\",\"2\"\r\n\"donotmail@example.com\",\"0\"\r\n\"spamtrap@example.com\",\"0\"\r\n\"abuse@example.com\",\"10\"\r\n\"unknown@example.com\",\"10\"\r\n\"catch_all@example.com\",\"10\"\r\n\"antispam_system@example.com\",\"0\"\r\n\"does_not_accept_mail@example.com\",\"0\"\r\n\"exception_occurred@example.com\",\"0\"\r\n\"failed_smtp_connection@example.com\",\"0\"\r\n\"failed_syntax_check@example.com\",\"0\"\r\n\"forcible_disconnect@example.com\",\"0\"\r\n\"global_suppression@example.com\",\"0\"\r\n\"greylisted@example.com\",\"0\"\r\n\"leading_period_removed@example.com\",\"0\"\r\n\"mail_server_did_not_respond@example.com\",\"0\"\r\n\"mail_server_temporary_error@example.com\",\"0\"\r\n\"mailbox_quota_exceeded@example.com\",\"0\"\r\n\"mailbox_not_found@example.com\",\"0\"\r\n\"no_dns_entries@example.com\",\"0\"\r\n\"possible_trap@example.com\",\"0\"\r\n\"possible_typo@example.com\",\"0\"\r\n\"role_based@example.com\",\"0\"\r\n\"timeout_exceeded@example.com\",\"0\"\r\n\"unroutable_ip_address@example.com\",\"0\"\r\n\"free_email@example.com\",\"0\"\r\n\"role_based_catch_all@example.com\",\"0\""

Delete file

file_id = "89fb7262-b845-4fa1-aa25-e486347ec64e"
=> "89fb7262-b845-4fa1-aa25-e486347ec64e"
Zerobounce.validate_file_delete(file_id)
=> {"success"=>false, "message"=>"File cannot be found."}

More details on CSV file submission and CSV result retrieval

This applies for both 'Email validation' and 'AI Scoring' functionalities.

The data of the submitted CSV file will be included in the result CSV file. Therefore, the first columns of the result CSV file will consist of the submitted data and the following columns will provide information specific to each functionality.

'Email validation'

The additional columns that would be included in result CSV file:

• ZB Status
• ZB Sub Status
• ZB Account
• ZB Domain
• ZB First Name
• ZB Last Name
• ZB Gender
• ZB Free Email
• ZB MX Found
• ZB MX Record
• ZB SMTP Provider
• ZB Did You Mean
• ZB City
• ZB Region/State
• ZB Zip Code
• ZB Country

When has_header_row: true is provided to validate_file_send() method, original columns of the submitted file will be retained.

When has_header_row: false, the columns that were explicitly specified in validate_file_send() will be given the following column title:

email_address_column    => "Email Address"
first_name_column       => "First Name"
last_name_column        => "Last Name"
gender_column           => "Gender"

Any additional that were not (or can not be) specified by parameters, will be given column title "Custom".

'AI Scoring':

The additional column that would be included in result CSV file:

• ZeroBounceQualityScore

When has_header_row: true is provided to scoring_file_send() method, original columns of the submitted file will be retained.

When has_header_row: false is provided to scoring_file_send() method, column title for the email column (as well as the other columns) will be Email Address.

Email Finder

Guess Format by Domain

# New keyword argument syntax (recommended)
Zerobounce.guessformat(domain: "zerobounce.net")
=>
{"email"=>"",
 "domain"=>"zerobounce.net",
 "format"=>"first.last",
 "status"=>"",
 "sub_status"=>"",
 "confidence"=>"high",
 "did_you_mean"=>"",
 "failure_reason"=>"",
 "other_domain_formats"=>
  [{"format"=>"first", "confidence"=>"high"},
   {"format"=>"last.first", "confidence"=>"high"},
   {"format"=>"lfirst", "confidence"=>"high"},
   {"format"=>"lastfirst", "confidence"=>"high"},
   {"format"=>"firstl", "confidence"=>"high"},
   {"format"=>"last", "confidence"=>"medium"},
   {"format"=>"first.middle.last", "confidence"=>"medium"},
   {"format"=>"first-last", "confidence"=>"medium"},
   {"format"=>"l.first", "confidence"=>"medium"},
   {"format"=>"f.last", "confidence"=>"medium"},
   {"format"=>"f-last", "confidence"=>"medium"},
   {"format"=>"first.l", "confidence"=>"medium"},
   {"format"=>"first-l", "confidence"=>"medium"},
   {"format"=>"firstlast", "confidence"=>"medium"},
   {"format"=>"first_l", "confidence"=>"medium"},
   {"format"=>"f_last", "confidence"=>"medium"},
   {"format"=>"last.f", "confidence"=>"medium"},
   {"format"=>"last-f", "confidence"=>"medium"},
   {"format"=>"last-first", "confidence"=>"medium"},
   {"format"=>"first_last", "confidence"=>"medium"},
   {"format"=>"last_f", "confidence"=>"medium"},
   {"format"=>"last_first", "confidence"=>"medium"},
   {"format"=>"flast", "confidence"=>"medium"},
   {"format"=>"lastf", "confidence"=>"medium"},
   {"format"=>"l-first", "confidence"=>"low"},
   {"format"=>"l_first", "confidence"=>"low"}]}

# With names for better accuracy (new syntax)
Zerobounce.guessformat(domain: "zerobounce.net", first_name: "John", middle_name: 'Deere', last_name: "Doe")

# Backwards compatible syntax (still supported)
Zerobounce.guessformat("zerobounce.net")
Zerobounce.guessformat("zerobounce.net", first_name: "John", middle_name: 'Deere', last_name: "Doe")

Guess Format by Company Name

# New keyword argument syntax (recommended)
Zerobounce.guessformat(company_name: "Zero Bounce")
=>
{"email"=>"",
 "company_name"=>"Zero Bounce",
 "format"=>"first.last",
 "status"=>"",
 "sub_status"=>"",
 "confidence"=>"high",
 "did_you_mean"=>"",
 "failure_reason"=>"",
 "other_domain_formats"=>[...]}

# With names for better accuracy (new syntax)
Zerobounce.guessformat(first_name: "John", last_name: "Doe", company_name: "Zero Bounce")

Find Email Address

# Find email by domain
Zerobounce.find_email("John", domain: "zerobounce.net")
=>
{
  "email": "john@zerobounce.net",
  "email_confidence": "medium",
  "domain": "zerobounce.net",
  "company_name": "ZeroBounce",
  "did_you_mean": "",
  "failure_reason": ""
}

# Find email by company name
Zerobounce.find_email("John", company_name: "Zero Bounce")
=>
{
  "email": "john@zerobounce.net",
  "email_confidence": "medium",
  "domain": "zerobounce.net",
  "company_name": "ZeroBounce",
  "did_you_mean": "",
  "failure_reason": ""
}

# With additional name information for better accuracy
Zerobounce.find_email("John", domain: "zerobounce.net", middle_name: "Deere", last_name: "Doe")

Find Domain Information

# Find domain format by domain
Zerobounce.find_domain(domain: "zerobounce.net")
=>
{
  "domain": "zerobounce.net",
  "company_name": "Hertza, LLC",
  "format": "first.last",
  "confidence": "high",
  "did_you_mean": "",
  "failure_reason": "",
  "other_domain_formats": [
    {"format": "first", "confidence": "high"},
    {"format": "last.first", "confidence": "high"},
    {"format": "lastfirst", "confidence": "high"},
    {"format": "firstl", "confidence": "high"},
    {"format": "lfirst", "confidence": "high"},
    {"format": "firstlast", "confidence": "high"},
    {"format": "last_middle_f", "confidence": "high"},
    {"format": "last", "confidence": "high"},
    {"format": "f.last", "confidence": "medium"},
    {"format": "last-f", "confidence": "medium"},
    {"format": "l.first", "confidence": "medium"},
    {"format": "last_f", "confidence": "medium"},
    {"format": "first.middle.last", "confidence": "medium"},
    {"format": "first-last", "confidence": "medium"},
    {"format": "last.f", "confidence": "medium"},
    {"format": "last_first", "confidence": "medium"},
    {"format": "f-last", "confidence": "medium"},
    {"format": "first.l", "confidence": "medium"},
    {"format": "first-l", "confidence": "medium"},
    {"format": "first_l", "confidence": "medium"},
    {"format": "first_last", "confidence": "medium"},
    {"format": "f_last", "confidence": "medium"},
    {"format": "last-first", "confidence": "medium"},
    {"format": "flast", "confidence": "medium"},
    {"format": "lastf", "confidence": "medium"},
    {"format": "l_first", "confidence": "medium"},
    {"format": "l-first", "confidence": "medium"},
    {"format": "first-middle-last", "confidence": "low"},
    {"format": "firstmlast", "confidence": "low"},
    {"format": "last.middle.first", "confidence": "low"},
    {"format": "last_middle_first", "confidence": "low"},
    {"format": "first_middle_last", "confidence": "low"},
    {"format": "last-middle-first", "confidence": "low"},
    {"format": "first-m-last", "confidence": "low"},
    {"format": "firstmiddlelast", "confidence": "low"},
    {"format": "last.m.first", "confidence": "low"},
    {"format": "lastmfirst", "confidence": "low"},
    {"format": "lastmiddlefirst", "confidence": "low"},
    {"format": "last_m_first", "confidence": "low"},
    {"format": "first.m.last", "confidence": "low"},
    {"format": "first_m_last", "confidence": "low"},
    {"format": "last-m-first", "confidence": "low"}
  ]
}

# Find domain format by company name
Zerobounce.find_domain(company_name: "Zero Bounce")
=>
{
  "domain": "zerobounce.net",
  "company_name": "Zero Bounce",
  "format": "first.last",
  "confidence": "high",
  "did_you_mean": "",
  "failure_reason": "",
  "other_domain_formats": [...]
}

Development

Local setup

sudo apt install -y rbenv
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
rbenv install 3.2.1
rbenv global 3.2.1
rbenv rehash
ruby -v
gem install bundler -v "~>2.4.6"
bundle install

Run tests

bundle exec rspec

You should see an output like this

running mock tests
.....................................................

Finished in 6.81 seconds (files took 0.40587 seconds to load)
53 examples, 0 failures

Test parameters

The tests use the following environment parameters: ZEROBOUNCE_API_KEY <zerobounce-api-key-value> this key is used in mock tests as a valid key sample (any value will work for mock tests) INCORRECT_API_KEY non whitespace string value that is not a valid key used for tests where the requests are meant to fail due to the API key value.

To set them

export ZEROBOUNCE_API_KEY=99e7ef20ceea4480a173b07b1be75371
export INCORRECT_API_KEY=thiskeyisinvalidorotherwiseincorrect

A .env.sample file is provided.

Tests use webmock and vcr for mocking HTTP requests. This means that actual requests were made and recorded in the spec/cassettes with an (at the time) valid API key used for testing purposes. This key has been invalidated in the meantime, however it is provided in the .env.sample file for the mock tests to work. If you do not wish to use this key for mocks, you can replace it with any value in the .yml files under spec/cassettes or delete all of them and rerun the tests so that vcr records them with a new key.

Publish

gem signin
gem build zerobounce.spec
gem push zerobounce-sdk-<version>.gem
gem search zerobounce-sdk --remote