Documentación API

API GPTMail

Usa la API de GPTMail para generar bandejas de entrada temporales, listar y leer mensajes y eliminar correos mediante HTTPS con un encabezado X-API-Key. Es ideal para pruebas automatizadas, pipelines de CI/CD y flujos de trabajo de QA.

Cómo obtener una API Key

Buy API requests

Purchase API requests with GPTMail points. Earn points through daily check-ins and public domains, or buy points with LDC at a 1:1 rate.

Buy with points / add requests

Opción 2: Añadir tu propio dominio

Cuando un dominio público supera la verificación MX: enviado sin iniciar sesión → clave API (20000 solicitudes); enviado con sesión iniciada → 200 puntos. Cada dominio recibe una sola recompensa. Importante: una vez conectado, ese sufijo de dominio pasa a ser público para todos los usuarios del sitio, y otros también pueden generar direcciones de buzón bajo él. Tras la activación, no elimines, sustituyas ni modifiques el registro MX que apunta este dominio a nuestro servicio. De lo contrario, comprobaciones posteriores pueden considerar el dominio mal configurado. Si una comprobación posterior encuentra el MX inválido, el dominio se desactivará. Si el MX sigue inválido en 3 comprobaciones consecutivas, la API Key asociada también se desactivará. Si el MX vuelve a ser válido más tarde, el dominio se reactivará automáticamente.

Dominios

Clave de prueba pública

Para hacer pruebas, envía la clave pública compartida que se muestra abajo en el encabezado X-API-Key. Cambia cada día y tiene un límite diario de 200.000 solicitudes compartido entre todos los usuarios.

Restante hoy

Se restablece en

Cargando cuota en vivo de la clave pública…

La referencia de la API siguiente se puede copiar como Markdown para herramientas de IA, bases de conocimiento o un README.

URL base: https://mail.chatgpt.org.uk

AI
llms.txt

·

llms-full.txt

(Markdown)

Inicio rápido

  • X-API-Key: YOUR_KEY es la opción más sencilla. Para pruebas rápidas, usa la clave pública diaria que se muestra arriba en lugar de YOUR_KEY.

  • La mayoría de endpoints de buzón requieren un parámetro email, por ejemplo ?email=demo@example.com.

  • Las respuestas de la API de GPTMail usan JSON con los campos success, data y error, además de usage cuando se usa una clave de API. Los errores de Cloudflare, incluidas las respuestas por límite de frecuencia, pueden devolver HTML en su lugar. Comprueba el estado HTTP y el Content-Type antes de analizar el JSON.

  • Si ya conoces un dominio admitido actualmente en este sitio, no hace falta llamar primero al endpoint de generación de correo. Puedes componer prefix@domain en local y llamar directamente a las APIs de buzón, ahorrando una solicitud.

Límites de frecuencia y reintentos

  • GET y POST /api/generate-email comparten un límite de 30 solicitudes cada 10 segundos por IP de origen. Se aplica tanto a las claves de API públicas como a las personales. Las distintas claves y clientes que usan la misma IP comparten este límite.

  • Superar este límite devuelve HTTP 429 y bloquea la generación de direcciones durante 10 segundos. Espera el tiempo indicado en Retry-After antes de reintentar. Si falta este encabezado, espera al menos 10 segundos y vuelve a intentarlo con esperas cada vez mayores. Evita los reintentos simultáneos desde clientes que comparten una IP.

  • Esta regla no se aplica a listar los mensajes de una bandeja ni a leer correos individuales. Las cuotas diarias y totales de las claves de API se siguen aplicando por separado. Esperar 10 segundos no restablece la cuota agotada de una clave.

Endpoints principales

POST / GET
/api/generate-email

Genera un buzón temporal. Usa GET para el flujo aleatorio más simple, o POST con prefix y domain cuando quieras control explícito.

GET
/api/emails?email=...

Obtiene los correos de un buzón.

GET
/api/email/{id}?email=...

Obtiene un solo correo, con texto, HTML, cabeceras en bruto y metadatos.

DELETE
/api/email/{id}?email=...

Elimina un correo por su ID.

DELETE
/api/emails/clear?email=...

Elimina todos los correos de un buzón.

GET
/api/stats

Lee estadísticas de todo el sitio.

Flujo de ejemplo

