Hunter.io API Getting Started: Account, Keys, First Request (2026)

Getting started overview

Integrating with the Hunter.io API enables programmatic access to its suite of email-related services, including email verification, domain search, and email finding. This guide outlines the foundational steps required to begin development: account creation, API key retrieval, and executing an initial API call. Hunter.io's API is RESTful, communicating over HTTP with JSON payloads, and uses API keys for authentication, simplifying the setup process for developers looking to integrate email data capabilities into their applications or workflows.

The API provides endpoints for various functions, such as checking the validity of an email address, finding email addresses associated with a specific domain, or determining the author of a given article. Each request requires your unique API key for authentication, ensuring secure access to your account's allocated credits. Understanding the structure of these requests and responses is crucial for effective integration.

Create an account and get keys

Before making any API calls, you must establish a Hunter.io account and retrieve your API key. This key serves as your authentication credential for all API interactions.

Account creation

1. Navigate to the Hunter.io homepage: Open your web browser and go to the official Hunter.io website.
2. Sign up: Click on the 'Sign Up' or 'Get Started Free' button, typically located in the top right corner.
3. Provide details: Enter your email address and choose a strong password. You may also be able to sign up using a Google account.
4. Complete registration: Follow any on-screen prompts to verify your email address. Hunter.io offers a free tier that includes 50 verifications per month, suitable for initial testing and development.

API key retrieval

1. Log in: Once your account is active, log in to your Hunter.io dashboard.
2. Access API settings: In the dashboard, locate your profile icon or name, usually in the top right corner. Click on it to reveal a dropdown menu. Select 'API' or 'API Key' from this menu.
3. Copy your API key: Your unique API key will be displayed on this page. It is a long alphanumeric string. Copy this key securely. Treat your API key like a password; do not expose it in client-side code or public repositories.

For additional security, consider environment variables or a secrets management service to store your API key, especially in production environments. For local development, a .env file is a common practice.

Your first request

After obtaining your API key, you can make your first API call. A common starting point is the Email Verifier endpoint, which checks the validity of an email address. This example uses cURL for simplicity, but the Hunter.io API is compatible with any language capable of making HTTP requests. The official Hunter.io API documentation provides examples in various programming languages like Python, PHP, and Node.js.

Email Verifier API endpoint

The Email Verifier endpoint is located at https://api.hunter.io/v2/email-verifier. It requires two parameters: email (the email address to verify) and api_key (your personal API key).

Example: Verifying an email with cURL

Replace YOUR_API_KEY with the actual key you copied from your dashboard and [email protected] with an email address you wish to verify.

curl "https://api.hunter.io/v2/[email protected]&api_key=YOUR_API_KEY"

Expected successful response (JSON)

A successful response for a verifiable email address will return a JSON object containing verification details:

{
  "data": {
    "status": "valid",
    "result": "deliverable",
    "disposable": false,
    "webmail": true,
    "mx_records": true,
    "smtp_server": true,
    "gibberish": false,
    "details": {
      "reason": null,
      "regexp": true,
      "syntax": true,
      "dns": true,
      "blacklist": false,
      "autocatchall": false,
      "disposable": false,
      "smtp_check": true,
      "mx_records": [
        "smtp.example.com",
        "mail.example.com"
      ]
    }
  },
  "meta": {
    "params": {
      "email": "[email protected]"
    }
  }
}

The status and result fields are key indicators of the email's validity. A status of valid and a result of deliverable indicate a high probability that the email address is active and can receive mail.

Example: Verifying an email with Python

Using Python's requests library, you can achieve the same:

import requests
import os

API_KEY = os.getenv("HUNTER_API_KEY") # Recommended: store key in environment variable
EMAIL_TO_VERIFY = "[email protected]"

if not API_KEY:
    print("Error: HUNTER_API_KEY environment variable not set.")
else:
    url = f"https://api.hunter.io/v2/email-verifier?email={EMAIL_TO_VERIFY}&api_key={API_KEY}"
    response = requests.get(url)

    if response.status_code == 200:
        print(response.json())
    else:
        print(f"Error: {response.status_code} - {response.text}")

This Python example demonstrates how to construct the URL and handle the response, including basic error checking. Storing your API key in an environment variable (HUNTER_API_KEY) is a recommended security practice, as shown in the Python snippet. This prevents hardcoding sensitive credentials directly into your source code.

