Module: Zerobounce

Defined in:
lib/zerobounce.rb,
lib/zerobounce/error.rb,
lib/zerobounce/request.rb,
lib/zerobounce/version.rb,
lib/zerobounce/api_urls.rb,
lib/zerobounce/base_request.rb,
lib/zerobounce/mock_request.rb,
lib/zerobounce/configuration.rb,
lib/zerobounce/download_type.rb,
lib/zerobounce/get_file_helper.rb,
lib/zerobounce/validate_status.rb,
lib/zerobounce/get_file_options.rb,
lib/zerobounce/validate_sub_status.rb

Overview

todo:

Defined Under Namespace

Modules: DownloadType, GetFileHelper, ValidateStatus, ValidateSubStatus Classes: ApiError, ApiUrls, BaseRequest, Configuration, Error, GetFileOptions, InternalServerError, MissingParameter, MockRequest, Request, UnknownError

Constant Summary collapse

VERSION =

The version of the gem.

'2.1.4'
@@request = 
ENV['TEST']=='unit' ? MockRequest : Request

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.configuration ⇒ Zerobounce::Configuration Also known as: config

Zerobounce configuration

Returns:



30
31
32
 
# File 'lib/zerobounce.rb', line 30

def configuration
  @configuration ||= Configuration.new
end

Class Method Details

.activity(email) ⇒ Hash

Get Activty for email

"found": true,
"active_in_days": "180"

Parameters:

  • :email (String) —

    Email to get activity for

Returns:

  • (Hash) 


180
181
182
183
 
# File 'lib/zerobounce.rb', line 180

def activity(email)
  params = {email: email}
  @@request.get('activity', params)
end

.api_usage(start_date, end_date) ⇒ Hash

Get API usage

"total": 5,
"status_valid": 4,
"status_invalid": 1,
"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": 1,
"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_accept_all": 0,
"sub_status_mx_forward": 0,
"sub_status_alternate": 0,
"sub_status_allowed": 0,
"sub_status_blocked": 0,
"sub_status_gold": 0,
"sub_status_role_based_accept_all": 0,
"start_date": "1/1/2018",
"end_date": "12/12/2023"

Parameters:

  • start_date (Date)
  • end_date (Date)

Returns:

  • (Hash) 


160
161
162
163
164
165
166
167
168
169
 
# File 'lib/zerobounce.rb', line 160

def api_usage(start_date, end_date)
  begin
    start_date_f = start_date.strftime('%Y-%m-%d')
    end_date_f = end_date.strftime('%Y-%m-%d')
  rescue NoMethodError => e
    raise ArgumentError.new('strftime method not found for provided arguments')
  end
  params = {start_date: start_date_f, end_date: end_date_f}
  @@request.get('getapiusage', params)
end

.configure {|config| ... } ⇒ Object

Configure Zerobounce inside a block.

Examples:

Zerobounce.configure do |config|
  config.apikey = 'api-key'
end

Yield Parameters:



51
52
53
 
# File 'lib/zerobounce.rb', line 51

def configure
  yield configuration
end

.credits ⇒ Integer

Get the number of remaining credits on the account.

Returns:

  • (Integer) —

    amount of credits left



90
91
92
93
94
95
 
# File 'lib/zerobounce.rb', line 90

def credits()
  json = @@request.get('getcredits', {})
  credits = json['Credits']
  credits_i = credits.to_i
  return credits_i
end

.find_domain(domain: '', company_name: '') ⇒ Hash

Find domain format

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

}

Parameters:

  • [String] (Hash) —

    a customizable set of options

Returns:

  • (Hash) 


602
603
604
605
606
607
608
609
610
611
612
613
614
615
 
# File 'lib/zerobounce.rb', line 602

def find_domain(domain: '', company_name: '')
  # Validate that exactly one of domain or company_name is provided
  if (domain.nil? || domain.empty?) && (company_name.nil? || company_name.empty?)
    raise ArgumentError, "Either domain or company_name must be provided"
  elsif !(domain.nil? || domain.empty?) && !(company_name.nil? || company_name.empty?)
    raise ArgumentError, "Only one of domain or company_name can be provided"
  end

  params = {}
  params[:domain] = domain unless domain.nil? || domain.empty?
  params[:company_name] = company_name unless company_name.nil? || company_name.empty?

  @@request.get('guessformat', params)
end

.find_email(first_name, domain: '', company_name: '', middle_name: '', last_name: '') ⇒ Hash

Find email address format

