ES Cambiar idioma
Abrir un buzón

Referencia de la API

Tres endpoints, JSON de entrada y JSON de salida. Sin clave ni cuenta en dominios públicos: pega una solicitud en una terminal y funciona.

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

https://grabmail.io/api/v1

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 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.

En un dominio propio el buzón es privado, así que las solicitudes llevan una clave, que es lo que demuestra que el buzón es tuyo. La clave se emite cuando verificar el dominio, se muestra una sola vez, y aquí solo se guarda como hash: 

Authorization: Bearer <your key>

Una clave incorrecta o ausente en un dominio privado responde 401 con unauthorized. Las claves se comparan en tiempo constante, así que una incorrecta tarda lo mismo en rechazarse que una correcta en aceptarse.

Endpoints

GET /api/v1/mailbox

Todo lo que espera en una dirección, lo más reciente primero. Esta es la llamada que consulta tu batería de pruebas.

Parámetros

NombreEntradaTipoObligatorioDescripción
address query string sí El buzón a leer, p. ej. k7fq2m@grabmail.io.
limit query integer no Cuántos mensajes devolver en esta llamada, 1–200. Por defecto 50, los más recientes primero. Limita una respuesta, no el buzón — usa before para leer más allá.
before query string no El id del mensaje más antiguo que ya tienes; devuelve la página siguiente. Reenvía el campo next de la respuesta anterior. Cuando next es null, ya tienes todo.

Ejemplo

Listar un buzón 
$ 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"
    }
  ]
}

Códigos de estado

200
El buzón se leyó correctamente. Un buzón vacío es un 200 con count: 0, nunca un 404. next lleva el cursor para la página siguiente, o null al final.
400
La dirección no tiene un formato válido, o before no es un id de mensaje.
400
address falta o no es válida.
404
Ese dominio no está alojado aquí — comprueba el registro MX.
429
Límite de solicitudes superado. Reintenta después del retraso indicado en Retry-After.
GET /api/v1/message/{id}

Cabeceras, la parte en texto plano, la parte en HTML y los adjuntos.

Parámetros

NombreEntradaTipoObligatorioDescripción
id path string sí El id del mensaje devuelto por la llamada de listado.
mailbox query string sí La dirección a la que se entregó el mensaje.

Ejemplo

Leer un mensaje 
$ 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": []
}

Códigos de estado

200
El mensaje. html es null cuando el remitente envió solo texto plano.
400
mailbox falta o no es válido.
404
No existe ese mensaje en ese buzón, o ha superado su periodo de retención.
429
Límite de solicitudes superado.
DELETE /api/v1/message/{id}

Lo elimina de inmediato, en lugar de esperar a que expire la ventana de retención.

Parámetros

NombreEntradaTipoObligatorioDescripción
id path string sí El mensaje a eliminar.
mailbox query string sí La dirección a la que fue entregado.

Ejemplo

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

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

Códigos de estado

200
Eliminado. La llamada es idempotente: eliminar dos veces sigue respondiendo 200.
400
mailbox falta o no es válido.
404
No existe ese mensaje en ese buzón.
429
Límite de solicitudes superado.

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, y los buzones solo se pueden leer con tu clave.

Conectar un dominio →