Hunter.io ExecModule

Overview

HunterModule connects ValkyrAI workflows to the fixed Hunter API v2 host through the native map I/O ExecModule ABI. It performs bounded domain search, email finding and verification, email counts, person, company, and combined enrichment, and account-usage inspection without exposing the Hunter API key to workflow data.

The connector follows the core domain-search, email-finder, and email-verifier operations in n8n's Hunter integration. ValkyrAI also exposes Hunter's current read-only enrichment and usage endpoints, while adding the generated IntegrationAccount boundary, fixed-host routing, bounded retry and response handling, identity checks, and credential redaction.

Hunter results may contain personal data. Use the module only for approved business purposes, apply consent and outreach rules downstream, and honor Hunter's HTTP 451 privacy response as a permanent stop for that person or address.

Usage

1. Create a least-privilege Hunter API key for the intended team and plan.
2. Store the key only in the encrypted IntegrationAccount.apiKey SecureField.
3. Mark the IntegrationAccount READY after its connection test succeeds.
4. Select one operation and provide only its required domain, company, email, or name fields.
5. Review enriched data under the caller's approved sales or customer workflow before outreach.

Inputs

Input	Type	Required	Default	Description
operation	string	Yes	None	One of the eight operations listed below.
domain	string	By operation	None	Valid DNS company domain; URLs and paths are rejected.
company	string	Alternative	None	Company name when a domain is unavailable.
email	string	By operation	None	Professional address for verification or enrichment.
firstName	string	Finder option	None	First name paired with lastName.
lastName	string	Finder option	None	Last name paired with firstName.
fullName	string	Finder option	None	Alternative to separate first and last names.
type	string	No	None	personal or generic for domain search or email count.
department	string	No	None	Bounded Hunter department filter for domain search.
seniority	string	No	None	Bounded Hunter seniority filter for domain search.
jobTitles	string	No	None	Comma-delimited job-title filter, up to 500 characters.
decisionMaker	boolean	No	false	Restrict domain search to decision makers.
maxDuration	integer	No	10	Hunter email-finder time budget from 3 through 20 seconds.
limit	integer	No	10	Domain-search page size from 1 through 100.
offset	integer	No	0	Domain-search result offset from 0 through 10,000.

domain_search, email_count, and email_finder accept domain or company. When both are supplied, the validated domain is used and company is omitted from the provider request. email_finder additionally requires either fullName or both firstName and lastName; the two name shapes cannot be mixed.

Outputs

Output	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized Hunter operation.
data	object/array	Success	Sanitized provider data with credential-shaped fields removed.
items	array	Domain search	Bounded email-address results from the current provider page.
count	integer	Domain search	Number of returned items.
total	integer	Domain search	Provider-reported matching result count.
hasMore	boolean	Domain search	Whether the next offset may return more results.
nextOffset	integer	More results	Offset for the next workflow execution.
pending	boolean	HTTP 202 verifier	Verification is still processing and may be polled later.
httpStatus	integer	Provider response	Hunter HTTP status.
attempts	integer	Always	Provider attempts consumed.
error	object	Failure	Redacted code, message, and retryable fields.

IntegrationAccount Requirements

Field	Requirement
Provider	Hunter API v2
Status	READY
apiKey	Encrypted SecureField containing the Hunter API key
accountId	Optional operator label; not sent to Hunter

Hunter's REST v2 contract requires the API key as the api_key query parameter. The module adds it only inside the fixed-host HTTP request, never accepts it from workflow input, never includes it in output, and never logs request URLs. Rotate the key through the IntegrationAccount lifecycle if it may have appeared in external proxy or provider logs.

Use separate keys or IntegrationAccounts when teams require distinct Hunter plans, credit pools, or access boundaries. A Hunter team is not a substitute for ValkyrAI RBAC or approval policy.

Configuration

{
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:hunter-sales-research"
  },
  "parameters": "{\"operation\":\"domain_search\",\"department\":\"it\",\"decisionMaker\":true,\"limit\":25}"
}

Credentials stay in authConfig.integrationAccount. Do not place an API key in parameters, workflow input, a domain, company name, email, logs, or examples.

Operations

