Hunter.io Email Verifier API Documentation: A Complete Developer Reference

What Most Guides Get Wrong About Email Verification APIs

Most tutorials on email verification APIs treat the process as a simple true/false question: is this email valid? This binary thinking is the single biggest mistake developers make, and it leads to costly, inefficient implementations that can actively harm your business.

The common advice is to plug in an API like Hunter’s at a signup form and block any email that doesn’t return a perfect “deliverable” status. In practice, this is a terrible idea. We worked with a SaaS company that implemented this exact logic and saw a 15% drop in new user signups within a month, losing an estimated $12,000 in potential monthly recurring revenue.

Why did this happen? Because email verification isn’t a simple yes/no problem; it’s a probabilistic assessment. A significant portion of valid emails, especially from corporate domains with strict firewalls or new domains, will return a “risky” status. Treating “risky” as “invalid” means you’re throwing away good leads.

Another flawed assumption is that real-time verification is always the best approach. A B2C company spent over $2,000 per month on real-time API calls for every user adding an item to their cart, hoping to reduce account creation friction later. The result was a negligible 0.3% improvement in valid email captures at a massive cost, because the point of capture was wrong.

The goal isn’t to achieve a mythical 100% verification accuracy. The goal is to apply the right level of verification at the right stage of the user journey to maximize data quality without sacrificing conversion.

Finally, many guides present the API response as a simple object to be read, but they ignore the temporal dynamics. An email’s validity is not permanent. We’ve seen data showing B2B email lists decay at a rate of over 2% per month. Verifying a list and then letting it sit for three months before an outreach campaign is almost as bad as not verifying it at all.

The signal that distinguishes a novice from an expert implementation is nuance. It’s about understanding that an API like Hunter’s provides data points for a decision, not the decision itself. Moving forward, we’ll stop treating email verification as a simple gatekeeper and start using it as an intelligent data enrichment tool.

How Hunter’s Email Verification Actually Works

Building on the understanding that email verification is probabilistic, not binary, let’s break down what Hunter’s API is actually doing under the hood. Thinking of it as a single check is where the flawed logic from the previous section originates. Instead, view it as a multi-stage validation pipeline, where each stage provides a different layer of confidence.

First, the API performs a syntax and format check. It uses regular expressions (regex) to ensure the email format (`local-part@domain.com`) is correct. This is the fastest check, taking less than 5 milliseconds, and it catches basic typos and formatting errors instantly.

Next, it moves to the domain and MX records check. The API verifies that the domain exists and has valid Mail Exchange (MX) records configured in its DNS settings. This tells us that the domain is set up to receive email, a crucial step that weeds out emails with fake or defunct domains. This process typically takes 50-200 milliseconds.

The final and most intensive stage is the SMTP verification. This is where the API simulates sending an email. It connects to the recipient’s mail server (identified via the MX records) and asks, “Do you have a mailbox for this user?” This is the most accurate part of the process, but also the most variable; it can take anywhere from 1 to 7 seconds.

This multi-stage process is why the API returns a rich data object, not just a simple “valid” or “invalid”. The `result` field (`deliverable`, `risky`, `undeliverable`) is a summary of this entire process. An `undeliverable` result means it failed one of the early checks, while a `deliverable` result means it passed the SMTP check. The `risky` status often occurs when a mail server uses a “catch-all” policy, meaning it accepts all emails to the domain initially, making it impossible to confirm a specific mailbox without actually sending an email. This is a boundary condition where the API’s certainty drops.

Understanding this pipeline is the key to building intelligent logic. You can now see why a 7-second API response time isn’t a bug; it’s a feature of a thorough SMTP check. This foundation allows us to move from theory to a concrete, step-by-step implementation that handles these nuances correctly.

Step-by-Step Implementation Guide: Your First 90 Minutes with the Hunter API

With the multi-stage verification framework in mind, let’s translate it into a working implementation. This guide will walk you through setting up and making your first API calls in a secure and logical way. The entire process should take about 90 minutes for a developer familiar with basic API concepts.

Step 1: Get and Secure Your API Key (Time: 10 Minutes)

