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

Overview

todo:

Defined Under Namespace

Classes: ApiError, ApiUrls, BaseRequest, Configuration, Error, InternalServerError, MissingParameter, MockRequest, Request, UnknownError

Constant Summary collapse

VERSION =

The version of the gem.

'1.2.0'
@@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:



24
25
26
 
# File 'lib/zerobounce.rb', line 24

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) 


163
164
165
166
 
# File 'lib/zerobounce.rb', line 163

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_mx_forward": 0,
"sub_status_alternate": 0,
"sub_status_blocked": 0,
"sub_status_allowed": 0,
"start_date": "1/1/2018",
"end_date": "12/12/2023"

Parameters:

  • start_date (Date)
  • end_date (Date)

Returns:

  • (Hash) 


143
144
145
146
147
148
149
150
151
152
 
# File 'lib/zerobounce.rb', line 143

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:



37
38
39
 
# File 'lib/zerobounce.rb', line 37

def configure
  yield configuration
end

.credits ⇒ Integer

Get the number of remaining credits on the account.

Returns:

  • (Integer) —

    amount of credits left



76
77
78
79
80
81
 
# File 'lib/zerobounce.rb', line 76

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) 


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

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": "[email protected]",
"email_confidence": "medium",
"domain": "zerobounce.net",
"company_name": "ZeroBounce",
"did_you_mean": "",
"failure_reason": ""

Parameters:

  • [String] (Hash) —

    a customizable set of options

Returns:

  • (Hash) 


453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
 
# File 'lib/zerobounce.rb', line 453

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

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


427
428
429
430
431
432
433
 
# File 'lib/zerobounce.rb', line 427

def guessformat(domain, first_name: '', middle_name: '', last_name: '')
  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) 


359
360
361
362
 
# File 'lib/zerobounce.rb', line 359

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) 


375
376
377
378
 
# File 'lib/zerobounce.rb', line 375

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

.scoring_file_get(file_id) ⇒ String/File?

Get validate results file

Parameters:

  • :file_id (String) —

    Id of the file.

Returns:

  • (String/File?) 


339
340
341
342
343
 
# File 'lib/zerobounce.rb', line 339

def scoring_file_get(file_id)
  # todo:
  params = {file_id: file_id}
  @@request.bulk_get('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) 


320
321
322
323
324
325
326
327
328
329
330
331
332
 
# File 'lib/zerobounce.rb', line 320

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

.validate(email, ip_address = nil) ⇒ Hash

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

"address": "[email protected]",
"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) 


68
69
70
71
 
# File 'lib/zerobounce.rb', line 68

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": "[email protected]",
  "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) 


201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/zerobounce.rb', line 201

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) 


272
273
274
275
276
 
# File 'lib/zerobounce.rb', line 272

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) 


300
301
302
303
304
 
# File 'lib/zerobounce.rb', line 300

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

.validate_file_get(file_id) ⇒ String/File?

Get validate results file

Parameters:

  • :file_id (String) —

    Id of the file.

Returns:

  • (String/File?) 


283
284
285
286
287
 
# File 'lib/zerobounce.rb', line 283

def validate_file_get(file_id)
  # todo:
  params = {file_id: file_id}
  @@request.bulk_get('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) ⇒ 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) 


237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/zerobounce.rb', line 237

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
  )
  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
  @@request.bulk_post('sendfile', params, 'multipart/form-data', filepath)
end