Beta privadaMailbeam está en beta privada: la API pública todavía no está abierta.Únete a la lista de espera

Mailbeam·Documentación
Empezar

Inicio rápido

Esta guía te lleva de cero a tu primer email verificado en menos de 5 minutos.

Requisitos previos

Paso 1 — Consigue tu clave de API

Al registrarte se crea automáticamente tu primera clave de API. Cópiala desde el panel:

export MAILBEAM_KEY="mb_live_xxxxxxxxxxxxxxxxxxxx"

Guarda tu clave de API en secreto. No la subas nunca al control de versiones. Usa variables de entorno o un gestor de secretos.

Paso 2 — Haz tu primera petición

Envía una petición POST a /v1/verify con la dirección que quieras comprobar:

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

Paso 3 — Lee la respuesta

Una respuesta correcta tiene este aspecto:

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

Los campos clave que mirar en tu flujo de registro:

  • valid — true si la dirección ha pasado todas las comprobaciones críticas
  • score — puntuación de calidad de 0 a 100; fija tu propio umbral (recomendamos ≥ 60 en la mayoría de los casos)
  • reason — null si es válida, o una cadena legible por máquina que explica por qué ha fallado

Paso 4 — Envuelve la llamada

No hay ningún SDK que instalar. Mailbeam es un único endpoint HTTP, así que un envoltorio pequeño en tu propio código hace el trabajo y no te deja nada que actualizar. Los SDK oficiales están en la hoja de ruta: mira SDKs.

// 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();
}

Paso 5 — Intégralo en tu registro

Un handler de registro completo para 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) {
    // Nunca bloquees un registro porque hayamos ido lentos o estemos caídos.
    // Decide a conciencia si una comprobación no disponible significa "que
    // pase" o "que espere": en la mayoría de los productos es lo primero.
    console.error("mailbeam no disponible", error);
    result = { valid: true, score: 100, reason: null };
  }

  if (!result.valid || result.score < 60) {
    return res.status(422).json({
      error: "Escribe una dirección de email válida.",
      code: result.reason ?? "invalid_email",
    });
  }

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

Y el equivalente en 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:
        # El mismo razonamiento de arriba: nuestra caída no es problema del usuario.
        result = {"valid": True, "score": 100, "reason": None}

    if not result["valid"] or result["score"] < 60:
        raise HTTPException(
            status_code=422,
            detail=result["reason"] or "Escribe una dirección de email válida.",
        )

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

Siguientes pasos