emailhunter 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa2d9e9cc40ed470a2704f6cb875ade4b23bfb3f256ea535fc9ec772aa6d36f7
-  data.tar.gz: b16e0822b7b5362ac3ce01435467db482dd867d97abd9a394b40394c7f67989a
+  metadata.gz: 2006e973eb996d6b4285c772c1af115e0d96091c403fff927381233f4ebeed94
+  data.tar.gz: 51433f5603cbb512baedb0342eb83f7655505ae4a4ee5f4deac18d317d8861ae
 SHA512:
-  metadata.gz: 119c49c0e20229684a533a5bd000c33b5ba7470d2bc0ddcb075bfab48b705b1f0fe84e59227e2ed621c4ec27b335328189d7920b9db80037a5ad674864f94c22
-  data.tar.gz: 1de4508d1b3289004fe3a5603e48c2f03ce1b5cd4334c6a2b2efcf846e52a4f9966a2224639a342d790f0bd05b1adbcb5e322358567cae8d979930e526d7f6f4
+  metadata.gz: 71a8eebcf7e1c0452a08d0d8ef4c79d980b1d48dbe0d898dab096b8012267dc2d7e7d4ade75ea861635dfa78690522b409993a60f065d3901299f85de161715f
+  data.tar.gz: 27c55a270224f1a9bc513c54903d0e5c16598bc939270dd331422dea13487c2fb733f5cb90f47efd83dd4628180730cf3baf9b1f90ff6ecff9bc1d2871c5103f

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in emailhunter.gemspec

data/README.md

@@ -1,8 +1,6 @@
-# Emailhunter
+# EmailHunter
 
