POST /v1/verify

Vérifie une adresse e-mail de façon synchrone.

Une adresse qui ne passe pas les contrôles reste une requête réussie : vous recevez un200avec valid: false + reason. Les réponses 4xx ci-dessous concernent la requête elle-même.

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

L'endpoint principal de vérification. Renvoie le verdict, le score de qualité et le détail contrôle par contrôle.

Corps de la requête

Parameters

Name	Type	Required	Description
`email`	string	required	L'adresse à vérifier. Format du RFC 5321, 254 caractères au maximum.
`timeout_ms`	integer	optional (default: 3000)	Délai maximum de la sonde SMTP en ms. Plage : 100–5000.
`include_checks`	boolean	optional (default: true)	Inclure le détail contrôle par contrôle dans la réponse.

Schéma de la réponse

Champs de la réponse

Name	Type	Required	Description
`valid`	boolean	required	true seulement quand la boîte a été confirmée.
`status`	"deliverable" \| "undeliverable" \| "risky" \| "unknown"	required	Le verdict. « unknown » signifie que nous n'avons pas pu savoir, pas que l'adresse est mauvaise.
`score`	integer (0–100)	required	Score de qualité. Nous conseillons d'accepter à partir de 60.
`disposable`	boolean	required	true si l'adresse vient d'un fournisseur temporaire connu.
`catchAll`	boolean	required	true si le domaine accepte toutes les adresses.
`mx`	boolean	required	true si le domaine a des enregistrements MX valides et joignables.
`reason`	string \| null	required	null quand l'adresse est valide. Sinon, un motif lisible par la machine.
`latency_ms`	integer	required	Temps de traitement côté serveur, en ms.
`checks`	object	required	Détail contrôle par contrôle : syntax, mx, smtp, disposable, roleAddress, freeProvider, catchAll.
`request_id`	string	required	Identifiant de cette requête. Citez-le dans vos demandes au support.

Exemples de réponse

Response200 OK

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

Réponse — adresse rejetée par les contrôles200 OK

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

Réponse — requête mal formée422 Unprocessable Entity

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

Réponse — non autorisé401 Unauthorized

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

Exemples de code

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