"email": "john@zerobounce.net",
"email_confidence": "medium",
"domain": "zerobounce.net",
"company_name": "ZeroBounce",
"did_you_mean": "",
"failure_reason": ""

Parameters:

  • [String] (Hash) —

    a customizable set of options

Returns:

  • (Hash) 


527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
 
# File 'lib/zerobounce.rb', line 527

def find_email(first_name, domain: '', company_name: '', middle_name: '', last_name: '')
  # Validate that exactly one of domain or company_name is provided
  if (domain.nil? || domain.empty?) && (company_name.nil? || company_name.empty?)
    raise ArgumentError, "Either domain or company_name must be provided"
  elsif !(domain.nil? || domain.empty?) && !(company_name.nil? || company_name.empty?)
    raise ArgumentError, "Only one of domain or company_name can be provided"
  end

  params = { first_name: first_name }
  params[:domain] = domain unless domain.nil? || domain.empty?
  params[:company_name] = company_name unless company_name.nil? || company_name.empty?
  params[:middle_name] = middle_name unless middle_name.nil? || middle_name.empty?
  params[:last_name] = last_name unless last_name.nil? || last_name.empty?

  @@request.get('guessformat', params)
end

.get_file_json_indicates_error?(body) ⇒ Boolean

Whether a getfile response body looks like a JSON error payload (including HTTP 200).

Parameters:

  • body (String)

Returns:

  • (Boolean) 


39
40
41
 
# File 'lib/zerobounce.rb', line 39

def get_file_json_indicates_error?(body)
  GetFileHelper.json_indicates_error?(body)
end

.guessformat(domain, first_name: '', middle_name: '', last_name: '') ⇒ Hash

Guess email formatDomain to guess format for

{ “email”=>“”,

"domain"=>"zerobounce.net",
"format"=>"first.last",
 "status"=>"",
 "sub_status"=>"",
 "confidence"=>"high",
 "did_you_mean"=>"",
 "failure_reason"=>"",
 "other_domain_formats"=> [

“confidence”=>“high”, “confidence”=>“high”, “confidence”=>“high”, “confidence”=>“high”, “confidence”=>“high”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“medium”, “confidence”=>“low”, “confidence”=>“low”

]

}

Parameters:

  • domain (String) —

    Domain to guess format for

  • [String] (Hash) —

    a customizable set of options

Returns:

  • (Hash) 


499
500
501
502
503
504
505
506
507
 
# File 'lib/zerobounce.rb', line 499

def guessformat(domain, first_name: '', middle_name: '', last_name: '')
  warn "[DEPRECATION] `guessformat` is deprecated and will be removed in a future version.\n" \
       "Please use `find_email` or `find_domain` instead."
  params = {domain: domain}
  params[:first_name] = first_name unless first_name.nil? || first_name.empty?
  params[:middle_name] = middle_name unless middle_name.nil? || middle_name.empty?
  params[:last_name] = last_name unless last_name.nil? || last_name.empty?  
  @@request.get('guessformat', params)
end

.scoring_file_check(file_id) ⇒ Hash

Get validate file status

"success": true,
"file_id": "d391b463-cb56-4fb3-a9c0-9817653ff725",
"file_name": "zerobounce-ai-scoring.csv",
"upload_date": "2023-04-18T15:13:56Z",
"file_status": "Complete",
"complete_percentage": "100% Complete.",
"return_url": null

Parameters:

  • :file_id (String) —

    Id of the file.

Returns:

  • (Hash) 


431
432
433
434
 
# File 'lib/zerobounce.rb', line 431

def scoring_file_check(file_id)
  params = {file_id: file_id}
  @@request.bulk_get('scoring/filestatus', params)
end

.scoring_file_delete(file_id) ⇒ Hash

Delete validate file

"success": true,
"message": "File Deleted",
"file_name": "zerobounce-ai-scoring.csv",
"file_id": "6d44a908-7283-42a9-aa5f-9e57b16f84bd"

Parameters:

  • file_id —

    Id of the file.

Returns:

  • (Hash) 


447
448
449
450
 
# File 'lib/zerobounce.rb', line 447

def scoring_file_delete(file_id)
  params = {file_id: file_id}
  @@request.bulk_get('scoring/deletefile', params)
end

.scoring_file_get(file_id, options = nil) ⇒ String

Get scoring bulk results file

Parameters:

  • file_id (String) —

    Id of the file.

  • options (Zerobounce::GetFileOptions, nil) (defaults to: nil) —

    Optional download_type; activity_data is not sent.

