Referencia de la API de verificación de correo

Autenticación

POST /v1/email/validate acepta una clave publicable restringida por origen mediante la cabecera X-Api-Key: el mismo tipo de clave y el mismo modelo de orígenes permitidos que GET /v1/geo. Todos los demás endpoints de esta página (lotes, trabajos de lista, verificación de registro) aceptan muchas direcciones o una IP arbitraria, por lo que requieren tu clave secreta mediante Authorization: Bearer y solo deben llamarse desde tu backend; una clave publicable recibe un 403 en ellos.

Ejemplo

curl https://api.watch-ip.com/v1/email/validate \
  -H "X-Api-Key: YOUR_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "John.Doe+news@Gmial.com"}'

{
  "email": "John.Doe+news@Gmial.com",
  "domain": "gmial.com",
  "syntaxValid": true,
  "isDisposable": false,
  "normalizedEmail": "john.doe+news@gmial.com",
  "canonicalEmail": "john.doe@gmial.com",
  "disposableSource": null,
  "isFreeProvider": false,
  "isRoleAccount": false,
  "didYouMean": "john.doe+news@gmail.com",
  "mx": {
    "status": "none",
    "host": null
  },
  "verdict": "reject",
  "reasons": [
    "no_mail_server",
    "typo_suspected"
  ]
}

Veredictos y códigos de motivo

Cada condición fija un veredicto mínimo; gana la más grave, y reasons las enumera todas, de la más grave a la menos grave. Si una dirección de un proveedor gratuito es aceptable lo decides tú: nunca cambia el veredicto.

Verificación por lotes

POST/v1/email/batch

Verifica de 1 a 100 direcciones en una sola solicitud, con las mismas comprobaciones y la misma forma de resultado que POST /v1/email/validate, un resultado por dirección en el orden de entrada. Envía { "emails": [...] }. Las direcciones del mismo dominio comparten una única consulta DNS. Cuenta una solicitud por dirección contra el límite mensual de tu plan; un lote que superaría el límite se rechaza entero con 429 monthly_limit_exceeded. Para el límite de tasa por minuto, la llamada completa cuenta como una sola solicitud. Solo con clave secreta.

curl https://api.watch-ip.com/v1/email/batch \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user@gmail.com", "someone@mailinator.com"]}'

{
  "results": [
    { "email": "user@gmail.com", "verdict": "accept", "reasons": [], ... },
    { "email": "someone@mailinator.com", "isDisposable": true, "disposableSource": "list", "verdict": "reject", "reasons": ["disposable_domain"], ... }
  ]
}

Trabajos de lista de correo

POST/v1/email/jobs

Verifica hasta 100.000 direcciones en segundo plano. Envía JSON { "emails": [...], "filename": "..." } o un cuerpo text/csv de 10 MB como máximo: se usa la columna titulada email (también e-mail, email address, email_address o mail, sin distinguir mayúsculas), o la primera columna si ninguna cabecera la nombra; se detectan los separadores coma, punto y coma y tabulación. El trabajo se cobra al crearse (una solicitud por dirección distinta, coincidencia exacta, así que los duplicados se verifican pero se cobran una vez) y una lista que superaría tu límite mensual se rechaza entera. Si parte de un trabajo no se puede procesar tras varios reintentos, el trabajo se marca como failed y se devuelven los créditos de la parte no procesada. Responde 202 con el objeto del trabajo. Solo con clave secreta; los mismos trabajos también se pueden subir y descargar desde la página Email lists del panel.

curl https://api.watch-ip.com/v1/email/jobs \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @newsletter.csv

{
  "id": "5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11",
  "status": "queued",
  "source": "api",
  "filename": null,
  "total": 12840,
  "credits": 12512,
  "processed": 0,
  "summary": null,
  "createdAt": "2026-09-28T10:00:00.000Z",
  "completedAt": null,
  "expiresAt": "2026-10-05T10:00:00.000Z"
}

Estado del trabajo

GET/v1/email/jobs/{id}