Dos patrones habituales: dejar que el servicio genere un buzón o pedir un prefijo fijo. Si ya conoces un dominio admitido actualmente, también puedes componer el buzón en local y consultarlo directamente.

1) Generar una dirección de email temporal aleatoria

curl 'https://mail.chatgpt.org.uk/api/generate-email' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Ejemplo de respuesta
{
  "success": true,
  "data": {
    "email": "a3f9c2b1@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 1,
    "remaining_today": 199999,
    "total_limit": 200000,
    "total_usage": 1,
    "remaining_total": 199999
  }
}

2) Generar con prefijo fijo (p. ej. demo@example.com)

curl -X POST 'https://mail.chatgpt.org.uk/api/generate-email' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: PUBLIC_API_KEY' \
  -d '{"prefix":"demo"}'
Ejemplo de respuesta
{
  "success": true,
  "data": {
    "email": "demo@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 2,
    "remaining_today": 199998
  }
}

3) Listar correos en un buzón

Si ya conoces un dominio admitido, omite el paso 1 y consulta directamente.

curl 'https://mail.chatgpt.org.uk/api/emails?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Ejemplo de respuesta
{
  "success": true,
  "data": {
    "emails": [
      {
        "id": "e5a7f3...",
        "email_address": "demo@example.com",
        "from_address": "noreply@github.com",
        "subject": "Your code: 654321",
        "content": "Your verification code is 654321",
        "html_content": "...",
        "has_html": true,
        "timestamp": 1709654321,
        "created_at": "2024-03-05T12:18:41Z"
      }
    ],
    "count": 1
  }
}

4) Leer un solo correo — incluye texto plano, cuerpo HTML y metadatos

Sustituye EMAIL_ID por un id devuelto en el paso 3. Pasa también la dirección de la bandeja como email (también para eliminar y descargar adjuntos): así el correo se lee directamente de su bandeja en lugar de buscarse por ID. Con una clave de API, el parámetro email es opcional, pero enviarlo agiliza la búsqueda.

curl 'https://mail.chatgpt.org.uk/api/email/EMAIL_ID?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Ejemplo de respuesta
{
  "success": true,
  "data": {
    "id": "e5a7f3...",
    "email_address": "demo@example.com",
    "from_address": "noreply@github.com",
    "subject": "Your code: 654321",
    "content": "Your verification code is 654321",
    "html_content": "<p>Your code is 654321</p>",
    "has_html": true,
    "timestamp": 1709654321,
    "raw_size": 2048,
    "created_at": "2024-03-05T12:18:41Z"
  }
}

5) Eliminar un correo por ID

Con una clave de API, el parámetro email es opcional, pero enviarlo agiliza la búsqueda.

curl -X DELETE 'https://mail.chatgpt.org.uk/api/email/EMAIL_ID?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Ejemplo de respuesta
{
  "success": true,
  "data": {
    "message": "Email deleted"
  }
}

6) Vaciar todo el buzón — elimina todos los correos de esta dirección

Cada llamada elimina un lote. Mientras la respuesta tenga "has_more": true, vuelva a llamarla hasta que devuelva false.

curl -X DELETE 'https://mail.chatgpt.org.uk/api/emails/clear?email=demo@example.com' \
  -H 'X-API-Key: PUBLIC_API_KEY'
Ejemplo de respuesta
{
  "success": true,
  "data": {
    "message": "Deleted 3 emails",
    "count": 3,
    "has_more": false
  }
}

Forma de la respuesta

Las respuestas correctas suelen verse así. Si te autenticas con una API Key, fíjate en la información de cuota dentro de usage.

{
  "success": true,
  "data": {
    "email": "demo@example.com"
  },
  "usage": {
    "daily_limit": 200000,
    "used_today": 1,
    "remaining_today": 199999,
    "total_limit": 200000,
    "total_usage": 1,
    "remaining_total": 199999
  }
}

Estadísticas ampliadas

  • /api/statistics/24h devuelve una ventana de distribución horaria de 24 horas; usa offset=1,2,... para ventanas anteriores.
  • /api/statistics/top-subjects devuelve los asuntos de correo más frecuentes.
  • /api/statistics/top-domains devuelve los dominios más activos.
  • /api/statistics/top-senders devuelve los remitentes más activos.
GPTMail