Returns:

  • (String) —

    file body on success

Raises:

  • (RuntimeError) —

    on API/JSON error responses



409
410
411
412
413
414
415
 
# File 'lib/zerobounce.rb', line 409

def scoring_file_get(file_id, options = nil)
  params = { file_id: file_id }
  if options && options.download_type
    params[:download_type] = options.download_type
  end
  @@request.bulk_getfile('scoring/getfile', params)
end

.scoring_file_send(filepath, email_address_column: 1, has_header_row: true, return_url: nil) ⇒ Hash

Score CSV file

"success": true,
"message": "File Accepted",
"file_name": "zerobounce-ai-scoring.csv",
"file_id": "6d44a908-7283-42a9-aa5f-9e57b16f84bd"

Parameters:

  • :filepath (String) —

    Path to the file to be uploaded

  • [Int] (Hash) —

    a customizable set of options

Returns:

  • (Hash) 


370
371
372
373
374
375
376
377
378
379
380
381
382
 
# File 'lib/zerobounce.rb', line 370

def scoring_file_send(
    filepath,
    email_address_column: 1,
    has_header_row: true,
    return_url: nil
  )
  params = {
    email_address_column: email_address_column,
    has_header_row: has_header_row,
  }
  params[:return_url] = return_url if return_url
  @@request.bulk_post('scoring/sendfile', params, 'multipart/form-data', filepath)
end

.scoring_file_send_stream(io, file_name, **opts) ⇒ Hash

Score CSV from a stream (IO or String).

Parameters:

  • io (IO, String) —

    Stream or string content to upload

  • file_name (String) —

    Filename for the upload (e.g. “emails.csv”)

  • [Int] (Hash) —

    a customizable set of options

Returns:

  • (Hash) —

    same as scoring_file_send



392
393
394
395
396
397
398
399
400
 
# File 'lib/zerobounce.rb', line 392

def scoring_file_send_stream(io, file_name, **opts)
  content = io.respond_to?(:read) ? io.read : io.to_s
  Tempfile.create(['zb', File.extname(file_name)]) do |tmp|
    tmp.binmode
    tmp.write(content)
    tmp.rewind
    scoring_file_send(tmp.path, **opts)
  end
end

.validate(email, ip_address = nil) ⇒ Hash

Validates the email address and gets geoip information for an IP if provided.

"address": "valid@example.com",
"status": "valid",
"sub_status": "",
"free_email": false,
"did_you_mean": null,
"account": null,
"domain": null,
"domain_age_days": "9692",
"smtp_provider": "example",
"mx_found": "true",
"mx_record": "mx.example.com",
"firstname": "zero",
"lastname": "bounce",
"gender": "male",
"country": null,
"region": null,
"city": null,
"zipcode": null,
"processed_at": "2023-04-18 12:09:39.074"

Parameters:

  • :email (String) —

    The email address to validate.

  • [String] (Hash) —

    a customizable set of options

Returns:

  • (Hash) 


82
83
84
85
 
# File 'lib/zerobounce.rb', line 82

def validate(email, ip_address=nil)
  params = {email: email, ip_address: ip_address}
  @@request.get('validate', params)
end

.validate_batch(emails, ip_addresses = []) ⇒ Array

Validate email batch

[

{
  "address": "disposable@example.com",
  "status": "do_not_mail",
  "sub_status": "disposable",
  "free_email": false,
  "did_you_mean": null,
  "account": null,
  "domain": null,
  "domain_age_days": "9692",
  "smtp_provider": "example",
  "mx_found": "true",
  "mx_record": "mx.example.com",
  "firstname": "zero",
  "lastname": "bounce",
  "gender": "male",
  "country": null,
  "region": null,
  "city": null,
  "zipcode": null,
  "processed_at": "2023-04-18 12:27:39.529"
},
{
  ...
},
...

]

Parameters:

  • :emails (Array) —

    List of email addresses to validate.

  • [Array] (Hash) —

    a customizable set of options

Returns:

  • (Array) —

    list of validate result for each element

Raises:

  • (ArgumentError) 


218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/zerobounce.rb', line 218

def validate_batch(emails, ip_addresses=[])

  raise ArgumentError.new if emails.class != Array
  emails.each do |email|
    raise ArgumentError if email.class != String
  end

  email_batch = []
  emails.each_index do |i|
    email_batch.push({
      email_address: emails[i],
      ip_address: ip_addresses[i]
    })
  end
  params = {email_batch: email_batch}
  results = @@request.bulk_post('validatebatch', params)
  return results['email_batch']