Common next steps

After successfully making your first API call, you can explore other Hunter.io API functionalities and integrate them into your applications. Here are some common next steps:

1. Explore other endpoints:
   • Domain Search: Find all email addresses associated with a specific domain (e.g., google.com). This is useful for lead generation or understanding an organization's structure. The endpoint is /v2/domain-search.
   • Email Finder: Given a first name, last name, and domain, attempt to find the most likely email address. This is a core feature for sales and outreach. The endpoint is /v2/email-finder.
   • Author Finder: Discover the email address of the author of a given article URL. This is valuable for content outreach. The endpoint is /v2/author-finder.
   • Bulk operations: For processing large lists, Hunter.io offers bulk endpoints for email verification and domain search, which can be more efficient than individual calls.
2. Implement rate limiting: Hunter.io, like many APIs, imposes rate limits to ensure fair usage and system stability. Monitor your API usage and implement client-side rate limiting or backoff strategies to avoid exceeding your plan's limits and encountering 429 Too Many Requests errors. Details on current rate limits are available in the Hunter.io API documentation.
3. Handle errors gracefully: Design your application to handle various API error codes (e.g., 400 Bad Request, 401 Unauthorized, 404 Not Found, 429 Too Many Requests, 500 Internal Server Error). Presenting user-friendly messages and logging errors can improve the user experience and aid debugging.
4. Monitor usage: Regularly check your API usage within the Hunter.io dashboard to ensure you stay within your monthly credit limits. Upgrade your plan if your usage consistently exceeds your current tier's allowance. The Hunter.io API documentation on usage provides details on how to track your consumption.
5. Explore SDKs and Libraries: While Hunter.io does not officially provide SDKs, community-contributed libraries for popular languages may simplify integration further. Search GitHub or package managers (like PyPI for Python or npm for Node.js) for "hunter.io API client" to find community-maintained options. When using third-party libraries, always review their source code and maintenance status.
6. GDPR Compliance: If your application processes personal data of individuals in the European Union, ensure your usage of Hunter.io API aligns with GDPR requirements. Hunter.io states its compliance with GDPR regulations on its website.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

• Check your API key: Ensure your API key is correct and hasn't been truncated or altered. Copy it directly from your Hunter.io API settings page. An incorrect key often results in a 401 Unauthorized error.
• Verify endpoint URL: Double-check that the URL for the API endpoint is correct (e.g., https://api.hunter.io/v2/email-verifier). Typos in the URL path or domain can lead to 404 Not Found errors.
• Parameter names and values: Confirm that parameter names (e.g., email, api_key) are spelled correctly and that their values are properly encoded (especially for special characters in email addresses, though less common for basic verification). Missing required parameters typically result in 400 Bad Request.
• Network connectivity: Ensure your development environment has an active internet connection and no firewall rules are blocking outgoing HTTP requests to api.hunter.io.
• Review HTTP status codes:
  • 200 OK: Success. The request was processed, and the response body contains the data.
  • 400 Bad Request: The request was malformed, often due to missing or incorrect parameters. Review the API documentation for required parameters.
  • 401 Unauthorized: Your API key is invalid or missing. Re-check your API key.
  • 404 Not Found: The requested endpoint does not exist. Verify the URL path.
  • 429 Too Many Requests: You have exceeded your rate limit. Wait before making further requests or implement rate limiting in your code.
  • 500 Internal Server Error: A server-side issue at Hunter.io. This is less common and usually indicates a temporary problem on their end.
• Consult Hunter.io documentation: The official Hunter.io API documentation is the authoritative source for endpoint specifics, error codes, and request examples.
• Check your credit balance: If you are on the free tier or a paid plan, ensure you haven't exhausted your monthly credits. You can check your remaining credits in your Hunter.io dashboard. If credits are depleted, API calls may fail or return specific error messages indicating insufficient credits.
• Use a tool like Postman or Insomnia: For debugging, tools like Postman or Insomnia allow you to construct and send API requests manually, helping isolate whether the issue lies with your code or the request itself. This can be particularly useful for verifying the correct URL and parameter structure before implementing it in your application. For general API client information, the Mozilla Developer Network HTTP Client Hints resource provides context on client-side request best practices.