Email Validation API

Valida un email de forma estructurada y tri-estado (VALID / INVALID / UNKNOWN). El pipeline es fail-fast (se detiene apenas un resultado es concluyente) y cache-first (reutiliza la infraestructura de dominio ya verificada).

Un error técnico o transitorio nunca marca un email como INVALID: se reporta como UNKNOWN.

• Endpoint: POST /api/v1/utils/email/validate
• Autenticación: API Key ilk_ — igual que el resto de la API (Autenticación)
• Scope requerido: utils:email:validate
• Facturación: 1 request ejecutado (Límites y facturación)

POSTProbar la validación de email→

Request

{
  "email": "persona@empresa.com.ar",
  "identity": {
    "type": "CUIT",
    "value": "20123456789"
  }
}

Campo	Tipo	Requerido	Descripción
email	string	sí	Email a validar (3–320). La sintaxis la dictamina el servicio.
identity	object	no	Identidad de contexto. No se usa para consultar datos de la persona en esta versión; se guarda sólo como contexto de la consulta.
identity.type	enum	—	CUIT · CUIL · DNI · PASSPORT · OTHER
identity.value	string	—	Valor del identificador.

Un email mal formado no es un error de protocolo: devuelve 200 con status: INVALID_SYNTAX. Sólo un sobre mal formado (falta email, JSON inválido) devuelve 400.

Response

{
  "requestId": "capi_9f2a7c1e4b0d8a6f",
  "email": "persona@empresa.com.ar",
  "valid": true,
  "result": "VALID",
  "status": "DELIVERABLE",
  "score": 92,
  "suggestedEmail": null,
  "attributes": {
    "freeEmail": false,
    "disposableEmail": false,
    "roleEmail": false,
    "catchAllEmail": false
  },
  "checks": {
    "syntax": { "status": "PASS" },
    "domain": { "status": "PASS" },
    "dns": { "status": "PASS", "cacheHit": true },
    "mx": { "status": "PASS", "cacheHit": true },
    "smtpInfrastructure": { "status": "UNKNOWN", "cacheHit": false },
    "mailbox": { "status": "PASS", "cacheHit": false }
  },
  "stoppedAt": null
}

Campo	Descripción
requestId	Identificador de la ejecución.
email	El email recibido (se conserva; nunca se auto-corrige).
valid	true sólo si result es VALID.
result	Veredicto tri-estado: VALID / INVALID / UNKNOWN.
status	Estado detallado (ver Estados).
score	Puntuación normalizada de calidad/confianza entre 0 y 100 (o null).
suggestedEmail	Corrección sugerida (p.ej. typo de dominio), o null. Nunca reemplaza el email original.
attributes	Atributos del email (null si no se determinaron).
checks	Resultado por etapa (PASS / FAIL / UNKNOWN, con cacheHit opcional).
stoppedAt	Etapa donde se detuvo (fail-fast) o la última evaluada; null si completó.

Pipeline

Sintaxis → Dominio → DNS → MX → Infraestructura SMTP → Mailbox

• Sintaxis / Dominio — estructura del email y normalización IDN del dominio.
• DNS — existencia real del dominio. La ausencia de registros A/AAAA no implica que el dominio no exista.
• MX — destino de correo. Soporta Null MX (el dominio declara que no recibe correo → inválido) e implicit MX (sin MX pero con A/AAAA → válido).
• Infraestructura SMTP — comprobación no intrusiva de conectividad al servidor de correo. Es informativa: si no se puede alcanzar (frecuente en muchas redes), el resultado es UNKNOWN y no invalida el email.
• Mailbox — verificación de la casilla (cuando está habilitada).

Estados

status	result	Significado
VALID	VALID	Email válido a nivel infraestructura.
DELIVERABLE	VALID	Casilla entregable.
INVALID_SYNTAX	INVALID	Estructura del email inválida.
DOMAIN_NOT_FOUND	INVALID	El dominio no existe (NXDOMAIN).
NULL_MX	INVALID	El dominio declara que no recibe correo.
NO_MAIL_EXCHANGER	INVALID	El dominio no tiene ningún destino de correo.
MAILBOX_UNDELIVERABLE	INVALID	La casilla no existe / no es entregable.
DNS_ERROR	UNKNOWN	Error DNS transitorio.
SMTP_UNREACHABLE	UNKNOWN	No se pudo alcanzar la infraestructura SMTP.
MAILBOX_UNKNOWN	UNKNOWN	La casilla no pudo determinarse.
TEMPORARY_ERROR	UNKNOWN	Error transitorio.
PROVIDER_*	UNKNOWN	Error técnico del verificador de mailbox (reintentar).

Códigos HTTP

Los mismos de toda la API (ver Errores); acá, qué los dispara:

Código	Caso
200	Validación ejecutada (incluye INVALID_* y UNKNOWN).
400	Sobre inválido (falta email o JSON inválido).
401	API Key ausente o inválida.
403	Scope utils:email:validate ausente.
429	Rate-limit (con retryAfterMs) o cuota diaria agotada.

Un email mal formado no es un error

400 es para el sobre; un email inválido es un resultado 200 con status: INVALID_SYNTAX. La API distingue "no pude ejecutar" de "ejecuté y el veredicto es negativo".

Límites y facturación

Rige el modelo común: rate-limit por minuto y cuota por período, ambos por API Key. La unidad facturable es 1 request ejecutado; los rechazos previos a la ejecución (validación, autenticación, autorización, rate-limit, cuota) no facturan.

Playground

Probá la API en vivo desde el API Reference + Playground (elegí Email Validation en el selector de documentos). Pegá tu propia API Key en el playground: nunca se publica ni se comparte.

Todos los ejemplos usan datos sintéticos; ningún email es real.