end

.validate_file_check(file_id) ⇒ Hash

Get validate file status

"success": true,
"file_id": "6d44a908-7283-42a9-aa5f-9e57b16f84bd",
"file_name": "zerobounce-batch-validation.csv",
"upload_date": "2023-04-18T14:40:08Z",
"file_status": "Complete",
"complete_percentage": "100%",
"error_reason": null,
"return_url": null

Parameters:

  • :file_id (String) —

    Id of the file.

Returns:

  • (Hash) 


315
316
317
318
319
 
# File 'lib/zerobounce.rb', line 315

def validate_file_check(file_id)
  # todo:
  params = {file_id: file_id}
  @@request.bulk_get('filestatus', params)
end

.validate_file_delete(file_id) ⇒ Hash

Delete validate file

"success": true,
"message": "File Deleted",
"file_name": "zerobounce-batch-validation.csv",
"file_id": "6d44a908-7283-42a9-aa5f-9e57b16f84bd"

Parameters:

  • file_id —

    Id of the file.

Returns:

  • (Hash) 


350
351
352
353
354
 
# File 'lib/zerobounce.rb', line 350

def validate_file_delete(file_id)
  # todo:
  params = {file_id: file_id}
  @@request.bulk_get('deletefile', params)
end

.validate_file_get(file_id, options = nil) ⇒ String

Get validate results file

Parameters:

  • file_id (String) —

    Id of the file.

  • options (Zerobounce::GetFileOptions, nil) (defaults to: nil) —

    Optional download_type and activity_data (validation bulk only).

Returns:

  • (String) —

    file body on success

Raises:

  • (RuntimeError) —

    on API/JSON error responses



328
329
330
331
332
333
334
335
336
337
 
# File 'lib/zerobounce.rb', line 328

def validate_file_get(file_id, options = nil)
  params = { file_id: file_id }
  if options
    params[:download_type] = options.download_type if options.download_type
    unless options.activity_data.nil?
      params[:activity_data] = options.activity_data ? 'true' : 'false'
    end
  end
  @@request.bulk_getfile('getfile', params)
end

.validate_file_send(filepath, email_address_column: 1, first_name_column: 2, last_name_column: 3, gender_column: 4, has_header_row: true, return_url: nil, allow_phase_2: nil) ⇒ Hash

Validate CSV file

"success": true,
"message": "File Accepted",
"file_name": "zerobounce-batch-validation.csv",
"file_id": "6d44a908-7283-42a9-aa5f-9e57b16f84bd"

Parameters:

  • :filepath (String) —

    Path to the file to be uploaded

  • [Int] (Hash) —

    a customizable set of options

Returns:

  • (Hash) 


254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
 
# File 'lib/zerobounce.rb', line 254

def validate_file_send(
    filepath,
    email_address_column: 1,
    first_name_column: 2,
    last_name_column: 3,
    gender_column: 4,
    has_header_row: true,
    return_url: nil,
    allow_phase_2: nil
  )
  params = {
    email_address_column: email_address_column,
    has_header_row: has_header_row,
  }
  params[:first_name_column] = first_name_column if first_name_column
  params[:last_name_column] = last_name_column if last_name_column
  params[:gender_column] = gender_column if gender_column
  params[:return_url] = return_url if return_url
  unless allow_phase_2.nil?
    params[:allow_phase_2] = allow_phase_2 ? 'true' : 'false'
  end
  @@request.bulk_post('sendfile', params, 'multipart/form-data', filepath)
end

.validate_file_send_stream(io, file_name, **opts) ⇒ Hash

Validate CSV from a stream (IO or String).

Parameters:

  • io (IO, String) —

    Stream or string content to upload

  • file_name (String) —

    Filename for the upload (e.g. “emails.csv”)

  • [Int] (Hash) —

    a customizable set of options

  • [Boolean] (Hash) —

    a customizable set of options

Returns:

  • (Hash) —

    same as validate_file_send



290
291
292
293
294
295
296
297
298
 
# File 'lib/zerobounce.rb', line 290

def validate_file_send_stream(io, file_name, **opts)
  content = io.respond_to?(:read) ? io.read : io.to_s
  Tempfile.create(['zb', File.extname(file_name)]) do |tmp|
    tmp.binmode
    tmp.write(content)
    tmp.rewind
    validate_file_send(tmp.path, **opts)
  end
end