Devuelve el mismo objeto del trabajo. Consúltalo periódicamente hasta que status sea completed; las consultas no se cobran.

Resultados del trabajo

GET/v1/email/jobs/{id}/results

Descarga un CSV con una fila por cada fila enviada, en el orden de envío, duplicados incluidos. Columnas: email, normalized_email, verdict, reasons, syntax_valid, is_disposable, disposable_source, is_free_provider, is_role_account, did_you_mean, mx_status, mx_host. reasons va separado por punto y coma, las celdas vacías significan null y mx_status está vacío para las direcciones sintácticamente no válidas (no se consultó nada). Una dirección no válida que empieza por =, +, - o @ lleva delante un apóstrofo para que las hojas de cálculo no la ejecuten como fórmula. 409 hasta que el trabajo termine, 410 cuando haya caducado. La descarga no se cobra.

curl https://api.watch-ip.com/v1/email/jobs/5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11/results \
  -H "Authorization: Bearer YOUR_SECRET_KEY" -o results.csv

Verificación de registro

POST/v1/signup/check

Puntúa un registro a partir de su dirección de correo y su IP en una sola llamada, desde tu backend cuando se envía el formulario de registro (un veredicto calculado en el navegador se puede falsificar). Envía { "email": "...", "ip": "...", "userAgent": "..." }; userAgent es opcional. La respuesta contiene el resultado completo de la verificación de correo (email), el país y el ASN de la IP y, en los planes que incluyen datos de seguridad, sus indicadores de VPN/Tor/centro de datos/amenaza (ip), la antigüedad del dominio del correo en días según los datos públicos de registro (RDAP) (emailDomainAgeDays, null cuando se desconoce y para los grandes proveedores de consumo), una puntuación de 0 a 100 (la suma de los pesos de los motivos siguientes, con un máximo de 100) y un veredicto: reject a partir de 60, review a partir de 25 y, en otro caso, accept. En un plan sin datos de seguridad, ip.security es null, la puntuación usa solo las señales del correo y reasons incluye ip_security_unavailable. Cuenta como una solicitud. Solo con clave secreta.

curl https://api.watch-ip.com/v1/signup/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@new-startup.io", "ip": "203.0.113.1"}'

{
  "email": { "email": "jane@new-startup.io", "verdict": "accept", "reasons": [], ... },
  "ip": {
    "ip": "203.0.113.1",
    "country": "US",
    "asn": 64500,
    "asOrganization": "Example Hosting",
    "security": { "isTor": false, "isVpn": false, "isDatacenter": true, "isThreat": false, "isSanctionedNetwork": false }
  },
  "emailDomainAgeDays": 12,
  "score": 45,
  "verdict": "review",
  "reasons": ["new_domain", "ip_datacenter"]
}

Límites

Cada dirección verificada cuenta como una solicitud contra el límite mensual compartido de tu plan (una verificación individual, cada dirección de un lote, cada dirección distinta de un trabajo de lista) y una verificación de registro es una solicitud. Los lotes y los trabajos de lista se admiten o se rechazan enteros, nunca se atienden parcialmente. El límite de tasa por minuto cuenta llamadas HTTP, no elementos: un lote de hasta 100 IP o direcciones de correo cuenta como una sola solicitud, mientras que cada elemento sigue contando por separado en el límite mensual de solicitudes. Las subidas y los resultados de los trabajos de lista se eliminan 7 días después de crear el trabajo. Las consultas DNS tienen un margen de tiempo corto: cuando una falla o agota el tiempo, el resultado se degrada a mx.status unknown y motivo dns_unavailable en lugar de un error. Los datos de dominios desechables se combinan a partir de tres listas de código abierto mantenidas por la comunidad, se actualizan cada pocas horas y se amplían con los servidores de correo observados atendiendo dominios de las listas; consulta fuentes de datos. Es posible que un proveedor desechable muy reciente aún no se marque. Todas las comprobaciones son a nivel de dominio y de dirección: no se contacta ningún buzón, así que ningún resultado establece que un buzón exista, quién es su titular ni que el correo vaya a llegar.