Validate your AI agent's contact list in 5 lines
Your agent scraped, enriched, or imported a contact list. Before it sends a single message, every record should pass a validation gate: syntax, disposable domains, role accounts, typos, canonical form. Here is the whole loop — five lines of TypeScript, a free API key (250 records/month), no crypto wallet.
The five lines, What each verdict contains, Why deterministic validation instead of asking the LLM
The five lines
Install the SDK with npm i @hermesplant/agent-services, create the client with your free key, and hand it the list: const results = await hermes.emailGuardBatch(contacts.map((c) => ({ email: c.email }))). Then keep the good rows with results.filter((r) => r.ok). The batch helper preserves input order, bounds concurrency, and captures per-record errors instead of throwing — the exact snippet is in the API quickstart linked below.
What each verdict contains
Every record gets one deterministic verdict: valid, a deliverability score, a risk level, the normalized canonical form (plus-aliases stripped, case folded), and a classification — disposable or temporary domain, role-based address, free provider, and a typo suggestion when the domain is one edit from a major provider (gnail.com becomes gmail.com). A checks array carries per-rule evidence, so your agent can log WHY a record was flagged, not just that it was.
Why deterministic validation instead of asking the LLM
An LLM asked to judge an email list gives different answers on different runs and invents reasons. This endpoint is a pure function: the same record returns the same verdict every run, with rule-level evidence — which is what makes it safe to wire into an unattended loop. It also costs $0.02 per record at the pay-per-call ceiling, less than the tokens a judgment prompt burns.
Run it without the SDK
The loop is one curl per record from any language: POST the record to /api/agent-services/emailguard/validate with your X-API-Key header. MCP clients (Claude Desktop, Cursor, agent frameworks) get the same loop as a single tool call — emailguard_validate_batch validates up to 20 records per call from the same free quota.
Costs, limits, and scaling up
The free key covers 250 records a month across every endpoint. Past that, the $29 Agent API Pass covers 5,000 calls a month, or your agent can pay per record over x402 ($0.02 in USDC on Base) with no key at all. When a batch hits the quota it stops sending and marks the remaining records skipped, so you can upgrade and resume exactly where it stopped.
FAQ
Does EmailGuard do live DNS or SMTP checks?
No — it is deliberately network-free and deterministic: RFC 5322 syntax, a bundled disposable-domain corpus, role and free-provider classification, and typo distance. If your agent already resolved MX records it can pass mxPresent as a hint. No mailbox is ever pinged.
How do I validate more than 250 contacts a month?
Upgrade to the $29 Agent API Pass (5,000 calls a month, self-serve) or let your agent pay per record over x402 — an unpaid call returns HTTP 402, the agent settles $0.02 USDC on Base and retries.
Can my agent use this with zero signup?
Yes. Every endpoint is x402-metered: the first unpaid call returns a 402 challenge, and any x402-compatible client can settle it per call without an account. The free key just makes the first 250 calls each month simpler.