Bêta privéeMailbeam est en bêta privée : l'API publique n'est pas encore ouverte.Rejoindre la liste d'attente

Mailbeam·Documentation
Commencer

Démarrage rapide

Ce guide vous mène de zéro à votre première adresse vérifiée en moins de 5 minutes.

Prérequis

Étape 1 — Récupérer votre clé d'API

À l'inscription, votre première clé d'API est créée automatiquement. Copiez-la depuis le tableau de bord :

export MAILBEAM_KEY="mb_live_xxxxxxxxxxxxxxxxxxxx"

Gardez votre clé d'API secrète. Ne la versionnez jamais. Passez par des variables d'environnement ou un gestionnaire de secrets.

Étape 2 — Faire votre première requête

Envoyez une requête POST à /v1/verify avec l'adresse à contrôler :

curl -X POST https://api.mailbeam.dev/v1/verify \
  -H "Authorization: Bearer $MAILBEAM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Étape 3 — Lire la réponse

Une réponse réussie ressemble à ceci :

{
  "valid": true,
  "score": 94,
  "disposable": false,
  "catchAll": false,
  "mx": true,
  "reason": null,
  "checks": {
    "syntax": true,
    "mx": true,
    "smtp": true,
    "disposable": false,
    "roleAddress": false,
    "freeProvider": false
  },
  "latency_ms": 82
}

Les champs à regarder dans votre parcours d'inscription :

  • valid — true si l'adresse a passé tous les contrôles critiques
  • score — un score de qualité de 0 à 100 ; fixez votre propre seuil (nous conseillons ≥ 60 pour la plupart des usages)
  • reason — null si l'adresse est valide, sinon une chaîne lisible par la machine expliquant l'échec

Étape 4 — Envelopper l'appel

Il n'y a pas de SDK à installer. Mailbeam se résume à un endpoint HTTP : un petit wrapper dans votre propre code fait le travail et ne vous laisse rien à mettre à jour. Des SDK officiels sont à la feuille de route — voyez SDK.

// lib/mailbeam.js
const ENDPOINT = "https://api.mailbeam.dev/v1/verify";

export async function verifyEmail(email, { timeoutMs = 3000 } = {}) {
  const response = await fetch(ENDPOINT, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MAILBEAM_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email }),
    signal: AbortSignal.timeout(timeoutMs),
  });

  if (!response.ok) {
    const { error, message } = await response.json();
    throw Object.assign(new Error(message), { code: error, status: response.status });
  }

  return response.json();
}

Étape 5 — L'intégrer à votre inscription

Un handler d'inscription complet pour Node.js / Express :

import { verifyEmail } from "./lib/mailbeam.js";

app.post("/api/signup", async (req, res) => {
  const { email, password } = req.body;

  let result;
  try {
    result = await verifyEmail(email);
  } catch (error) {
    // Ne bloquez jamais une inscription parce que nous avons été lents ou
    // indisponibles. Décidez délibérément si un contrôle indisponible veut dire
    // « laissez-les entrer » ou « faites-les attendre » — pour la plupart des
    // produits, c'est le premier.
    console.error("mailbeam indisponible", error);
    result = { valid: true, score: 100, reason: null };
  }

  if (!result.valid || result.score < 60) {
    return res.status(422).json({
      error: "Merci de fournir une adresse e-mail valide.",
      code: result.reason ?? "invalid_email",
    });
  }

  const user = await createUser({ email, password });
  res.json({ user });
});

Et l'équivalent pour Python / FastAPI :

import os
import httpx
from fastapi import HTTPException

ENDPOINT = "https://api.mailbeam.dev/v1/verify"
HEADERS = {"Authorization": f"Bearer {os.environ['MAILBEAM_KEY']}"}


async def verify_email(email: str) -> dict:
    async with httpx.AsyncClient(timeout=3.0) as client:
        response = await client.post(ENDPOINT, json={"email": email}, headers=HEADERS)
        response.raise_for_status()
        return response.json()


@app.post("/api/signup")
async def signup(email: str, password: str):
    try:
        result = await verify_email(email)
    except httpx.HTTPError:
        # Même raisonnement que plus haut : notre panne n'est pas le problème
        # de l'utilisateur.
        result = {"valid": True, "score": 100, "reason": None}

    if not result["valid"] or result["score"] < 60:
        raise HTTPException(
            status_code=422,
            detail=result["reason"] or "Merci de fournir une adresse e-mail valide.",
        )

    user = await create_user(email=email, password=password)
    return {"user": user}

Prochaines étapes