zerobounce-sdk 1.0.1 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce3b4157b9478ba02c42a325862699aa7679b4270504ac7cc5448f5b7d4538fe
-  data.tar.gz: f95a6733dc75b74bcf4fcfc341eb84baa4e539ea54eaf70ac38d64fe2aa63655
+  metadata.gz: 804ff0380f6e305c6b80ceaec623ed06f014927074ebef93598b9dab3d23c988
+  data.tar.gz: 64ff74c48f382f6cb50d29c1d9f6e95d149929289e3971f27c2e1cfcc7088706
 SHA512:
-  metadata.gz: 3e0382eb10b8a5aac8edfdd6fedf4c50ab6de72333f5f648f0d9cac64d41af67412cf8dfbd77ba10731f1185b05f2c84b252bb25a2bd98a1827fc55397b77c1a
-  data.tar.gz: b9213e632058dd88944cb0499d6dfbdbf343138547296644a3843ef7e860d59fc808c7b8429ec3c86df81a971cf1891006c61a7982aeae9ba236789a9dd36b0f
+  metadata.gz: 8c4b82770126e3f7f0ef3699688ad11bf526163df669d3a6d637ff87d183955b1876e99e2a9e953eebb5b4102863ab8ff5204417a77d7e47722fe3b14977abcf
+  data.tar.gz: a9ebe2bd4422d96e85ffd5331456cb0669090a1ade71f828249b32a44730e843b05ffa24148673b353130b4e896075acf035d59c9963bc83ad60dcb841c56f4f

data/.gitignore

@@ -57,3 +57,8 @@ build-iPhoneSimulator/
 
 # Used by RSpec
 .rspec_status
+
+
+# Log files
+output.err
+output.log

data/Gemfile.lock

@@ -1,7 +1,8 @@
 PATH
   remote: .
   specs:
-    zerobounce (0.4.0)
+    zerobounce-sdk (1.1.1)
+      dotenv (~> 2.8.1)
       rest-client (~> 2.1)
 
 GEM
@@ -17,15 +18,16 @@ GEM
     docile (1.4.0)
     domain_name (0.5.20190701)
       unf (>= 0.0.5, < 1.0.0)
+    dotenv (2.8.1)
     hashdiff (1.0.1)
     http-accept (1.7.0)
     http-cookie (1.0.5)
       domain_name (~> 0.5)
     json (2.6.3)
     method_source (1.0.0)
-    mime-types (3.4.1)
+    mime-types (3.5.1)
       mime-types-data (~> 3.2015)
-    mime-types-data (3.2023.0218.1)
+    mime-types-data (3.2023.0808)
     netrc (0.11.0)
     parallel (1.22.1)
     parser (3.2.2.0)
@@ -115,7 +117,7 @@ DEPENDENCIES
   vcr (~> 6.1.0)
   webmock (~> 3.18)
   yard (~> 0.9.26)
-  zerobounce!
+  zerobounce-sdk!
 
 BUNDLED WITH
    2.4.6

data/README.md

@@ -30,7 +30,7 @@ Zerobounce.configure do |config|
   ...
 end
 ```
-or 
+or
 ```
 Zerobounce.config.apikey = '<zerobounce-api-key>'
 ...
@@ -92,7 +92,7 @@ Zerobounce.api_usage(Date.today, Date.today)
 
 Validate single eMail
 ```ruby
-Zerobounce.validate('valid@example.com') 
+Zerobounce.validate('valid@example.com')
 # Zerobounce.validate('valid@example.com', '192.168.0.1') # optional IP address
 =>
 {"address"=>"valid@example.com",
@@ -126,11 +126,11 @@ emails
  "toxic@example.com",
  "donotmail@example.com",
  "spamtrap@example.com"]
- 
-# ip_addresses 
+
+# 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",
@@ -263,14 +263,14 @@ Send file
  "file_name"=>"validation.csv",
  "file_id"=>"75d854a6-565c-49f9-b4c8-b3344480ec4c"}
  # file_id will be required for next steps
- # optional named parameters: 
+ # 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) 
+ # Zerobounce.validate_file_send(validate_file_path, email_address_column: 1, gender_column: 4)
 ```
 
 Check file
