Verificación en tiempo real de correo

POST/v1/realtime/check/email

Verifica de forma síncrona una dirección de correo contra entre uno y diez productos de correo en tiempo real. El motor, el contrato de facturación y la forma de la respuesta son idénticos a los del endpoint de teléfono; solo difieren la serie y el formato del identificador.

Parámetros

Campo	Tipo	Requerido	Descripción
identifier	string	Sí	Una dirección de correo, por ejemplo user@example.com.
country	string	No	Debe omitirse para correo. Enviar un código de país con un producto de correo se rechaza.
product_ids	array<int>	Sí	Un arreglo de 1 a 10 IDs de producto de correo en tiempo real.

El país debe ir vacío

El correo no tiene dimensión de país. country es opcional en el endpoint de teléfono, pero aquí no se acepta — una solicitud que lo incluya falla la validación antes de que se envíe o se cobre algo.

Idempotencia obligatoria

Idempotency-Key es obligatorio en cada llamada. Reintentar la misma solicitud con la misma clave no cobra dos veces; cambiar el payload devuelve 409. Consulta Idempotencia y reintentos.

Elegir los productos

Los productos de correo y de teléfono son series diferentes y no se pueden combinar en una solicitud. Lee el id de una entrada cuyo mode sea realtime y cuya serie sea correo en Productos en tiempo real, que se alimenta de GET /v1/products. Pasar un slug nunca funciona aquí, y un ID de producto de teléfono en una llamada de correo se rechaza como una serie no coincidente.

Ejemplo de respuesta

{
  "request_id": "b7d2a1c4-9f3e-4a1b-8c5d-2e6f7a8b9c0d",
  "identifier": "user@example.com",
  "series": "email",
  "status": "succeeded",
  "request_status": "completed",
  "replayed": false,
  "total_reserved": 0.004000,
  "total_charged": 0.004000,
  "total_refunded": 0.000000,
  "results": [
    {
      "product_id": 49,
      "product": "insemailvalid-rt",
      "result": "valid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.002000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-13T10:00:00Z",
      "error_code": null
    }
  ]
}

Los valores de product_id anteriores son ejemplos — confirma los IDs actuales de productos de correo en Productos en tiempo real antes de enviar una solicitud real. request_id es un UUID, y cached vive dentro de cada resultado, no en el nivel superior.

Ejemplo de cURL

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/email" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"user@example.com","product_ids":[49]}'

Errores específicos del correo

HTTP	code	Significado
400	invalid_realtime_request	La dirección está mal formada, se envió country, los IDs pertenecen a otra serie o no se proporcionó ningún ID. No se envía nada ni se cobra nada.
400	idempotency_key_required	Falta el encabezado Idempotency-Key.
402	insufficient_balance	El saldo no cubre la reserva; ninguna entrada comienza.
409	request_in_progress / idempotency_conflict	Misma clave, aún en ejecución, o misma clave con un payload diferente.

Los códigos de estado restantes — 401, 403, 429, 503, 500 — se comportan exactamente como se documenta en el endpoint de teléfono.