Beta privataMailbeam è in beta privata: l'API pubblica non è ancora aperta.Iscriviti alla lista d'attesa

Mailbeam·Documentazione
Inizia

Avvio rapido

Questa guida ti porta da zero alla tua prima email verificata in meno di 5 minuti.

Prerequisiti

Passo 1 — Prendi la tua chiave API

Iscrivendoti viene creata automaticamente la tua prima chiave API. Copiala dal pannello:

export MAILBEAM_KEY="mb_live_xxxxxxxxxxxxxxxxxxxx"

Tieni segreta la tua chiave API. Non caricarla mai nel controllo di versione. Usa variabili d'ambiente o un gestore di segreti.

Passo 2 — Fai la tua prima richiesta

Invia una richiesta POST a /v1/verify con l'indirizzo che vuoi controllare:

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

Passo 3 — Leggi la risposta

Una risposta corretta ha questo aspetto:

{
  "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
}

I campi chiave da guardare nel tuo flusso di registrazione:

  • valid — true se l'indirizzo ha superato tutti i controlli critici
  • score — punteggio di qualità da 0 a 100; fissa la tua soglia (consigliamo ≥ 60 nella maggior parte dei casi)
  • reason — null se è valido, oppure una stringa leggibile dalla macchina che spiega perché è fallito

Passo 4 — Avvolgi la chiamata

Non c'è nessun SDK da installare. Mailbeam è un unico endpoint HTTP, quindi un piccolo wrapper nel tuo codice fa il lavoro e non ti lascia niente da aggiornare. Gli SDK ufficiali sono nella roadmap: vedi 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();
}

Passo 5 — Integralo nella tua registrazione

Un gestore di registrazione completo per 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) {
    // Non bloccare mai una registrazione perché siamo stati lenti o siamo giù.
    // Decidi con cognizione di causa se un controllo non disponibile significa
    // "fallo passare" o "fallo aspettare": nella maggior parte dei prodotti è
    // la prima.
    console.error("mailbeam non disponibile", error);
    result = { valid: true, score: 100, reason: null };
  }

  if (!result.valid || result.score < 60) {
    return res.status(422).json({
      error: "Inserisci un indirizzo email valido.",
      code: result.reason ?? "invalid_email",
    });
  }

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

E l'equivalente in 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:
        # Lo stesso ragionamento di sopra: il nostro guasto non è un problema dell'utente.
        result = {"valid": True, "score": 100, "reason": None}

    if not result["valid"] or result["score"] < 60:
        raise HTTPException(
            status_code=422,
            detail=result["reason"] or "Inserisci un indirizzo email valido.",
        )

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

Prossimi passi