Referencia de la API

Resumen

Un buzón nunca se crea: existe en el momento en que llega un mensaje a una dirección, y desaparece 5 días después. No hay nada que registrar, así que en dominios públicos la API no tiene concepto de usuario, proyecto o token.

• Toda respuesta es JSON, incluido cada error.
• Todas las horas están en UTC en formato RFC 3339: 2026-08-04T18:31:07Z.
• Los ids de mensaje son cadenas opacas. No los analices.
• Solo recepción. No existe un endpoint para enviar correo, de forma intencional.

URL base

Solo HTTPS; el HTTP simple se redirige. La versión está en la ruta, y v1 no cambiará de forma bajo tus pies: un cambio incompatible obtiene un número nuevo.

Autenticación: ninguna

Ninguna en dominios públicos. Cualquiera que conozca una dirección puede leer su buzón, a través de la API igual que a través del sitio web. Ese es el trato que ofrece un servicio de correo desechable compartido, así que nunca uses una dirección pública para algo que te importe.

Un dominio que apuntes aquí responde en estos mismos endpoints, tampoco con clave. Apunta el MX hacia nosotros y el primer mensaje lo conecta; consulta conectar un dominio. Los buzones de ese dominio los puede leer cualquiera que conozca la dirección, igual que en los dominios públicos.

Sigue habiendo un caso con cabecera: un dominio que hemos cerrado a petición se lee con Authorization: Bearer <key>, y una clave incorrecta o ausente responde 401 con unauthorized. Las claves se comparan en tiempo constante, así que una incorrecta tarda en rechazarse lo mismo que una correcta en aceptarse.

Dominios premium

La única excepción a la regla anterior. Los dominios públicos están en las listas públicas de correo desechable, por eso un formulario de registro rechaza a veces una dirección alojada en ellos. Un plan de pago abre un pool de 92 dominios .com privados, fuera de esas listas.

La API no cambia en nada. Mismas rutas, mismos parámetros, mismas formas de respuesta. La única diferencia es una cabecera: una dirección premium se lee con Authorization: Bearer gm_live_…, con una clave de sus claves de API. Sin una clave válida, la misma petición responde 402 o 403 — nunca un buzón.

# A public domain: no header at all.
curl -sG https://grabmail.io/api/v1/mailbox \
  --data-urlencode "address=a7f3k2@grabmail.io"

# A premium domain: the same call, plus a key.
curl -sG https://grabmail.io/api/v1/mailbox \
  -H "Authorization: Bearer gm_live_…" \
  --data-urlencode "address=a7f3k2@one-of-the-pool.com"

Los dominios públicos y sus propios dominios siguen siendo gratuitos, sin clave y sin límite en todos los planes, incluido el gratuito. Las cuotas solo cuentan los mensajes que llegan al pool premium. Los planes y los precios están en la página de planes.

Endpoints

$ curl -G https://grabmail.io/api/v1/mailbox \
  --data-urlencode "address=k7fq2m@grabmail.io"

{
  "address": "k7fq2m@grabmail.io",
  "count": 1,
  "next": null,
  "messages": [
    {
      "id": "01JR8W2K4Q",
      "from": "no-reply@example.com",
      "subject": "Your verification code",
      "date": "2026-08-04T18:31:07Z",
      "seen": false,
      "attachments": 0,
      "expires_at": "2026-08-09T18:31:07Z"
    }
  ]
}

$ curl -G https://grabmail.io/api/v1/message/01JR8W2K4Q \
  --data-urlencode "mailbox=k7fq2m@grabmail.io"

{
  "id": "01JR8W2K4Q",
  "from": "no-reply@example.com",
  "to": "k7fq2m@grabmail.io",
  "subject": "Your verification code",
  "date": "2026-08-04T18:31:07Z",
  "text": "Your code is 481920. It expires in 10 minutes.",
  "html": null,
  "attachments": []
}

$ curl -X DELETE -G https://grabmail.io/api/v1/message/01JR8W2K4Q \
  --data-urlencode "mailbox=k7fq2m@grabmail.io"

{
  "deleted": true,
  "id": "01JR8W2K4Q"
}

Archivos adjuntos

Cada mensaje lista sus adjuntos con una URL ya lista. Descárgalo con la misma autorización que el mensaje.

GET /api/v1/attachment/{id}?mailbox={address}

Siempre responde application/octet-stream con Content-Disposition: attachment, sea cual sea la etiqueta que puso el remitente. Es intencionado: devolver el text/html de un desconocido permitiría que un adjunto se ejecutara como página en este origen. El tipo real está en el JSON del mensaje, donde es un dato y no una instrucción.

Errores

Todo fallo es JSON con los mismos dos campos, así que un cliente los gestiona en un solo lugar. El estado indica la categoría, error es un identificador estable legible por máquina, y message es para humanos y puede reformularse en cualquier momento.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error":   "invalid_address",
  "message": "address must look like name@domain"
}

Nunca decidas según message. Los identificadores en uso son invalid_address, unknown_domain, not_found y rate_limited.

Límites de solicitudes

Una solicitud por segundo, por dirección. Consultar un buzón una vez por segundo es el patrón previsto y nunca se limita.

Al superar el límite obtienes 429 con Retry-After en segundos. No hay cuota diaria ni crédito de ráfaga que gestionar.

Retención

Un mensaje se elimina 5 días después de llegar, leído o no. Cada mensaje incluye expires_at, así que nunca tienes que calcular esa fecha tú mismo.

Es un límite fijo, no una opción configurable: ningún parámetro lo amplía. Si un mensaje debe durar más que esa ventana, descárgalo y guárdalo por tu cuenta.

Tu propio dominio

Apunta tu MX a smtp.grabmail.io y todas las direcciones de tu dominio responderán a través de estos mismos endpoints: sin una segunda API que aprender, sin registro y sin clave.

Conectar un dominio →