Validación por Lotes

Autenticación

Incluya su clave de API en el encabezado X-API-Key:

X-API-Key: ml_pv_Ab3Kx9mN2pQ7rT4wL8yD...

La credencial debe ser una credencial de producto Validation con el canal Api habilitado.

Validar un Lote

POST https://api.mail.land/v1/validation/batch

Solicitud de validación por lotes

{
  "emails": [
    "[email protected]",
    "[email protected]",
    "invalid@",
    "[email protected]",
    "[email protected]"
  ],
  "verify_smtp": true
}

Campo	Tipo	Predeterminado	Descripción
`emails`	array	-	Direcciones de correo electrónico a validar (obligatorio, máx. 100)
`verify_smtp`	bool	true	Realizar verificación SMTP del buzón

Batch validate

curl -X POST https://api.mail.land/v1/validation/batch \
  -H "X-API-Key: ml_pv_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["[email protected]", "[email protected]", "[email protected]"],
    "verify_smtp": true
  }'

Respuesta

Respuesta de validación por lotes

{
  "total_count": 5,
  "processed_count": 5,
  "successful_count": 5,
  "credits_consumed": 4,
  "free_validations": 1,
  "results": [
    {
      "email": "[email protected]",
      "result": "Deliverable",
      "score": 95,
      "syntax": { "is_valid": true, "has_typo": false },
      "disposable": { "is_disposable": false },
      "role": { "is_role_account": false },
      "mx": { "has_mx": true, "records": ["mx.example.com"], "accepts_mail": true },
      "smtp": { "can_connect": true, "is_deliverable": true, "is_catch_all": false, "reachability": "safe" },
      "provider": { "name": "Unknown", "type": "unknown" },
      "cached": false,
      "verified_at": "2026-02-17T12:34:56Z"
    },
    {
      "email": "[email protected]",
      "result": "Deliverable",
      "score": 95,
      "syntax": { "is_valid": true, "has_typo": false },
      "disposable": { "is_disposable": false },
      "role": { "is_role_account": false },
      "mx": { "has_mx": true, "records": ["gmail-smtp-in.l.google.com"], "accepts_mail": true },
      "smtp": { "can_connect": true, "is_deliverable": true, "is_catch_all": false, "reachability": "safe" },
      "provider": { "name": "Gmail", "type": "consumer" },
      "cached": false,
      "verified_at": "2026-02-17T12:34:56Z"
    },
    {
      "email": "invalid@",
      "result": "Undeliverable",
      "score": 0,
      "syntax": { "is_valid": false, "has_typo": false },
      "disposable": { "is_disposable": false },
      "role": { "is_role_account": false },
      "mx": { "has_mx": false, "records": [], "accepts_mail": false },
      "smtp": null,
      "provider": { "name": "Unknown", "type": "unknown" },
      "cached": false,
      "verified_at": "2026-02-17T12:34:56Z"
    },
    {
      "email": "[email protected]",
      "result": "Undeliverable",
      "score": 10,
      "syntax": { "is_valid": true, "has_typo": false },
      "disposable": { "is_disposable": true },
      "role": { "is_role_account": false },
      "mx": { "has_mx": true, "records": ["mx.tempmail.org"], "accepts_mail": true },
      "smtp": null,
      "provider": { "name": "Unknown", "type": "unknown" },
      "cached": false,
      "verified_at": "2026-02-17T12:34:56Z"
    },
    {
      "email": "[email protected]",
      "result": "Deliverable",
      "score": 85,
      "syntax": { "is_valid": true, "has_typo": false },
      "disposable": { "is_disposable": false },
      "role": { "is_role_account": true },
      "mx": { "has_mx": true, "records": ["mx.company.com"], "accepts_mail": true },
      "smtp": { "can_connect": true, "is_deliverable": true, "is_catch_all": false, "reachability": "safe" },
      "provider": { "name": "Unknown", "type": "unknown" },
      "cached": false,
      "verified_at": "2026-02-17T12:34:56Z"
    }
  ]
}

Campos de Respuesta

Campo	Tipo	Descripción
`total_count`	int	Direcciones únicas en la solicitud. Los duplicados exactos (sensibles a mayúsculas) se deduplican antes de procesarse y se validan una sola vez, por lo que este número puede ser menor que la cantidad de correos enviados.
`processed_count`	int	Correos electrónicos que fueron procesados
`successful_count`	int	Validaciones que se completaron sin errores
`credits_consumed`	int	Créditos deducidos (validaciones de pago)
`free_validations`	int	Validaciones gratuitas (desechables, errores tipográficos, errores SMTP)
`results`	array	Una entrada por dirección única, en el orden de primera aparición. Relacione los resultados con su entrada por el campo `email`, no por posición: los duplicados de su solicitud no tendrán una entrada correspondiente.

Cada elemento en results tiene la misma estructura que una respuesta de validación individual.

Consumo de Créditos

Los créditos se verifican antes de procesar el lote. Si no tiene suficientes créditos para el lote completo, la solicitud se rechaza con 402.

Dentro del lote, las validaciones gratuitas se aplican según las mismas reglas que la validación individual:

Dominios desechables: gratuita
Errores tipográficos de alta confianza (90%+), gratuita
Errores de conexión SMTP: gratuita