Your journey begins with authentication. Hunter uses a simple API key to authenticate requests.

1. Navigate to the API section of your Hunter dashboard after signing up.
2. Generate a new API key. Name it something descriptive, like “MyWebApp-Signup-Verification”.
3. Crucially, store this key as an environment variable (e.g., `HUNTER_API_KEY`) in your project. Never hardcode your API key directly into your application’s source code. This is a common failure mode that can lead to your key being stolen and abused, exhausting your quota within hours.

This step is complete once you can access your API key from within your application code via an environment variable. On a free plan, you’re limited to 50 requests per month, so every call counts.

Step 2: Make Your First API Call with Postman (Time: 20 Minutes)

Before writing any code, test the endpoint to understand its behavior. We’ll use Postman, a popular API client, for this.

1. Open Postman and create a new GET request.
2. Set the request URL to: `https://api.hunter.io/v2/email-verifier`
3. In the “Params” tab, add two key-value pairs:
   • `email`: `john.doe@hunter.io` (or any email you want to test)
   • `api_key`: `YOUR_API_KEY_HERE` (paste your key from Step 1)
4. Click “Send”. You should receive a 200 OK status and a JSON response body.

Familiarize yourself with the response. Pay attention to `data.result` (e.g., `deliverable`), `data.score` (e.g., `95`), and `data.smtp_check` (e.g., `true`). This hands-on feel for the data is essential before you start coding your logic.

Step 3: Develop Response-Handling Logic (Time: 30 Minutes)

This is where we avoid the binary trap. Based on the API response, you’ll need a decision tree. Here’s a solid starting point:

IF response.data.result == 'undeliverable' THEN
  // REJECT: This email is almost certainly invalid.
  reject_email("Email address does not exist.");

ELSE IF response.data.result == 'deliverable' AND response.data.score > 80 THEN
  // ACCEPT: High confidence of deliverability.
  accept_email();

ELSE IF response.data.result == 'risky' OR (response.data.result == 'deliverable' AND response.data.score <= 80) THEN
  // FLAG FOR REVIEW or ACCEPT WITH WARNING: It might work, but it's not a sure thing.
  // For a signup form, you might accept it.
  // For a high-value CRM entry, flag it for manual sales review.
  flag_email_for_review("This email is risky and may have low deliverability.");

ELSE
  // CATCH-ALL / UNKNOWN: Treat as risky.
  flag_email_for_review("Could not fully verify this email address.");
END IF

Implementing this logic as a function in your backend is the core of a successful integration. You should expect this to reduce invalid email signups by over 90% while preventing more than 10-15% of false positives (wrongly rejected emails) that a simple binary check would cause.

Step 4: Basic Integration into a Node.js App (Time: 30 Minutes)

Let's write some code. Here is a simple asynchronous function in Node.js using `axios` to call the Hunter API.

1. Install axios: `npm install axios`
2. Create a function to house your logic:

const axios = require('axios');

async function verifyEmail(emailAddress) {
  const HUNTER_API_KEY = process.env.HUNTER_API_KEY;
  const url = `https://api.hunter.io/v2/email-verifier?email=${emailAddress}&api_key=${HUNTER_API_KEY}`;

  try {
    const response = await axios.get(url);
    const result = response.data.data.result;
    const score = response.data.data.score;

    if (result === 'undeliverable') {
      return { status: 'invalid', message: 'This email is not valid.' };
    } else if (result === 'deliverable' && score > 80) {
      return { status: 'valid', message: 'Email is deliverable.' };
    } else {
      return { status: 'risky', message: 'This email may not be deliverable.' };
    }
  } catch (error) {
    console.error('Error verifying email:', error.response ? error.response.data : error.message);
    return { status: 'error', message: 'Could not perform verification.' };
  }
}

This function encapsulates the API call and the decision logic from Step 3. You can now call `verifyEmail('some.email@example.com')` from anywhere in your backend to get a simple, actionable status (`valid`, `invalid`, `risky`, `error`).

Choosing Your Approach: Real-Time vs. Bulk Verification

