Laravel Hunter

#Laravel Hunter

A Laravel client for the Hunter.io v2 API. A fluent Hunter facade covers email finding, email verification, domain search, and lead/campaign management, authenticates every request with the api_key query parameter, and throws a HunterException on a non-2xx response instead of returning a silent error array.

#Features

Domain Search — domainSearch(), emailCount()
Email Finder & Verifier — findEmail(), verifyEmail()
Account — accountInfo()
Leads — listLeads(), getLead(), createLead(), deleteLead()
Campaigns — listCampaigns(), getCampaign(), startCampaign(), pauseCampaign()
Leads Lists — listLeadsLists(), getLeadsList()
Thin by design — every method returns the raw decoded JSON response as an array, no DTOs
Fails loud — required parameters throw InvalidArgumentException; a non-2xx API response throws HunterException carrying the API's error message and HTTP status code

#Installation

You can install the package via composer:

composer require jeffersongoncalves/laravel-hunter

Optionally publish the config file:

php artisan vendor:publish --tag="hunter-config"

#Configuration

Add to your .env:

HUNTER_API_KEY=your-api-key

Find your API key at https://hunter.io/api-keys.

#Config Options

// config/hunter.php
return [
    'api_key' => env('HUNTER_API_KEY'),
    'base_url' => env('HUNTER_BASE_URL', 'https://api.hunter.io/v2'),
];

#Usage

use JeffersonGoncalves\Hunter\Facades\Hunter;
use JeffersonGoncalves\Hunter\Exceptions\HunterException;

#Domain Search

Hunter::domainSearch('example.com', limit: 10, type: 'personal');
Hunter::emailCount('example.com', type: 'personal');

#Email Finder & Verifier

Hunter::findEmail('example.com', 'Jane', 'Doe');
Hunter::verifyEmail('jane@example.com');

#Account

Hunter::accountInfo();

#Leads

Hunter::listLeads(limit: 10, offset: 0);
Hunter::getLead('lead-id');
Hunter::createLead('jane@example.com', firstName: 'Jane', lastName: 'Doe', company: 'Acme');
Hunter::deleteLead('lead-id');

#Campaigns

Hunter::listCampaigns(limit: 10, offset: 0);
Hunter::getCampaign('campaign-id');
Hunter::startCampaign('campaign-id');
Hunter::pauseCampaign('campaign-id');

#Leads Lists

Hunter::listLeadsLists(limit: 10, offset: 0);
Hunter::getLeadsList('list-id');

#Handling errors

try {
    $result = Hunter::findEmail('example.com', 'Jane', 'Doe');
} catch (HunterException $e) {
    // $e->getMessage() — the API's errors[0].details, or the raw response body
    // $e->statusCode  — the HTTP status code returned by Hunter.io
} catch (InvalidArgumentException $e) {
    // a required parameter was empty
}

#Testing

composer test

#Static Analysis

composer analyse

#Code Formatting

composer format

#Changelog

Please see CHANGELOG for more information on what has changed recently.

#Contributing

Please see CONTRIBUTING for details.

#Security

Please review our security policy on how to report security vulnerabilities.

#Credits

#License

The MIT License (MIT). Please see License File for more information.