# AI agents

URL: https://email-validation.org/docs/ai-agents/
Updated: 2026-10-21

> Documentation index: https://email-validation.org/llms.txt

AI agents validate addresses with the same API key, credits, limits and results as the REST API, over the
protocol they speak: MCP, A2A or plain HTTP. `unknown` results and errors are free.

## Credentials

A person creates an API key in the dashboard and gives it to the agent, which sends it on every call as
`Authorization: Bearer <key>`. There is no OAuth flow and no self-registration for agents. The steps are written
for agents in [auth.md](https://email-validation.org/auth.md); key scopes, caps and rolling are on [Authentication](https://email-validation.org/docs/authentication/).

## Pick a protocol

| Agent | Endpoint | Description |
|---|---|---|
| MCP client | `https://api.email-validation.org/mcp` | [MCP server](https://email-validation.org/docs/mcp/) with `validate_email`, `get_credits` and the bulk tools |
| A2A agent | `https://api.email-validation.org/a2a` | [A2A endpoint](#a2a) with the skills `validate_email` and `get_credits` |
| Any HTTP client | `https://api.email-validation.org/v1/…` | [REST API](https://email-validation.org/docs/api-reference/) described by [OpenAPI](https://api.email-validation.org/openapi.json) |
| Coding agent | [SKILL.md](https://email-validation.org/.well-known/agent-skills/email-validation/SKILL.md) | [Agent Skill](#agent-skills) that explains the API to the agent |
| Agent in the browser | [Free email checker](https://email-validation.org/email-checker/) | [WebMCP tool](#webmcp) `check_email` |

## A2A

The A2A endpoint speaks the Agent2Agent protocol 1.0 (JSON-RPC binding). Send the header `A2A-Version: 1.0`;
requests without the header are answered in the A2A 0.3 format (`message/send`, `tasks/get`).

- **Endpoint:** `https://api.email-validation.org/a2a` (`POST`, `Content-Type: application/json`)
- **Agent card:** [https://api.email-validation.org/.well-known/agent-card.json](https://api.email-validation.org/.well-known/agent-card.json), also at
  [https://email-validation.org/.well-known/agent-card.json](https://email-validation.org/.well-known/agent-card.json)
- **Authentication:** `Authorization: Bearer <your API key>`
- **Skills:** `validate_email` (one address per message, in a text part or in a data part `{"email": …}`, with
  optional `ip_address` and `timeout` of 5–15 seconds) and `get_credits` (ask in
  text, or send the metadata `{"skill": "get_credits"}`)

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "9f0c2c4e-1",
      "role": "ROLE_USER",
      "parts": [{ "data": { "email": "accepted@sandbox.email-validation.org" }, "mediaType": "application/json" }]
    }
  }
}
```

The answer is a completed task. Its artifact holds the [validation result](https://email-validation.org/docs/api/validate/#response) as a data
part and a one-line summary as a text part:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "task": {
      "id": "…",
      "contextId": "…",
      "status": { "state": "TASK_STATE_COMPLETED", "timestamp": "2026-11-02T09:52:08.000Z" },
      "artifacts": [{
        "artifactId": "…",
        "name": "validation-result",
        "parts": [
          { "data": { "email": "accepted@sandbox.email-validation.org", "status": "deliverable", "action": "send", "…": "…" },
            "mediaType": "application/json" },
          { "text": "accepted@sandbox.email-validation.org is deliverable …", "mediaType": "text/plain" }
        ]
      }]
    }
  }
}
```

A validation uses exactly the credits and limits of `POST /v1/validate`. Tasks finish inside the request (at most
15 seconds) and are not stored, so `GetTask` and `CancelTask` answer "task not found" and `ListTasks`
returns an empty list. Streaming, push notifications and the extended agent card are not offered.

### Errors

| Situation | Answer |
|---|---|
| Missing, mistyped or revoked key | HTTP `401` with the [error envelope](https://email-validation.org/docs/errors/) |
| Too many requests, or checks paused | HTTP `429` or `503` with `Retry-After`, like the REST API |
| No credits, daily key cap, missing scope or origin | Task in `TASK_STATE_REJECTED`; its status message carries the error code |
| Unexpected failure | Task in `TASK_STATE_FAILED`, same message shape; nothing is charged |
| Malformed request, no address or several addresses | JSON-RPC error `-32602` (invalid parameters) |
| File parts, or no acceptable output type | JSON-RPC error `-32005` (content type not supported) |
| Unknown task, streaming or push notifications | JSON-RPC errors `-32001`, `-32004` and `-32003` |
| Unsupported `A2A-Version` | JSON-RPC error `-32009` |

## Agent Skill

The [Agent Skills index](https://email-validation.org/.well-known/agent-skills/index.json) lists one skill, `email-validation`. Its
[SKILL.md](https://email-validation.org/.well-known/agent-skills/email-validation/SKILL.md) tells a coding agent how to validate
addresses with the REST API, MCP or A2A, how to read the statuses and actions, and how to handle credits and errors.
The index carries the SHA-256 digest of the file, so agents can check what they load.

## WebMCP on the free checker

The checker on the [home page](https://email-validation.org/) and on [/email-checker/](https://email-validation.org/email-checker/) is a WebMCP tool named `check_email`
for agents that run in the visitor's browser. The form is annotated for the declarative API, and browsers with
`document.modelContext` also get the tool through `registerTool`. Either way the agent fills in and submits the same
form, so the bot check and the limit of 5 free checks a day apply. Agents that check more
addresses should use the API with a key.

## Discovery files

| File | What it is |
|---|---|
| [/.well-known/ard.json](https://email-validation.org/.well-known/ard.json) | Agentic Resource Discovery manifest: the MCP server, the A2A agent, the OpenAPI document, the Agent Skills index and llms.txt. The same file is at [/.well-known/ai-catalog.json](https://email-validation.org/.well-known/ai-catalog.json), linked from every page with `rel="ard"` and `rel="ai-catalog"`. |
| [/.well-known/mcp/server-card.json](https://email-validation.org/.well-known/mcp/server-card.json) | MCP server card |
| [/.well-known/agent-card.json](https://api.email-validation.org/.well-known/agent-card.json) | A2A agent card (on both hosts) |
| [/.well-known/api-catalog](https://email-validation.org/.well-known/api-catalog) | RFC 9727 API catalog: the REST API, the MCP server and the A2A endpoint |
| [/llms.txt](https://email-validation.org/llms.txt) | Index of the docs and policies for language models |
| [/auth.md](https://email-validation.org/auth.md) | How an agent gets and sends its API key |