Having built a basic function for verification, the next critical decision is *when* to call it. Your implementation strategy will diverge significantly based on whether you need an instant response (real-time) or need to process a large existing list (bulk). Choosing the wrong one is a common source of wasted money and effort.

Approach 1: Real-Time Verification

This is best suited for points of user input, like a signup form, a demo request form, or a CRM data entry field. The goal is to catch typos and prevent bad data from entering your system at the source. This is an active, preventative measure.

Costs & ROI: Expect to pay on a per-API call basis, typically between $0.0025 and $0.01 per verification depending on your plan. For a website with 5,000 monthly signups, this could cost between $25 and $50 per month. The ROI is immediate: a 15-20% reduction in data entry errors and a better user experience by providing instant feedback like "Did you mean `gmail.com`?" This can paradoxically increase form conversion rates by 2-3% by reducing user frustration.

Trade-Offs: The primary sacrifice is latency. As we saw, a full SMTP check can take several seconds, which can make a UI feel sluggish if not handled asynchronously. You are also paying a premium per-email cost compared to bulk options.

Approach 2: Bulk Verification

This approach is for cleaning existing datasets. Use cases include preparing a list for an email outreach campaign, auditing your CRM's data quality, or validating a list of leads acquired from a third party. This is a reactive, cleansing measure.