La respuesta muestra el desglose exacto: credits_consumed (facturados) + free_validations (no facturados) = processed_count.

Las validaciones por lotes ejecutan hasta 10 correos electrónicos de forma concurrente dentro de una sola solicitud. Esto equilibra el rendimiento con los límites de velocidad del servidor SMTP. Los resultados se devuelven en el mismo orden que el arreglo de entrada, independientemente del orden de procesamiento.

Para listas de más de 100 correos electrónicos, divídalas en múltiples solicitudes por lotes. El límite de concurrencia se aplica por solicitud: puede ejecutar múltiples solicitudes por lotes en paralelo desde su servidor.

Historial de Validación

Todas las validaciones (individuales y por lotes) se registran en su historial de validación:

GET https://api.mail.land/v1/validation/history

Parámetro	Tipo	Predeterminado	Descripción
`cursor`	string	-	Cursor opaco del `nextCursor` de la página anterior. Omitir para la primera página.
`limit`	int	20	Elementos por página (máx. 100)
`result`	string	-	Filtro: `Deliverable`, `Risky`, `Unknown`, `Undeliverable`, `Invalid`
`from`	datetime	-	Fecha de inicio
`to`	datetime	-	Fecha de fin
`search`	string	-	Buscar por dirección de correo electrónico

Respuesta del historial de validación

{
  "items": [
    {
      "email": "u***@example.com",
      "result": "Deliverable",
      "score": 95,
      "is_disposable": false,
      "is_role_account": false,
      "has_valid_mx": true,
      "smtp_deliverable": true,
      "provider": "Unknown",
      "was_cached": false,
      "smtp_verified": true,
      "credit_consumed": true,
      "verified_at": "2026-02-17T12:34:56Z"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoidmFsaWRhdGlvbjp2ZXJpZmllZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Las direcciones de correo electrónico en el historial están parcialmente enmascaradas por privacidad (por ejemplo, u***@example.com).

Estadísticas de Validación

Obtenga estadísticas agregadas de su uso de validación:

GET https://api.mail.land/v1/validation/stats

Parámetro	Tipo	Predeterminado	Descripción
`from`	datetime	-	Fecha de inicio
`to`	datetime	-	Fecha de fin

Respuesta de estadísticas de validación

{
  "total_validations": 450,
  "deliverable": 320,
  "risky": 65,
  "undeliverable": 50,
  "unknown": 15,
  "deliverable_rate": 71.11,
  "risky_rate": 14.44,
  "undeliverable_rate": 11.11,
  "unknown_rate": 3.33,
  "credits_consumed": 380,
  "free_validations": 70
}

Límites

Límite	Valor
Máx. correos electrónicos por lote	100
Validaciones concurrentes por lote	10
Tiempo de espera SMTP por correo electrónico	30 segundos
Longitud máxima del correo electrónico	320 caracteres

Respuestas de Error

Estado	Código	Descripción
`400`	`INVALID_REQUEST`	Se requiere al menos un correo electrónico
`400`	`CONTENT_TOO_LARGE`	El lote excede los 100 correos electrónicos
`402`	`INSUFFICIENT_CREDITS`	No hay suficientes créditos para el lote

Mejores Prácticas

Valide antes de importar: ejecute la validación por lotes en nuevas listas de suscriptores antes de importarlas para evitar picos de rebotes.
Filtre por resultado: solo importe correos electrónicos Deliverable. Trate los correos Risky con precaución y evite los Undeliverable por completo.
Verifique las sugerencias de errores tipográficos: cuando syntax.has_typo es true, presente la syntax.suggestion al usuario para confirmación antes de enviar.
Use durante el registro: valide correos electrónicos en su flujo de registro con validación individual para evitar que direcciones incorrectas ingresen a su sistema.
Monitoree el uso de créditos: consulte /validation/credits para rastrear el consumo y planificar actualizaciones antes de alcanzar el límite de su cuota.

Próximos Pasos

Validación de Correo Individual: validación en tiempo real para direcciones individuales
Supresiones: administre listas de supresión
Calentamiento de IP: caliente dominios con listas limpias y validadas

Validación por Lotes

Autenticación

Validar un Lote

Respuesta

Campos de Respuesta

Consumo de Créditos

Concurrencia

Historial de Validación

Estadísticas de Validación

Límites

Respuestas de Error

Mejores Prácticas

Próximos Pasos

En esta página

Validación por Lotes

AutenticaciónCopiar enlace de la sección

Validar un LoteCopiar enlace de la sección

RespuestaCopiar enlace de la sección

Campos de RespuestaCopiar enlace de la sección

Consumo de CréditosCopiar enlace de la sección

ConcurrenciaCopiar enlace de la sección

Historial de ValidaciónCopiar enlace de la sección

Estadísticas de ValidaciónCopiar enlace de la sección

LímitesCopiar enlace de la sección

Respuestas de ErrorCopiar enlace de la sección

Mejores PrácticasCopiar enlace de la sección

Próximos PasosCopiar enlace de la sección

En esta página

Autenticación

Validar un Lote

Respuesta

Campos de Respuesta

Consumo de Créditos

Concurrencia

Historial de Validación

Estadísticas de Validación

Límites

Respuestas de Error

Mejores Prácticas

Próximos Pasos