AI agents

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; key scopes, caps and rolling are on Authentication.

Pick a protocol

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, also at 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"})

{
  "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 as a data part and a one-line summary as a text part:

{
  "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

Agent Skill

The Agent Skills index lists one skill, email-validation. Its 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 and on /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