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.8'
@@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) 


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

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) 


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

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



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

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": [ "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) 


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

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) 


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

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) 


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

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) 


433
434
435
436
 
# File 'lib/zerobounce.rb', line 433

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) 


449
450
451
452
 
# File 'lib/zerobounce.rb', line 449

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



411
412
413
414
415
416
417
 
# File 'lib/zerobounce.rb', line 411

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) 


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

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



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

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", "catchall_domain": false, "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) 


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

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", "catchall_domain": false, "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) 


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

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.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) 


317
318
319
320
321
 
# File 'lib/zerobounce.rb', line 317

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) 


352
353
354
355
356
 
# File 'lib/zerobounce.rb', line 352

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



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

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) 


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

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



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

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