-A tiny ruby wrapper around Hunter (former Email Hunter) API. Direct access to all the web's email addresses.
-
-UPDATE (2016-12-02): gem updated with V2 API.
+A lightweight Ruby wrapper around [Hunter.io](https://hunter.io/) (formerly Email Hunter) API, providing direct access to email search, verification, and company insights.
 
 ## Installation
 
@@ -12,30 +10,51 @@ Add this line to your application's Gemfile:
 gem 'emailhunter'
 ```
 
-And then execute:
+Then execute:
 
-    $ bundle
+```sh
+$ bundle install
+```
 
-Or install it yourself as:
+Or install it yourself with:
 
-    $ gem install emailhunter
+```sh
+$ gem install emailhunter
+```
 
 ## Usage
 
 ```ruby
 require 'emailhunter'
-email_hunter = EmailHunter.new('Your secret API key')
-
+email_hunter = EmailHunter.new('Your API Key')
 ```
-Your secret API key. You can generate it in your dashboard from https://hunter.io
 
-## Domain search API
-Returns all the email addresses found using one given domain name, with our sources.
+Your API key can be generated in your [Hunter dashboard](https://hunter.io).
+
+## Features
+
+**Core APIs:**
+
+1. **Domain Search API** - Retrieve all email addresses associated with a domain
+2. **Email Verification API** - Check the deliverability of an email address
+3. **Email Finder API** - Find the most likely email using name and domain
+4. **Count API** - Get the number of email addresses for a domain (FREE)
+5. **Account Information API** - Retrieve details about your Hunter account
+6. **Company Information API** - Get company details using a domain name
+7. **People Search API** - Find key individuals associated with a company
+
+---
+
+### 1. Domain Search API
+
+Retrieve all email addresses associated with a given domain.
+
 ```ruby
 result = email_hunter.search('stripe.com')
 ```
 
-## Accessing domain search response
+#### Response Fields:
+
 ```ruby
 result.fetch(:meta)
 result.fetch(:webmail)
@@ -43,13 +62,17 @@ result.fetch(:emails)
 result.fetch(:pattern)
 result.fetch(:domain)
 ```
-## Email Verify API
-Allows you to verify the deliverability of an email address.
+
+### 2. Email Verification API
+
+Check the deliverability of an email address.
+
 ```ruby
-email_hunter.verify('bonjour@firmapi.com')
+result = email_hunter.verify('bonjour@firmapi.com')
 ```
 
-## Accessing email verify response
+#### Response Fields:
+
 ```ruby
 result.fetch(:result)
 result.fetch(:score)
@@ -62,90 +85,281 @@ result.fetch(:smtp_check)
 result.fetch(:accept_all)
 result.fetch(:sources)
 result.fetch(:meta)
+```
+
+### 3. Email Finder API
+
+Guess the most likely email of a person using their first name, last name, and domain.
+
+```ruby
+result = email_hunter.finder('gmail.com', 'Davide', 'Santangelo')
+```
+
+#### Response Fields:
+
+```ruby
+result.fetch(:email)
+result.fetch(:score)
+result.fetch(:sources)
+result.fetch(:domain)
+result.fetch(:meta)
+```
+
+### 4. Count API
 
+Retrieve the number of email addresses associated with a domain (FREE API call).
+
+```ruby
+result = email_hunter.count('gmail.com')
 ```
 
-## Email Exist API (only for V1)
-This API call is deprecated, please use the email verification call instead.
+#### Response Fields:
+
+```ruby
+result.fetch(:data)
+result.fetch(:meta)
+```
 
+### 5. Company Information API (New Feature)
 
-This API endpoint allows you to check if a given email address has been found on the web. If it has been found, it returns all the sources with the dates of the last crawls.
+Retrieve company details using a domain name.
 
 ```ruby
-email_hunter.exist('bonjour@firmapi.com')
+result = email_hunter.company('stripe.com')
 ```
 
-## Accessing email verify response
+#### Response Fields:
+
 ```ruby
-result.status
-result.email
-result.exist
-result.sources
+result.fetch(:name)
+result.fetch(:industry)
+result.fetch(:employees)
+result.fetch(:country)
+result.fetch(:meta)
 ```
 
-## Finder API (legacy generate)
-Guesses the most likely email of a person from his first name, his last name and a domain name.
+### 6. People Search API (New Feature)
+
+Retrieve key individuals associated with a company based on a domain name.
+
 ```ruby
-email_hunter.finder('gmail.com', 'Davide', 'Santangelo')
+result = email_hunter.people('stripe.com')
 ```
-## Accessing finder response
+
+#### Response Fields:
+
 ```ruby
+result.fetch(:employees)
+result.fetch(:position)
 result.fetch(:email)
-result.fetch(:score)
-result.fetch(:sources)
-result.fetch(:domain)
 result.fetch(:meta)
 ```
 
-## Count API
-Returns the number of email addresses found for a domain. This is a FREE API call.
+### 7. Discover API (New in v2.0.0)
+
+Search for companies using natural language queries.
+
 ```ruby
-email_hunter.count('gmail.com')
+result = email_hunter.discover('US-based Software companies', limit: 10)
 ```
 
-## Accessing count response
+#### Response Fields:
+
 ```ruby
-result.fetch(:data)
-result.fetch(:meta)
+result.data  # Array of companies
+result.meta.fetch(:results)
+result.meta.fetch(:limit)
+result.meta.fetch(:offset)
+```
+
+### 8. Leads Management API (New in v2.0.0)
+
+Manage your leads stored in Hunter.
+
+#### List Leads:
+
+```ruby
+result = email_hunter.leads(limit: 20, offset: 0)
 ```
 
-## Account Information
-This method enables you to get information regarding your Hunter account at any time. This call is free.
+#### Create Lead:
+
 ```ruby
-email_hunter.account
+lead_data = {
+  email: 'john@example.com',
+  first_name: 'John',
+  last_name: 'Doe',
+  company: 'Example Inc',
+  position: 'CEO'
+}
+result = email_hunter.lead_create(lead_data)
 ```
 
-## Accessing account response
+#### Update Lead:
+
 ```ruby
-result.fetch(:data)
+update_data = { position: 'CTO' }
+result = email_hunter.lead_update(lead_id, update_data)
+```
+
+#### Delete Lead:
+
+```ruby
+success = email_hunter.lead_delete(lead_id)
+```
+
+#### Response Fields:
+
+```ruby
+result.data.leads  # Array of lead objects
+result.data.leads.first.email
+result.data.leads.first.company
+result.meta.fetch(:count)
+```
+
+### 9. Campaigns Management API (New in v2.0.0)
+
+Manage your email campaigns and recipients.
+
+#### List Campaigns:
+
+```ruby
+result = email_hunter.campaigns(limit: 20)
+```
+
+#### Get Campaign Recipients:
+
+```ruby
+result = email_hunter.campaign_recipients(campaign_id, limit: 20)
+```
+
+#### Add Recipient to Campaign:
+
+```ruby
+recipient_data = {
+  email: 'john@example.com',
+  first_name: 'John',
+  last_name: 'Doe'
+}
+result = email_hunter.campaign_add_recipient(campaign_id, recipient_data)
+```
+
+#### Remove Recipient from Campaign:
+
+```ruby
+success = email_hunter.campaign_delete_recipient(campaign_id, 'john@example.com')
+```
+
+#### Response Fields:
+
+```ruby
+result.data.campaigns  # Array of campaign objects
+result.data.recipients  # Array of recipient objects
+result.meta.fetch(:limit)
+```
+
+### 10. Lead Enrichment API (New in v2.0.0)
+
+Enrich person data with 100+ attributes using email or LinkedIn.
+
+```ruby
+# Using email
+result = email_hunter.lead_enrichment(email: 'matt@hunter.io')
+
+# Using LinkedIn
+result = email_hunter.lead_enrichment(linkedin: 'matttharp')
+```
+
+#### Response Fields:
+
+```ruby
+result.data.name.fullName
+result.data.email
+result.data.location
+result.data.timeZone
+result.data.employment.domain
+result.data.employment.title
+result.data.employment.name
+result.data.twitter.handle
+result.data.linkedin.handle
+result.meta.fetch(:email)
+```
+
+### 11. Company Enrichment API (New in v2.0.0)
+
+Enrich company data with detailed firmographic information.
+
+```ruby
+result = email_hunter.company_enrichment('stripe.com')
+```
+
+#### Response Fields:
+
+```ruby
+result.data.name
+result.data.description
+result.data.foundedYear
+result.data.location
+result.data.category.industry
+result.data.metrics.employees
+result.data.tech  # Array of technologies used
+result.data.site.emailAddresses
+result.meta.fetch(:domain)
+```
+
+### 12. Combined Enrichment API (New in v2.0.0)
+
+Get both lead and company data in a single call.
+
+```ruby
+result = email_hunter.combined_enrichment(email: 'patrick@stripe.com')
+```
+
+#### Response Fields:
+
+```ruby
+result.lead.data  # Lead enrichment data
+result.company.data  # Company enrichment data
+result.meta.email
+result.meta.domain
+```
+
+### 13. Account Information API
+
+Retrieve details about your Hunter account.
+
+```ruby
+result = email_hunter.account
 ```
 
+#### Response Example:
+
 ```json
-{  
-   "data":{  
-      "first_name":"Davide",
-      "last_name":"Santangelo",
-      "email":"davide.santangelo@gmail.com",
-      "plan_name":"Free",
-      "plan_level":0,
-      "reset_date":"2019-06-29",
-      "team_id":349,
-      "calls":{  
-         "used":4,
-         "available":50
-      }
-   }
+{
+  "data": {
+    "first_name": "Davide",
+    "last_name": "Santangelo",
+    "email": "davide.santangelo@gmail.com",
+    "plan_name": "Free",
+    "plan_level": 0,
+    "reset_date": "2025-06-29",
+    "team_id": 349,
+    "calls": {
+      "used": 4,
+      "available": 50
+    }
+  }
 }
 ```
 
 ## License
-The emailhunter GEM is released under the MIT License.
 
+The EmailHunter gem is released under the [MIT License](https://opensource.org/licenses/MIT).
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/emailhunter/fork )
+1. Fork it ( https://github.com/[your-github-username]/emailhunter/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
+3. Commit your changes (`git commit -am 'Add new feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request

data/Rakefile

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'bundler/setup'
 require 'emailhunter'

data/emailhunter.gemspec

@@ -1,6 +1,7 @@
-lib = File.expand_path('lib', __dir__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require File.expand_path('lib/email_hunter/version', __dir__)
+# frozen_string_literal: true
+
+# Use require_relative to load the version file
+require_relative 'lib/email_hunter/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'emailhunter'
@@ -8,23 +9,36 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Davide Santangelo']
   spec.email         = ['davide.santangelo@gmail.com']
 
-  spec.summary       = 'A tiny ruby wrapper around Hunter.io API '
-  spec.description   = 'A tiny ruby wrapper around Hunter.io API. Hunter.io helps sales people reach their targets and increase their sales. '
+  spec.summary       = 'A tiny Ruby wrapper around the Hunter.io API'
+  spec.description   = <<~DESC
+    EmailHunter is a minimalistic Ruby wrapper for the Hunter.io API.
+    It provides a straightforward interface to integrate Hunter.io's
+    email discovery capabilities into your sales and marketing workflows.
+  DESC
   spec.license       = 'MIT'
 
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  # Adding additional metadata improves discoverability
+  spec.homepage      = 'https://github.com/davidesantangelo/emailhunter'
+  spec.metadata      = {
+    'source_code_uri' => 'https://github.com/davidesantangelo/emailhunter'
+  }
+
+  # Automatically include all version-controlled files except tests and specs
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f =~ %r{^(test|spec|features)/} }
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
+  # Development dependencies
   spec.add_development_dependency 'bundler', '~> 2.1'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec'
   spec.add_development_dependency 'typhoeus'
   spec.add_development_dependency 'vcr'
 
-  spec.required_ruby_version = '>= 1.9.3'
+  spec.required_ruby_version = '>= 3.0.0'
 
+  # Runtime dependencies
   spec.add_dependency 'faraday'
   spec.add_dependency 'json'
 end

data/lib/email_hunter/account.rb

@@ -3,10 +3,10 @@
 require 'faraday'
 require 'json'
 
-API_ACCOUNT_URL = 'https://api.hunter.io/v2/account?'
-
 module EmailHunter
   class Account
+    API_URL = 'https://api.hunter.io/v2/account'
+
     attr_reader :result, :first_name, :last_name, :email, :plan_name, :plan_level, :reset_date, :team_id, :calls,
                 :requests
 
@@ -15,15 +15,24 @@ module EmailHunter
     end
 
     def hunt
-      response = apiresponse
-      Struct.new(*response.keys).new(*response.values) unless response.empty?
+      response = fetch_account_data
+      parse_response(response)
     end
 
     private
 
-    def apiresponse
-      response = Faraday.new("#{API_ACCOUNT_URL}&api_key=#{@key}").get
-      response.success? ? JSON.parse(response.body, { symbolize_names: true }) : []
+    def fetch_account_data
+      connection = Faraday.new
+      connection.get(API_URL, api_key: @key)
+    end
+
+    def parse_response(response)
+      return nil unless response.success?
+
+      data = JSON.parse(response.body, symbolize_names: true)
+      return nil if data.empty?
+
+      Struct.new(*data.keys).new(*data.values)
     end
   end
 end

data/lib/email_hunter/api.rb

@@ -2,14 +2,13 @@
 
 require 'uri'
 
-require File.expand_path(File.join(File.dirname(__FILE__), 'exist'))
-require File.expand_path(File.join(File.dirname(__FILE__), 'search'))
-require File.expand_path(File.join(File.dirname(__FILE__), 'finder'))
-require File.expand_path(File.join(File.dirname(__FILE__), 'verify'))
-require File.expand_path(File.join(File.dirname(__FILE__), 'count'))
-require File.expand_path(File.join(File.dirname(__FILE__), 'account'))
+%w[exist search finder verify count account company people discover leads campaigns lead_enrichment company_enrichment
+   combined_enrichment].each do |file|
+  require_relative file
+end
 
 module EmailHunter
+  # Main API client for EmailHunter services
   class Api
     attr_reader :key
 
@@ -19,17 +18,17 @@ module EmailHunter
 
     # Domain search API
     def search(domain, params = {})
-      EmailHunter::Search.new(domain, key, params).hunt
+      execute_hunt(Search, domain, params)
     end
 
     # Email exist API
     def exist(email)
-      EmailHunter::Exist.new(email, key).hunt
+      execute_hunt(Exist, email)
     end
 
     # Email verify API
     def verify(email)
-      EmailHunter::Verify.new(email, key).hunt
+      execute_hunt(Verify, email)
     end
 
     # Email Finder API
@@ -39,12 +38,105 @@ module EmailHunter
 
     # Email Count API
     def count(domain)
-      EmailHunter::Count.new(domain).hunt
+      execute_hunt(Count, domain)
     end
 
     # Account Information API
     def account
-      EmailHunter::Account.new(key).hunt
+      execute_hunt(Account)
+    end
+
+    # Company Information API
+    def company(domain)
+      execute_hunt(Company, domain)
+    end
+
+    # People Information API
+    def people(domain)
+      execute_hunt(People, domain)
+    end
+
+    # Discover API - Search companies using natural language
+    def discover(query, params = {})
+      execute_hunt(Discover, query, params)
+    end
+
+    # Leads API - List leads
+    def leads(params = {})
+      Leads.new(key, action: :list, params: params).hunt
+    end
+
+    # Leads API - Create lead
+    def lead_create(data)
+      Leads.new(key, action: :create, data: data).hunt
+    end
+
+    # Leads API - Update lead
+    def lead_update(id, data)
+      Leads.new(key, action: :update, lead_id: id, data: data).hunt
+    end
+
+    # Leads API - Delete lead
+    def lead_delete(id)
+      Leads.new(key, action: :delete, lead_id: id).hunt
+    end
+
+    # Campaigns API - List campaigns
+    def campaigns(params = {})
+      Campaigns.new(key, action: :list, params: params).hunt
+    end
+
+    # Campaigns API - Get campaign recipients
+    def campaign_recipients(campaign_id, params = {})
+      Campaigns.new(key, action: :recipients, campaign_id: campaign_id, params: params).hunt
+    end
+
+    # Campaigns API - Add recipient to campaign
+    def campaign_add_recipient(campaign_id, data)
+      Campaigns.new(key, action: :add_recipient, campaign_id: campaign_id, data: data).hunt
+    end
+
+    # Campaigns API - Delete recipient from campaign
+    def campaign_delete_recipient(campaign_id, email)
+      Campaigns.new(key, action: :delete_recipient, campaign_id: campaign_id, data: { email: email }).hunt
+    end
+
+    # Lead Enrichment API - Enrich person data
+    def lead_enrichment(email: nil, linkedin: nil)
+      LeadEnrichment.new(key, email: email, linkedin: linkedin).hunt
+    end
+
+    # Company Enrichment API - Enrich company data
+    def company_enrichment(domain)
+      CompanyEnrichment.new(domain, key).hunt
+    end
+
+    # Combined Enrichment API - Enrich both lead and company data
+    def combined_enrichment(email: nil, linkedin: nil)
+      CombinedEnrichment.new(key, email: email, linkedin: linkedin).hunt
+    end
+
+    private
+
+    # Helper method to reduce repetition
+    def execute_hunt(klass, *args)
+      case klass.name.split('::').last
+      when 'Search', 'Discover'
+        # Search and Discover expect (value, key, params)
+        value, params = args
+        klass.new(value, key, params || {}).hunt
+      when 'Count'
+        # Count doesn't need key
+        domain = args.first
+        klass.new(domain).hunt
+      when 'Account'
+        # Account only needs key
+        klass.new(key).hunt
+      else
+        # Other classes expect (value, key)
+        value = args.first
+        klass.new(value, key).hunt
+      end
     end
   end
 end