Operation	Hunter behavior	Required inputs	Side effect
domain_search	Returns one offset page of professional addresses and company context.	domain or company	Read-only; may consume search credits.
email_finder	Finds the most likely professional address and its verification context.	domain or company; one valid name shape	Read-only; may consume search credits.
email_verifier	Checks deliverability and provider evidence.	email	Read-only; may consume verification credits.
email_count	Returns available personal/generic counts for a company.	domain or company	Read-only.
person_enrichment	Returns Hunter's current person enrichment for an address.	email	Read-only; may consume enrichment credits.
company_enrichment	Returns company context for a domain.	domain	Read-only; may consume enrichment credits.
combined_enrichment	Returns person and company context together.	email	Read-only; may consume enrichment credits.
account_info	Returns plan and current request usage.	None	Read-only and free under Hunter's current contract.

Every operation uses GET. Transient HTTP and network failures use at most three bounded attempts. A verifier HTTP 202 is returned as successful pending work. Hunter's nonstandard HTTP 222 verifier outcome becomes HUNTER_VERIFICATION_UNAVAILABLE rather than false success.

Errors and Failure Modes

Error	Retryable	Recovery
VALIDATION_ERROR	No	Correct the named domain, company, email, name shape, filter, bound, or credential.
INTEGRATION_ACCOUNT_REQUIRED	No	Bind a Hunter IntegrationAccount.
INTEGRATION_ACCOUNT_NOT_READY	No	Repair and mark the account READY.
HUNTER_HTTP_400	No	Correct missing or invalid provider parameters.
HUNTER_HTTP_401	No	Rotate the Hunter API key.
HUNTER_HTTP_403	No	Wait for rate-limit recovery or use a plan with the required endpoint.
HUNTER_HTTP_404	No	Treat the requested enrichment resource as unavailable.
HUNTER_HTTP_429	Yes	Wait for plan usage to reset or upgrade the relevant credit allowance.
HUNTER_HTTP_451	No	Stop processing the person or address; do not work around the privacy request.
HUNTER_HTTP_5xx	Yes	Retry after Hunter recovers.
HUNTER_VERIFICATION_UNAVAILABLE	Yes	Retry later; the remote mail server prevented verification.
RESPONSE_TOO_LARGE	No	Narrow the page or filters; responses are capped at 5 MiB.
INVALID_PROVIDER_RESPONSE / EXECUTION_ERROR	No	Inspect provider compatibility without treating the run as successful.
NETWORK_ERROR	Yes	Restore DNS, TLS, or Hunter connectivity and retry.

Error bodies are capped and sanitized. Credential-shaped provider fields are removed, exact API-key occurrences are replaced, and secret-like text is passed through the shared sensitive-data policy before output.

Example

Find approved technical decision-makers for one target account:

{
  "operation": "domain_search",
  "domain": "example.com",
  "department": "it",
  "seniority": "executive",
  "decisionMaker": true,
  "limit": 25,
  "offset": 0
}

Expected normalized result:

{
  "status": "success",
  "operation": "domain_search",
  "data": {
    "domain": "example.com",
    "organization": "Example"
  },
  "items": [
    {
      "value": "ada@example.com",
      "type": "personal",
      "confidence": 97,
      "position": "CTO"
    }
  ],
  "count": 1,
  "total": 1,
  "hasMore": false,
  "httpStatus": 200,
  "attempts": 1
}

Downstream workflows should review confidence, verification status, legal basis, suppression rules, and outreach consent before sending any message.

Notes

• Pagination: domain_search exposes exactly one Hunter offset page per execution. Continue only with the returned nextOffset; the connector does not hide multiple credit-consuming requests inside one run.
• Rate limits: Hunter currently documents 15 requests per second and 500 per minute for Domain Search and Email Finder, and 10 per second and 300 per minute for Email Verifier. Plan credits and endpoint access are separate limits.
• API limits: domain pages are capped at 100 results and provider sources are currently capped at 20 per email. ValkyrAI additionally caps the response body at 5 MiB and local offset at 10,000.
• Idempotency: all operations are read-only, but many can consume provider credits. Repeating identical calls can still have billing or quota effects.
• Destructive behavior: none. The module does not create leads, campaigns, sequences, tags, webhooks, or send email.
• Privacy: HTTP 451 is a durable stop signal. Do not retry it, substitute another provider to evade it, or retain disallowed personal data.
• Output handling: enrichment is classified restricted; do not place results in public logs, public ContentData, or unprotected workflow state.
• External verification: deterministic local tests cover request paths, credential placement/redaction, validation, pagination, retry behavior, verifier 202/222, response bounds, identity checks, and metadata discovery. Live Hunter roles, plan access, credits, data accuracy, SMTP behavior, and billing require separately authorized credentials and are not exercised in repository tests.
• Functional references: n8n Hunter integration and Hunter API v2.