POST /v1/verify

Verifica una dirección de email de forma síncrona.

Una dirección que no pasa las comprobaciones sigue siendo una petición correcta: recibes un200con valid: false + reason. Las respuestas 4xx de abajo son sobre la petición en sí.

POSThttps://api.mailbeam.dev/v1/verify

El endpoint principal de verificación. Devuelve el veredicto, la puntuación de calidad y el desglose por comprobación.

Cuerpo de la petición

Parameters

Name	Type	Required	Description
`email`	string	required	El email que verificar. Formato del RFC 5321, máximo 254 caracteres.
`timeout_ms`	integer	optional (default: 3000)	Tiempo máximo del sondeo SMTP en ms. Rango: 100-5000.
`include_checks`	boolean	optional (default: true)	Incluir el desglose por comprobación en la respuesta.

Esquema de la respuesta

Campos de la respuesta

Name	Type	Required	Description
`valid`	boolean	required	true solo cuando el buzón ha quedado confirmado.
`status`	"deliverable" \| "undeliverable" \| "risky" \| "unknown"	required	El veredicto. 'unknown' significa que no hemos podido averiguarlo, no que la dirección sea mala.
`score`	integer (0-100)	required	Puntuación de calidad. Recomendamos aceptar >= 60.
`disposable`	boolean	required	true si viene de un proveedor temporal conocido.
`catchAll`	boolean	required	true si el dominio acepta todas las direcciones.
`mx`	boolean	required	true si el dominio tiene registros MX válidos y alcanzables.
`reason`	string \| null	required	null cuando es válida. Si no, un motivo legible por máquina.
`latency_ms`	integer	required	Tiempo de procesamiento en el servidor, en ms.
`checks`	object	required	Desglose por comprobación: syntax, mx, smtp, disposable, roleAddress, freeProvider, catchAll.
`request_id`	string	required	Identificador de esta petición. Cítalo en las incidencias de soporte.

Ejemplos de respuesta

Response200 OK

{
  "valid": true,
  "status": "deliverable",
  "score": 94,
  "disposable": false,
  "catchAll": false,
  "mx": true,
  "reason": null,
  "latency_ms": 82,
  "request_id": "req_9f2c1ab47d3e5081c6b2a904"
}

Respuesta — dirección rechazada por las comprobaciones200 OK

{
  "valid": false,
  "status": "undeliverable",
  "score": 10,
  "disposable": true,
  "catchAll": false,
  "mx": false,
  "reason": "disposable_domain",
  "latency_ms": 41,
  "request_id": "req_4c81f0a29b6d7e35a0c128ff"
}

Respuesta — petición mal formada422 Unprocessable Entity

{
  "error": "invalid_email_format",
  "message": "The email address is not RFC 5322 compliant.",
  "request_id": "req_01hx9abc123"
}

Respuesta — no autorizado401 Unauthorized

{
  "error": "invalid_api_key",
  "message": "The API key is invalid or revoked.",
  "request_id": "req_01hx9abc123"
}

Ejemplos de código

const response = await fetch("https://api.mailbeam.dev/v1/verify", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAILBEAM_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "user@example.com" }),
});

const { valid, score, reason } = await response.json();
if (!valid || score < 60) throw new Error(reason);

Try it out

Interactive playground — coming soon

Endpoint: /v1/verify