La API REST de Mailbeam vive en https://api.mailbeam.dev con todos los endpoints bajo /v1/. Las peticiones se autentican con un token Bearer, envían y reciben JSON, y devuelven el resultado directamente sin sobre: los errores son las únicas respuestas envueltas, y llevan un código de error, un mensaje y un request_id.

URL base: https://api.mailbeam.dev/v1/
Cabecera de autenticación: Authorization: Bearer mb_live_…
Tipo de contenido: application/json
Campos de error: error · message · request_id

Referencia de la API

La API REST de Mailbeam te permite verificar direcciones de email, lanzar trabajos por lotes y consultar el consumo de tu cuenta.

URL base

https://api.mailbeam.dev

Todos los endpoints cuelgan de /v1/. Los cambios que rompan compatibilidad se introducirán en versiones nuevas (/v2/, etc.).

Autenticación

Todas las peticiones necesitan un token Bearer en la cabecera Authorization:

Authorization: Bearer mb_live_xxxxxxxxxxxxxxxxxxxx

En Autenticación tienes los tipos de clave, la rotación y el modo de pruebas.

Tipo de contenido

Las peticiones con cuerpo deben enviar Content-Type: application/json. Todas las respuestas devuelven Content-Type: application/json.

Versionado

La versión actual de la API es v1. Mantenemos la compatibilidad hacia atrás dentro de una versión. Cuando haga falta romperla, sacaremos una versión nueva y marcaremos la antigua como obsoleta con al menos 12 meses de aviso.

Idempotencia

El endpoint POST /v1/verify se puede reintentar sin problema: no tiene efectos secundarios. Llamarlo dos veces con el mismo email devuelve el mismo resultado (salvo variaciones de tiempo o de red).

Para POST /v1/verify/batch, usa la cabecera Idempotency-Key para reintentar envíos sin crear trabajos duplicados:

Idempotency-Key: your-unique-job-id

Sobre de respuesta

Todas las respuestas correctas devuelven el resultado directamente, sin sobre. Los errores devuelven:

{
  "error": "error_code",
  "message": "Human-readable description.",
  "request_id": "req_01hx9abc123"
}

Endpoints

Método	Ruta	Descripción
`POST`	`/v1/verify`	Verificar un email
`POST`	`/v1/verify/batch`	Enviar un lote de emails
`GET`	`/v1/jobs/:id`	Consultar el estado de un trabajo por lotes
`GET`	`/v1/account/usage`	Consultar el consumo actual de la cuota

Preguntas frecuentes

¿Cuál es la URL base de la API de Mailbeam?

https://api.mailbeam.dev, con todos los endpoints bajo el prefijo /v1/. Las peticiones con cuerpo deben enviar Content-Type: application/json, y todas las respuestas devuelven JSON.

¿Cómo se autentican las peticiones a la API de Mailbeam?

Con un token Bearer en la cabecera Authorization, de esta forma: Authorization: Bearer mb_live_xxxxxxxxxxxxxxxxxxxx. No hay ningún otro esquema de autenticación, y las claves se rotan desde el panel.

¿Qué aspecto tiene un error de la API de Mailbeam?

Las respuestas correctas devuelven el resultado directamente, sin sobre. Los errores devuelven un objeto JSON con tres campos: error (un código estable y legible por máquina), message (una descripción legible por personas) y request_id, que es lo que necesita soporte para rastrear una llamada concreta.

¿Qué endpoints de Mailbeam se pueden reintentar sin riesgo?

POST /v1/verify se puede reintentar porque no tiene efectos secundarios: la misma dirección devuelve el mismo resultado. POST /v1/verify/batch crea un trabajo, así que los reintentos deben llevar una cabecera Idempotency-Key para no enviar el mismo trabajo dos veces.

Respuestas contrastadas con el contrato de la API el 2026-08-10.