Verifique direcciones de correo mediante una API REST

Envíe la petición desde su servidor

Cree una credencial en su cuenta y guárdela en su servidor, fuera del código del navegador. La petición del ejemplo envía una dirección y usa la verificación completa, la opción predeterminada. El encabezado Idempotency-Key permite repetir la misma operación si falla la conexión o se duplica el envío. Dentro del plazo de idempotencia, la API devuelve el resultado original sin iniciar otra verificación.

curl -sS https://api.emvero.tech/v1/verifications \
  -H "Authorization: Bearer emv_your_credential" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-8f21c0" \
  -d '{"email":"ada@example.com"}'

El siguiente JSON muestra un ejemplo de respuesta 200. La dirección, el identificador y las pruebas son ficticios; no proceden de una consulta real a example.com:

{
  "id": "5f0b6f3e-1a4c-4a1f-9d2e-8f7b3c2a1d90",
  "email": "ada@example.com",
  "normalized": { "domain": "example.com", "ascii_domain": "example.com" },
  "status": "deliverable",
  "confidence": 0.92,
  "action": "allow",
  "checks": {
    "syntax": "valid",
    "domain": "valid",
    "mail_routing": "valid",
    "smtp": "accepted",
    "accept_all": "no",
    "disposable": false,
    "role_account": false,
    "public_provider": false,
    "smtp_utf8_required": false
  },
  "reason_codes": ["MX_FOUND", "SMTP_RCPT_ACCEPTED"]
}

El código HTTP 200 indica que la petición se ha procesado correctamente, incluso si la dirección es undeliverable. Para conocer el resultado de la verificación, lea el JSON. Los errores HTTP indican problemas con la petición, la credencial, el saldo, los límites de uso o el servicio.

Interprete el estado y la acción recomendada

El campo status resume el resultado en cuatro estados finales: deliverable, risky, undeliverable y unknown. Un resultado desconocido significa que las pruebas disponibles no permiten determinar si la dirección puede recibir correo. Puede deberse, por ejemplo, a un tiempo de espera agotado o a una restricción del servidor.

El campo action indica cómo recomienda Emvero tratar la dirección: allow permite continuar, allow_with_email_confirmation recomienda confirmar el control del buzón cuando sea necesario y reject recomienda rechazarla. Una dirección puede tener el estado risky y la acción allow. Use la recomendación devuelta por la API en lugar de deducirla únicamente del estado.

Para entender qué respalda el resultado, consulte checks, que recoge los resultados de las distintas etapas y las señales de riesgo. reason_codes identifica los motivos con códigos estables como DISPOSABLE_DOMAIN o SMTP_RCPT_ACCEPTED. El campo confidence puntúa la solidez de las pruebas entre 0 y 1; no expresa la probabilidad de que un mensaje llegue a la bandeja de entrada. La página sobre verificación de una dirección explica qué permiten saber la sintaxis, la ruta de correo y el sondeo SMTP.

Consulte el resultado si la verificación sigue pendiente

Una verificación completa puede devolver primero pending si la comprobación del destinatario aún no ha terminado. Ese estado indica que la verificación sigue en curso. No es un quinto resultado final. La respuesta incluye las pruebas ya obtenidas, un id y el intervalo de espera retry_after_ms. Este ejemplo muestra algunos de los campos de una respuesta pendiente:

{
  "id": "5f0b6f3e-1a4c-4a1f-9d2e-8f7b3c2a1d90",
  "status": "pending",
  "retry_after_ms": 2000
}

Espere el intervalo indicado y consulte GET /v1/verifications/{id} con la misma credencial bearer. Si la respuesta sigue pendiente, espere antes de volver a consultar. Cuando termine la verificación, esa consulta devolverá el resultado final. La API no lo envía automáticamente mediante un callback.

Defina un tiempo máximo de espera en su aplicación, especialmente si hay una persona esperando ante un formulario. La guía de resultados pendientes explica cómo consultar el resultado.

Elija qué comprobar y gestione los errores

El campo variant permite elegir hasta dónde llega la verificación. Si lo omite, se usa full, que puede realizar un sondeo SMTP del destinatario. Con "variant":"domain", se comprueban la sintaxis, el DNS y la ruta de correo, sin abrir una sesión SMTP. Ambas opciones usan el mismo endpoint y devuelven los mismos campos.

La comprobación de dominio no permite determinar si existe un buzón concreto. La verificación completa puede obtener pruebas sobre el destinatario, pero también puede devolver unknown si el servidor no responde a tiempo o limita la información disponible.

Si recibe un error HTTP, trate su causa antes de repetir la petición. Un 400 indica que debe corregirla; un 401, que hay un problema con la credencial; y un 402, que faltan créditos. Ante un 429, reduzca el ritmo de las peticiones y respete Retry-After cuando esté presente. Un 5xx indica un problema del servicio y no permite concluir nada sobre la dirección. Si repite la misma operación, conserve la clave de idempotencia. La guía de inicio muestra cómo integrar la API y la referencia de errores detalla los códigos.

Para comprobar direcciones mientras una persona rellena un formulario, consulte la verificación en tiempo real. Si ya tiene una lista, la verificación por lotes se realiza desde su propio sistema, con una petición por dirección. Emvero no ofrece una función para subir archivos CSV ni un endpoint independiente para procesar lotes.