--- name: hunter-io-f2f11c7cc373 description: >- Hunter.io is an email-finding and verification service with a REST API: list the public email addresses of a company domain, find one person's work email, check whether an address is deliverable, and detect a company's email pattern. Use when asked to "find emails for a domain", "find the email of a person at a company", "verify an email address with Hunter", "discover a company's email format", or for lead generation and authorized OSINT or phishing-simulation scoping. license: Apache-2.0 compatibility: Python 3.9+ with requests; a Hunter API key (free plan available) metadata: author: terminal-skills version: "1.1.0" category: research tags: "hunter, email, recon, lead-generation, email-verification" use-cases: "Find all publicly known email addresses for a target company domain, Discover the email naming convention used by a company, Verify that an email address is deliverable before sending outreach, Enrich a prospect list with work emails for a sales campaign" agents: "claude-code, openai-codex, gemini-cli, cursor" --- # Hunter.io ## Overview Hunter indexes professional email addresses found on the public web and exposes them through a REST API at `https://api.hunter.io/v2`. The endpoints that matter: Domain Search (emails for a domain, plus the company's email pattern), Email Finder (one person's address from name and domain), Email Verifier (deliverability check), Email Count (how many addresses are indexed, free) and Account (plan and credits). Checked against Hunter's API reference and OpenAPI file in October 2026. Hunter also publishes a hosted MCP server at `https://mcp.hunter.io/mcp` (OAuth for Claude, ChatGPT and Gemini; `X-API-Key` header for Cursor, VS Code, Codex and similar clients). If the agent has it connected, prefer the tools `Domain-Search`, `Email-Finder` and `Email-Verifier` over hand-written HTTP. Billing is by credits: a search or finder lookup costs 1 credit and a verification 0.5. The Free plan includes 50 credits a month; check `pricing` and `/account` before bulk work. ## Instructions ### 1. Authenticate Create a key at hunter.io/api-keys and export it. Send it in the `X-API-KEY` header; `?api_key=` also works but leaks the key into URLs and logs. The special key `test-api-key` validates parameters on Domain Search, Email Finder and Email Verifier and returns a fixed dummy response, which is useful for testing code without spending credits. ```bash export HUNTER_API_KEY="..." # from hunter.io/api-keys; never commit it ``` ```python import os import requests BASE = "https://api.hunter.io/v2" session = requests.Session() session.headers["X-API-KEY"] = os.environ["HUNTER_API_KEY"] def hunter(endpoint: str, **params) -> requests.Response: r = session.get(f"{BASE}/{endpoint}", params=params, timeout=30) if r.status_code == 403: raise RuntimeError("Hunter rate limit hit; slow down and retry later") if r.status_code == 429: raise RuntimeError("Hunter usage limit reached; check /account or upgrade the plan") r.raise_for_status() return r account = hunter("account").json()["data"] print(account["plan_name"], account["requests"]) # remaining credits or search/verification quotas ``` ### 2. Domain Search Parameters: `domain` (or `company`), `limit` 1-100 (default 10), `offset`, `type` (`personal` or `generic`), `department` and `seniority` (comma-separated, from Hunter's live taxonomy; unknown values are ignored and an all-unknown list returns 400), `job_titles`, `provenance` (`found` or `inferred`), `verification_status`. On the Free plan `limit + offset` may not exceed 10 and `limit` is capped at 10. ```python def domain_search(domain: str, limit: int = 10, offset: int = 0, **filters): data = hunter("domain-search", domain=domain, limit=limit, offset=offset, **filters).json()["data"] print(f"{data['domain']}: pattern={data.get('pattern')} org={data.get('organization')}") for e in data["emails"]: name = f"{e.get('first_name') or ''} {e.get('last_name') or ''}".strip() print(f" {e['value']:<38} {e['confidence']:>3}% {name} {e.get('position') or ''}") return data domain_search("stripe.com", limit=10, department="engineering", seniority="senior,executive") ``` To page through everything on a paid plan, raise `offset` by `limit` until `len(emails) < limit` or `offset` reaches the top-level `meta["results"]` of the response (a sibling of `data`); check `/email-count` first (free) to know the size. ### 3. Email Finder Needs `domain` or `company`, plus `first_name` and `last_name` (or `full_name`), or a `linkedin_handle`. `max_duration` (3-20 seconds) bounds the wait. ```python def find_email(first: str, last: str, domain: str): r = hunter("email-finder", domain=domain, first_name=first, last_name=last) d = r.json()["data"] print(d["email"], d["score"], d["position"]) return d ``` A 404 means no address was found. The `score` (0-100) is Hunter's confidence. ### 4. Email Verifier `status` is one of `valid`, `invalid`, `accept_all` (server accepts anything, so deliverability cannot be proven), `webmail`, `disposable`, `unknown`. Fields `result` and `score` still appear but `result` carries a deprecation notice; rely on `status`. HTTP 202 means verification is still running (call again after a few seconds); 222 means it failed for external reasons and can be retried later; 451 means the address cannot be processed for privacy reasons. ```python import time def verify(email: str, tries: int = 4) -> dict: for _ in range(tries): r = hunter("email-verifier", email=email) if r.status_code == 200: return r.json()["data"] time.sleep(5) # 202: still in progress return {"email": email, "status": "unknown"} print(verify("patrick@stripe.com")["status"]) ``` ### 5. Email Count and pattern `GET /email-count?domain=stripe.com` is free (documented; needs a real key, the test key is rejected) and returns totals (optionally `type=personal|generic`). The `pattern` in a Domain Search response, such as `{first}.{last}`, tells you the format; combine it with a verified lookup rather than guessing addresses. ## Examples ### Example 1: "Find the engineering leads at a company and their email format" ```python data = domain_search("vercel.com", limit=10, department="engineering", seniority="senior,executive") ``` Result: a printed list of up to 10 addresses with confidence scores and positions, and the company pattern (for example `{first}`), which you can reuse for people not in the list. ### Example 2: "Check this lead list before the campaign goes out" ```python leads = ["maria.lopez@northwind.dev", "info@northwind.dev", "tmp123@mailinator.com"] for email in leads: print(email, verify(email)["status"]) time.sleep(0.2) # stays well under the 10 requests/second verifier limit ``` Result: one status per address; drop `invalid` and `disposable`, and treat `accept_all` as risky rather than confirmed. ## Guidelines - Rate limits per endpoint: Domain Search and Email Finder 15 requests/second and 500/minute, Email Verifier 10/second and 300/minute, Discover 5/second and 50/minute. HTTP 403 means you hit a rate limit: back off. HTTP 429 means your plan's usage limit is used up: backing off does not help. - Email Finder and Email Verifier save found or valid addresses into your Hunter leads automatically unless you turn that off in the account settings. Keep that in mind when running tests against real people. - Credits are spent per call, including when the result is poor. Use the free `/email-count` and the `test-api-key` first. - A confidence score is not proof; verify before sending, and treat `accept_all` domains as unverifiable. - Use the data only for lawful purposes: sales outreach that respects GDPR/CAN-SPAM opt-out rules, journalism, or security work you are authorized to do (such as scoping a phishing simulation in a signed engagement). Do not build lists of private individuals' addresses. - Never log or print the API key, and keep it out of source control. --- Source attribution: terminal-skills Original project: https://github.com/TerminalSkills/skills/blob/8a9852d489f274538be9bf1c9121aeb403750b1c/skills/hunter-io/SKILL.md License: Apache-2.0 License information: https://www.apache.org/licenses/LICENSE-2.0 Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to the Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by the Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding any notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS Copyright 2025 Terminal Skills Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. # Mega AI Hub resource metadata Creator / publisher: terminal-skills Original project: https://github.com/TerminalSkills/skills/blob/8a9852d489f274538be9bf1c9121aeb403750b1c/skills/hunter-io/SKILL.md Attribution basis: Source repository record Fields of work: Marketing, Sales Roles: Marketing Analyst, Sales Development Rep (SDR), Business Development, Growth Marketer, Influencer Marketer Specialties: API Tools: Hunter.Io Country applicability: Country not specified Classification basis: Source category, role and specialization labels Instruction SHA-256: 7453fd146bbd16f8acbde31a24d72b4cb1bfd2da77cff587b8a5d5537ece797a