Autenticación

Mailbeam usa claves de API para autenticar las peticiones. Toda petición debe incluir una clave válida en la cabecera Authorization.

Token Bearer

Incluye tu clave de API como token Bearer en cada petición:

Authorization: Bearer mb_live_xxxxxxxxxxxxxxxxxxxx

Ejemplo con cURL:

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

Prefijos de las claves

Las claves de API de Mailbeam llevan un prefijo que indica su entorno:

Usa claves mb_test_ en desarrollo y en CI. Las claves de prueba devuelven respuestas fijas según el dominio del email:

• @valid.mailbeam-test.dev → devuelve siempre { valid: true, score: 99 }
• @invalid.mailbeam-test.dev → devuelve siempre { valid: false, score: 0 }
• @disposable.mailbeam-test.dev → devuelve siempre { valid: false, disposable: true }

Variables de entorno

No escribas nunca las claves de API directamente en tu código. Usa variables de entorno:

# .env.local
MAILBEAM_KEY=mb_live_xxxxxxxxxxxxxxxxxxxx

const headers = {
  Authorization: `Bearer ${process.env.MAILBEAM_KEY}`,
  "Content-Type": "application/json",
};

Rotación de claves

Conviene rotar las claves de API periódicamente, y de inmediato si una se ve comprometida:

1. Ve a la página de claves de API de tu panel
2. Pulsa Create key para generar una clave nueva
3. Actualiza tu aplicación con la clave nueva
4. Pulsa Revoke en la clave antigua cuando el tráfico ya haya cambiado

Revocar una clave la invalida al instante. Las peticiones que la usen devolverán 401 Unauthorized.

Varias claves

Puedes crear hasta 10 claves de API por cuenta. Nuestra recomendación:

• Una clave por entorno (desarrollo, staging, producción)
• Una clave por aplicación si tienes varios servicios
• Rota las claves cuando alguien deja el equipo

Respuestas de error