---
title: "Agent quickstart"
description: "Choose the service, obtain a key, submit a check and handle results."
url: https://agentsverify.dev/agents
markdown_url: https://agentsverify.dev/agents.md
---

For agents and their developers

# A clear path from _address to evidence._

Connect an agent to email verification with an API key and a few HTTP requests. Start here, then use the complete integration examples.

## When to use AgentsVerify

Check email addresses before a campaign, a CRM import or a workflow that needs recipient evidence. The service performs syntax, DNS, MX, SMTP recipient and catch-all checks, then saves a structured result. It never sends a message to the address being verified and does not provide inboxes.

## 1\. Set up your workspace

Sign in to the [dashboard](https://app.agentsverify.dev/dashboard), complete your profile to claim 500 free credits, and copy your automatically created key under [API key](https://app.agentsverify.dev/dashboard/api-keys). No card is required for the free credits. Account setup uses the dashboard.

Store the key as `AGENTS_VERIFY_API_KEY` in your server environment. Scripts read that environment variable. The dashboard can also copy instructions with your API key for an agent; use it only for authentication and keep it out of replies, client-side code and logs.

## 2\. Upload one CSV

For one address or a large list, prepare a one-column UTF-8 CSV. An optional first-record header is allowed; every subsequent record must contain an email. The SDK handles length, checksum and resumable transfer automatically. Raw HTTP starts with bodyless `POST /v1/verifications`, UUID `Idempotency-Key` and file-derived `X-Upload-Content-Length`, then PUTs raw bytes to `upload.url` without API credentials. The backend validates the whole file before checks or credits, then handles batching. No completion call is needed.

## 3\. Read saved progress and results

Read `GET /v1/verifications/{id}` for status and actionable issues. Download available final CSV outcomes from `GET /v1/verifications/{id}/results`; partial results appear as checks finish. Keep the Idempotency-Key and verification ID for retries. `GET /v1/verifications` lists saved IDs and current limits. See the [HTTP guide](https://docs.agentsverify.dev/quickstart) and [API reference](https://docs.agentsverify.dev/api-reference.md) for exact schemas.

## 4\. Handle results and errors explicitly

-   **Unknown:** inconclusive evidence; zero credits. Do not treat it as a valid mailbox.
-   **Catch-all:** the domain accepts random recipients; this is a separate result and costs one credit.
-   **Other completed results:** one credit. Follow the returned reason and evidence; SMTP acceptance does not guarantee delivery.
-   **401 / 402:** resolve credentials or credit balance before continuing.
-   **429:** wait for `Retry-After`. The cap is 60 API-key requests per minute per workspace, shared across keys.
-   **503:** verification is temporarily unavailable. Wait for `Retry-After` and submit again; no credit is charged for the rejected request.

A credit is reserved while a check runs; an unknown result refunds it. An eligible fallback does not add a second charge. Request-rate limits do not describe completed-address throughput.

## Quality and recovery

Duplicate identities within a CSV are checked once. A new verification can charge again; reading saved results is free. Eligible temporary SMTP replies may retry once after 75 seconds. The optional 15-minute target retry is disabled. Unknown is inconclusive and free; catch\_all is risky. Saved work recovers automatically after interruptions. Cancel remaining work with `POST /v1/verifications/{id}/cancel`. Completed results are emailed and remain available in the dashboard and API. Verification work is distributed fairly across active workspaces.

## Budget before you buy

Purchase any whole-number quantity from 5,000 to 1,000,000 credits ($5.85–$134.70). Paid credits never expire. No subscription or automatic top-up. Rejected requests and service errors cost no credits.

Use [pricing.md](https://agentsverify.dev/pricing.md) for exact USD-cent calculations, and [pricing](https://agentsverify.dev/pricing.md) for reference prices and purchase terms.

## Read any public page as Markdown

Append `.md` to its path: [/pricing.md](https://agentsverify.dev/pricing.md) or [/compare/millionverifier.md](https://agentsverify.dev/compare/millionverifier.md). The homepage is [/index.md](https://agentsverify.dev/index.md). You can also send `Accept: text/markdown` to the original page URL.

[llms.txt](https://agentsverify.dev/llms.txt) lists the public pages and their Markdown versions.