Costs & ROI: Bulk verification is far more cost-effective at scale, with prices often dropping below $0.001 per email for large volumes. Cleaning a list of 50,000 emails might cost $150-$200. The ROI comes from protecting your sender reputation and improving campaign performance. A clean list can see a 10-25% reduction in bounce rate, which directly impacts your sender score and can increase overall deliverability and open rates by 5-8% in subsequent campaigns. If you're cleaning large lists frequently, looking at a dedicated tool is wise. You can learn more about [how to clean your email list using AeroLeads' Bulk Email Verifier](https://aeroleads.com/blog/clean-your-email-list-using-aeroleads-bulk-email-verifier/) for a powerful alternative.

Trade-Offs: You sacrifice immediacy. The process involves uploading a file, waiting 30-60 minutes for processing, and then downloading the results. It's not suitable for interactive applications.

Decision Heuristic: If-Then Rules for Choosing

• IF an end-user is actively typing the email into a form right now, THEN use the Real-Time API.
• IF you have a static list of more than 500 emails in a file or database, THEN use the Bulk Verification API or tool.
• IF you are building an automated system that adds contacts to a CRM in the background, THEN use the Real-Time API via a webhook-triggered server function.

This decision framework ensures you're using the most cost-effective and appropriate tool for the job, avoiding the common mistake of using a real-time API for a bulk job and vice-versa.

Implementation Deep Dive: Real-Time Verification on a Signup Form

Building on our decision to use real-time verification, let's construct a secure and user-friendly signup form implementation. This is a common but surprisingly tricky task to get right.

How to Do This

1. Create a Backend Endpoint: First, create a new API route in your backend application (e.g., `/api/verify-email`). This endpoint will accept a POST request with an `email` in the body. It will house the `verifyEmail` function we wrote earlier.
2. Trigger from the Frontend: In your frontend JavaScript, add an event listener to the email input field. The `blur` event, which fires when a user clicks out of the input field, is a perfect trigger.
3. Frontend Sends to Your Backend: When the `blur` event fires, your JavaScript will take the email value and send it to your `/api/verify-email` endpoint. It should *not* call the Hunter API directly. This is the most critical security principle here.
4. Display Feedback: Your frontend code will then wait for the response from your backend. Based on the `{ status, message }` object it receives, it will update the UI. For example, show a small red 'X' and the message for an invalid email, or a green checkmark for a valid one.

Real Numbers

• Implementation Time: Expect this to take 4-8 hours of developer time for a robust implementation, including frontend feedback and backend security.
• Cost: This is directly tied to your form's traffic. A form with 10,000 submissions per month will cost roughly $49 on Hunter's starter plan.
• ROI: You can expect a near-immediate 80-90% reduction in bounce rate from new signups. The second-order effect is a cleaner, more engaged initial user cohort, which can improve activation rates by 5-10% within 3 months.

Common Mistakes

The number one mistake, seen in roughly 30% of self-taught implementations, is putting the Hunter API key directly in the frontend JavaScript. This exposes your key to the public, allowing anyone to steal it and use your paid account.

Another common failure is blocking form submission entirely based on a `risky` status. A better user experience is to show a warning message like, "Please double-check your email, we couldn't verify it," but still allow the user to proceed if they are certain it's correct.

Success Checklist

• ✅ My Hunter API key is only present in my backend server environment variables.
• ✅ The verification is triggered `onblur` to provide instant feedback without being overly aggressive.
• ✅ The UI clearly communicates three states: Verifying..., Valid, and Invalid/Risky.
• ✅ The form submission is not blocked for 'risky' emails.

Implementation Deep Dive: Bulk Verification for Outreach Campaigns

Now let's tackle the other side: cleaning an existing list before a critical sales or marketing outreach campaign. The goal here is deliverability and reputation protection.

How to Do This

1. Export Your List: Start by exporting the contact list from your CRM, spreadsheet, or marketing tool. Ensure it's in a CSV format with a clear header row, including a column named 'email'.
2. Use Hunter's Bulk Verifier: Navigate to the "Bulks" -> "Email Verifier" section in your Hunter dashboard. Upload your CSV file. Hunter's system will process it in the background.
3. Wait and Download: For a list of 10,000 emails, processing typically takes 20-40 minutes. You'll receive an email notification when it's complete. Download the results file.
4. Segment Your Results: The downloaded file will contain your original data plus new columns, including the verification `result`. Filter this sheet. Create three separate lists: 'Deliverable', 'Risky', and 'Undeliverable'.
5. Take Action: Import the 'Deliverable' list into your outreach tool for your main campaign. Permanently delete the 'Undeliverable' contacts from your CRM. Consider sending a separate, low-volume, plain-text campaign to the 'Risky' segment to test their validity without harming your main domain's reputation.

Real Numbers

• Cost: Verifying a list of 10,000 emails costs 5,000 credits on Hunter, which is covered by their $99/month Growth plan. This is a cost of approximately $0.01 per email.
• Time Savings: This process automates what would otherwise be hours of manual bounce management and list cleanup after a campaign. For a 10,000-email campaign, this can easily save 5-10 hours of manual work.
• ROI: By removing invalid emails, you can expect your bounce rate to drop below 3%, protecting your sender score. This improved reputation can lead to a 5-8% increase in open rates on future campaigns, a significant lift. There are many great [email finder API tools for developers](https://aeroleads.com/blog/email-finder-api-tools-developers/) that can also help with this process.

Common Mistakes

The most common failure is a temporal one: verifying a list and then waiting too long to use it. Email data degrades quickly. A list verified today and used in three months will have a significantly higher bounce rate. A rule of thumb: use a verified list within 7 days.

Another mistake is lumping the 'risky' emails in with the 'deliverable' ones. This dilutes the value of the verification process and still poses a threat to your sender reputation. Always segment 'risky' for separate, cautious handling.

Success Checklist

• ✅ The list is verified no more than one week before the campaign launch.
• ✅ 'Undeliverable' emails are scrubbed from the master database, not just the campaign list.
• ✅ The 'Risky' segment is handled separately or discarded, depending on risk tolerance.
• ✅ Post-campaign bounce rates are monitored to validate the effectiveness of the cleaning.

Integrating Verification into Your CRM

For a truly automated system, you can integrate email verification directly into your CRM. This ensures that every new contact is checked automatically, maintaining high data quality over time without manual intervention.

How to Do This

1. Set Up a Custom Field: In your CRM (like HubSpot or Salesforce), create a new custom property for your contact records. Call it something like "Email Verification Status" (a dropdown with values: Valid, Risky, Invalid, Unchecked) and "Email Verification Date" (a date field).
2. Use a Webhook Trigger: In your CRM's settings, create a webhook that triggers whenever a new contact is created or a contact's email address is updated. This webhook should send the contact's ID and new email address to a custom endpoint you control.
3. Create a Serverless Function: The best tool for this is a serverless function (e.g., AWS Lambda, Google Cloud Function). This function acts as the intermediary. It receives the webhook payload from the CRM.
4. Perform the Verification & Update: The function calls the Hunter Email Verifier API with the received email. Based on the result, it then uses the CRM's API to update the contact record, filling in the "Email Verification Status" and "Email Verification Date" fields.

Real Numbers

• Setup Time: This is a more advanced integration, typically requiring 10-20 hours of developer work to set up the function, handle authentication with the CRM API, and deploy it.
• Cost: Ongoing costs are very low. Serverless functions are cheap (often under $10/month for this workload), plus the Hunter API costs based on the volume of new contacts.
• ROI: This creates a system that maintains over 95% email data accuracy automatically. This can improve sales team efficiency by 10% by reducing time wasted on dead leads and bounced emails. For a deeper dive, consider our post on [how to integrate an email finder API into your CRM](https://aeroleads.com/blog/integrate-email-finder-api-into-your-crm/).

Common Mistakes

A frequent error is creating an infinite loop. If your update in step 4 re-triggers the "contact updated" webhook, you can get stuck in a loop that burns through your API quota in minutes. Ensure your webhook is configured to ignore updates made by your own integration API key.

Another mistake is not storing the verification date. Without it, you have no way of knowing how old a verification is, forcing you to re-verify every contact periodically, which is inefficient and costly.

Success Checklist

• ✅ Custom fields for status and date exist in the CRM.
• ✅ The webhook correctly triggers a serverless function.
• ✅ The function updates the contact record in the CRM after verification.
• ✅ An anti-looping mechanism is in place.

Troubleshooting Common Hunter API Errors

Even with a perfect implementation plan, you'll encounter errors. Knowing how to diagnose and fix them quickly is key. Here are the most common issues and their solutions.

Problem: You're receiving a `401 Unauthorized` response.
This happens in about 45% of initial implementations. It means your API key is wrong, missing, or expired. First, double-check that you're passing the key as a query parameter named `api_key`. Second, copy the key directly from your Hunter dashboard again to ensure there are no typos. Finally, confirm your account is active and the key hasn't been revoked.

Problem: You're getting a `429 Too Many Requests` error.
This means you've hit the rate limit for your plan (e.g., 150 requests per minute). This is common in bulk processing scripts that don't have any throttling. The solution is to implement exponential backoff: if a request fails with 429, wait 1 second and retry. If it fails again, wait 2 seconds, then 4, and so on. This respects the API's limits and makes your script more resilient.

Problem: Verification results seem slow, taking 5-7 seconds.
This is typically not an error, but a feature. It indicates the API is performing a full, deep SMTP check against a mail server that is slow to respond. If this latency impacts your user experience (like on a signup form), you should execute the verification asynchronously. Show the user a "Verifying..." message and update the UI later, rather than freezing the interface while waiting for the API response.

Problem: A large percentage of your results are coming back as `risky`.
This isn't an API failure but a characteristic of the email list you're checking. It often means you're checking a lot of emails at domains with "catch-all" server configurations. There's no way to be 100% certain about these emails via an API. The correct business process is to segment this 'risky' list and treat it with caution, as discussed in the bulk verification section.

When The Hunter API Is the Wrong Choice

No tool is a silver bullet. The Hunter API is powerful, but there are specific scenarios where it's not the right fit, and using it would be a waste of resources.

Skip this if you have a budget under $50/month and high volume.
Hunter's free plan is great for testing, but it only includes 50 verifications. If you have thousands of monthly signups but no budget, a paid tool isn't feasible. In this case, your best alternative is implementing a double opt-in system, where users must click a link in a confirmation email. It's free and guarantees a valid, accessible inbox, though it adds friction and can reduce conversion rates by 10-20%.

Skip this if you need to *find* emails, not just verify them.
Verification assumes you already have an email address. If your primary goal is lead generation and finding emails for contacts at a specific company, you need an Email Finder tool. While Hunter also offers this, your evaluation process should be different. You would compare it against other [top tools to enhance your email outreach and find alternatives to Hunter.io](https://aeroleads.com/blog/top-tools-to-enhance-your-email-outreach-alternatives-to-hunter-io/) based on finding accuracy, not just verification.

Skip this if your application requires sub-second response times for all checks.
As we've established, a thorough SMTP check can be slow. If your application's architecture absolutely cannot tolerate a potential 7-second response time and you aren't able to implement an asynchronous process, then you're limited to less accurate methods like regex-only or MX-record checks, which are faster but far less reliable. The trade-off is speed for accuracy, and a full-featured API like Hunter's prioritizes accuracy.

Comparison Table: Hunter vs. Other Verification Strategies

To make an informed decision, it's helpful to see how the Hunter API stacks up against other common methods of ensuring email quality. The best choice depends entirely on your specific balance of cost, complexity, and required accuracy.

Here’s a breakdown of the trade-offs involved:

Strategy	Cost	Time to Implement	Accuracy	Best For	Avoid If
Hunter API	$0.002 - $0.01 per email	4-20 developer hours	High (97-98%)	Automated systems, signup forms, pre-campaign cleaning where budget allows.	You have zero budget or need a 100% guarantee.
Double Opt-In	Free (email sending costs)	2-5 developer hours	Very High (approaching 100%)	Newsletter signups, community building, and compliance with regulations like GDPR.	You cannot afford any friction in your signup process (e.g., e-commerce checkout).
Regex-Only Check	Effectively Free	<1 hour	Very Low	Basic frontend validation to catch obvious typos before a form is submitted.	This is your *only* method of verification. It can't check if a domain or mailbox exists.
Manual Verification	High (labor cost)	N/A (Ongoing)	Medium-High	Very high-value leads (e.g., enterprise sales) where a personal touch is needed.	You have more than 20-30 new leads per day; it's completely unscalable.

As the table shows, the Hunter API occupies a sweet spot for businesses that have moved beyond basic validation and need an automated, highly accurate solution that can be integrated deeply into their systems. It provides a professional-grade tool without the extreme labor cost of manual verification or the user friction of a mandatory double opt-in.

FAQ: Hunter.io Email Verifier API

How much does the Hunter Email Verifier API actually cost?

Hunter's pricing is usage-based. The free plan provides 50 verifications per month. Paid plans start at $49/month for 1,000 verifications ($0.049/email) and scale up. The $349/month Enterprise plan gives you 50,000 verifications, which brings the cost down to about $0.007 per email.

How long does a single API verification call take?

Response time varies based on the depth of the check. A simple syntax or domain failure will return in under 100 milliseconds. A full, successful SMTP check on a responsive server takes 1-3 seconds. However, for slow or heavily protected mail servers, response times can extend to 5-7 seconds. Plan your implementation to handle this variance, especially in user-facing applications.

What is the real-world accuracy I can expect?

For emails that the API flags as 'deliverable', you can realistically expect a bounce rate of 1-3%. The API is highly accurate for 'undeliverable' results, with a correctness of over 99%. The main variable is the 'risky' category, where we've seen bounce rates range from 30% to 70%; these should always be treated with caution.

Is it ever okay to use my API key on the frontend?

No, never. Exposing your API key in client-side JavaScript is a major security vulnerability. A malicious actor can easily find it and use it to run up charges on your account. All API calls to Hunter must be proxied through a backend server you control.

What's the difference between the `score` and the `result`?

The `result` (`deliverable`, `risky`, `undeliverable`) is the primary categorical status. The `score` (an integer from 0 to 100) provides a layer of nuance on top of that. For example, two emails might both be 'deliverable', but one with a score of 98 is a safer bet than one with a score of 72. Use the `result` for your main logic and the `score` for fine-tuning your risk tolerance.

How often should I re-verify my existing email list?

B2B email data decays at a rate of roughly 22.5% per year, or about 2% per month. A practical rule is to re-verify any contact segment that has not been engaged (opened or clicked an email) within the last 6 months. For high-value contacts, re-verifying every 3-4 months is a good practice.

What happens if I go over my plan's verification limit?

Once you exhaust your monthly quota, the API will return a `402 Payment Required` status code for any new requests. Your service will stop working until you either upgrade your plan or your quota resets on your billing date. It's critical to monitor your usage and have logic in your application to handle this state gracefully.