@@ -361,6 +361,99 @@ Zerobounce.validate_file_delete(file_id)
 ```
 
 
+### 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
+```ruby
+Zerobounce.guessformat("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"}]}
+# Zerobounce.guessformat("zerobounce.net", first_name: "John", middle_name: 'Deere', last_name: "Doe")
+```
+
 ## Development
 
 After checking out the repo run tests

data/{README_es.md → documentation.md}

@@ -1,8 +1,4 @@
-
-# Zerobounce
-Ruby client for Zerobounce.net API. Developed based on [this version](https://github.com/afrase/zerobounce) by Aaron Frase.
-
-## Usage
+#### Usage
 Add this line to your application's Gemfile:
 ```ruby
 gem 'zerobounce-sdk'
@@ -30,7 +26,7 @@ Zerobounce.configure do |config|
   ...
 end
 ```
-or 
+or
 ```
 Zerobounce.config.apikey = '<zerobounce-api-key>'
 ...
@@ -39,7 +35,13 @@ Zerobounce.config.apikey = '<zerobounce-api-key>'
 Credits
 ```ruby
 Zerobounce.credits
-=> 79   # returns -1 for invalid key
+=> 79   ### returns -1 for invalid key
+```
+
+Activity
+```ruby
+Zerobounce.activity('ss@gmail.com')
+=> {"found"=>true, "active_in_days"=>"180"}
 ```
 
 Usage statistics
@@ -82,12 +84,12 @@ Zerobounce.api_usage(Date.today, Date.today)
  "end_date"=>"4/28/2023"}
 ```
 
-### Email Validation
+##### Email Validation
 
 Validate single eMail
 ```ruby
-Zerobounce.validate('valid@example.com') 
-# Zerobounce.validate('valid@example.com', '192.168.0.1') # optional IP address
+Zerobounce.validate('valid@example.com')
+### Zerobounce.validate('valid@example.com', '192.168.0.1') # optional IP address
 =>
 {"address"=>"valid@example.com",
  "status"=>"valid",
@@ -120,11 +122,11 @@ emails
  "toxic@example.com",
  "donotmail@example.com",
  "spamtrap@example.com"]
- 
-# ip_addresses 
+
+### 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, ip_addresses) # optional ip_addresses parameter
+
 Zerobounce.validate_batch(emails)
 =>
 [{"address"=>"disposable@example.com",
@@ -243,11 +245,11 @@ Zerobounce.validate_batch(emails)
   "processed_at"=>"2023-04-28 15:21:44.340"}]
 ```
 
-#### Batch File Validation
+###### Batch File Validation
 
 Send file
 ```ruby
-# sample file can be found in the files folder of this repository
+### 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)
@@ -256,15 +258,15 @@ Send file
  "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: 
+ ### 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) 
+    return_url: nil         ### results callback url
+ ### Zerobounce.validate_file_send(validate_file_path, email_address_column: 1, gender_column: 4)
 ```
 
 Check file
@@ -303,7 +305,7 @@ Zerobounce.validate_file_delete(file_id)
  "file_id"=>"75d854a6-565c-49f9-b4c8-b3344480ec4c"}
 ```
 
-### AI Scoring
+##### AI Scoring
 
 Send file
 ```ruby
@@ -315,12 +317,12 @@ Zerobounce.scoring_file_send(scoring_file_path)
  "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
+### 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)
+    return_url: nil         ### results callback url
+### Zerobounce.scoring_file_send(scoring_file_path, email_address_column: 1)
 ```
 
 File check
@@ -354,12 +356,56 @@ Zerobounce.validate_file_delete(file_id)
 => {"success"=>false, "message"=>"File cannot be found."}
 ```
 
+##### Email Finder
+
+Guess Format
+```ruby
+Zerobounce.guessformat("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"}]}
+# Zerobounce.guessformat("zerobounce.net", first_name: "John", middle_name: 'Deere', last_name: "Doe")
+```
+
 
-## Development
+#### Development
 
 After checking out the repo run tests
 ```bash
-rspec --init # if needed
+rspec --init ### if needed
 bundle exec rspec
 ```
 
@@ -373,7 +419,7 @@ Finished in 6.81 seconds (files took 0.40587 seconds to load)
 53 examples, 0 failures
 ```
 
-### Test parameters
+##### Test parameters
 The tests use the following environment parameters:
 TEST {unit|live} influences whether mocked unit tests are run or the live server is used (credits may be used if you choose to do this)
 ZEROBOUNCE_API_KEY {<zerobounce-api-key-value>} this key is used to make requests to the live server; it is also used in mock tests as a valid key sample (any value will work for mock tests)