POST /v1/verify

Verifica un indirizzo email in modo sincrono.

Un indirizzo che non supera i controlli resta comunque una richiesta riuscita: ricevi un200con valid: false + reason. Le risposte 4xx qui sotto riguardano la richiesta in sé.

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

L'endpoint principale di verifica. Restituisce l'esito, il punteggio di qualità e il dettaglio controllo per controllo.

Corpo della richiesta

Parameters

Name	Type	Required	Description
`email`	string	required	L'email da verificare. Formato dell'RFC 5321, massimo 254 caratteri.
`timeout_ms`	integer	optional (default: 3000)	Tempo massimo del sondaggio SMTP in ms. Intervallo: 100-5000.
`include_checks`	boolean	optional (default: true)	Includere nella risposta il dettaglio controllo per controllo.

Schema della risposta

Campi della risposta

Name	Type	Required	Description
`valid`	boolean	required	true solo quando la casella è stata confermata.
`status`	"deliverable" \| "undeliverable" \| "risky" \| "unknown"	required	L'esito. 'unknown' significa che non siamo riusciti a saperlo, non che l'indirizzo sia cattivo.
`score`	integer (0-100)	required	Punteggio di qualità. Consigliamo di accettare >= 60.
`disposable`	boolean	required	true se viene da un fornitore temporaneo noto.
`catchAll`	boolean	required	true se il dominio accetta tutti gli indirizzi.
`mx`	boolean	required	true se il dominio ha record MX validi e raggiungibili.
`reason`	string \| null	required	null quando è valido. Altrimenti, un motivo leggibile dalla macchina.
`latency_ms`	integer	required	Tempo di elaborazione sul server, in ms.
`checks`	object	required	Dettaglio controllo per controllo: syntax, mx, smtp, disposable, roleAddress, freeProvider, catchAll.
`request_id`	string	required	Identificatore di questa richiesta. Citalo nelle segnalazioni all'assistenza.

Esempi di risposta

Response200 OK

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

Risposta — indirizzo rifiutato dai controlli200 OK

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

Risposta — richiesta malformata422 Unprocessable Entity

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

Risposta — non autorizzato401 Unauthorized

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

Esempi di codice

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