Module: Zerobounce

Defined in:
lib/zerobounce.rb,
lib/zerobounce/error.rb,
lib/zerobounce/request.rb,
lib/zerobounce/version.rb,
lib/zerobounce/base_request.rb,
lib/zerobounce/mock_request.rb,
lib/zerobounce/configuration.rb

Overview

todo:

Defined Under Namespace

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

Constant Summary collapse

API_ROOT_URL = 
'https://api.zerobounce.net/v2'
BULK_API_ROOT_URL = 
'https://bulkapi.zerobounce.net/v2'
VERSION =

The version of the gem.

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



26
27
28
 
# File 'lib/zerobounce.rb', line 26

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) 


165
166
167
168
 
# File 'lib/zerobounce.rb', line 165

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) 


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

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:



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

def configure
  yield configuration
end

.credits ⇒ Integer

Get the number of remaining credits on the account.

Returns:

  • (Integer) —

    amount of credits left



78
79
80
81
82
83
 
# File 'lib/zerobounce.rb', line 78

def credits()
  json = @@request.get('getcredits', {})
  credits = json['Credits']
  credits_i = credits.to_i
  return credits_i
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) 


429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
 
# File 'lib/zerobounce.rb', line 429

def guessformat(domain, first_name: '', middle_name: '', last_name: '')
  params = {
    domain: domain
  }
  unless first_name.empty?
    params['first_name'] = first_name
  end
  unless middle_name.empty?
    params['middle_name'] = middle_name
  end
  unless last_name.empty?
    params['last_name'] = last_name
  end

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


361
362
363
364
 
# File 'lib/zerobounce.rb', line 361

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) 


377
378
379
380
 
# File 'lib/zerobounce.rb', line 377

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


341
342
343
344
345
 
# File 'lib/zerobounce.rb', line 341

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) 


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

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) 


70
71
72
73
 
# File 'lib/zerobounce.rb', line 70

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) 


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

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) 


274
275
276
277
278
 
# File 'lib/zerobounce.rb', line 274

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) 


302
303
304
305
306
 
# File 'lib/zerobounce.rb', line 302

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


285
286
287
288
289
 
# File 'lib/zerobounce.rb', line 285

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) 


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

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