API de correo temporal y servidor MCP para pruebas y agentes de IA

Inicio rápido con curl

Crea un buzón, espera el siguiente correo, léelo y elimina el buzón. Guarda tu clave API en TEMPGENERATOR_TOKEN y nunca la pongas en una URL.

Requiere curl y jq. El script espera hasta tres veces durante 20 segundos, muestra el asunto, los códigos, los enlaces y el texto de cada mensaje y, al final, elimina el buzón.

export TEMPGENERATOR_URL='https://www.tempgenerator.com'
API="$TEMPGENERATOR_URL/developer-api/v1"
AUTH="Authorization: Bearer $TEMPGENERATOR_TOKEN"
INBOX=$(curl --fail-with-body -sS -X POST "$API/inboxes" -H "$AUTH" -H 'Accept: application/json')
ID=$(printf '%s' "$INBOX" | jq -r .id)
echo "Send a test email to $(printf '%s' "$INBOX" | jq -r .address)"
for ATTEMPT in 1 2 3; do
  RESULT=$(curl --fail-with-body -sS "$API/inboxes/$ID/wait?after=0&timeout=20" -H "$AUTH" -H 'Accept: application/json')
  [ "$(printf '%s' "$RESULT" | jq -r .status)" = message ] && break
done
for MESSAGE in $(printf '%s' "$RESULT" | jq -r '.messages[].id'); do
  curl --fail-with-body -sS "$API/inboxes/$ID/messages/$MESSAGE" -H "$AUTH" -H 'Accept: application/json' \
    | jq '{subject, codes, links, text}'
done
curl --fail-with-body -sS -X DELETE "$API/inboxes/$ID" -H "$AUTH"

La API de un vistazo

URL base: https://www.tempgenerator.com/developer-api/v1. Envía Authorization: Bearer <key> en cada solicitud. Las respuestas son JSON; los errores tienen la forma {"error": {"code", "message", "retry_after"}} y los errores de cuota también envían una cabecera Retry-After.

• POST /inboxes Crear un buzón y obtener su dirección y su caducidad
• GET /inboxes/{id}/wait?after=0&timeout=20 Esperar hasta 20 segundos el siguiente mensaje después de un cursor
• GET /inboxes/{id}/messages?after=0 Listar hasta 50 mensajes después de un cursor, del más antiguo al más reciente
• GET /inboxes/{id}/messages/{message_id} Leer un mensaje: texto, códigos, enlaces y lista de adjuntos
• GET /inboxes/{id}/messages/{message_id}/attachments/{index} Descargar un adjunto por su índice
• DELETE /inboxes/{id} Eliminar de inmediato el buzón y sus mensajes

Las solicitudes de listado y de espera aceptan los filtros opcionales from y subject_contains: coincidencias de tipo «contiene» en el remitente y en el asunto, sin distinguir mayúsculas de minúsculas.

Ejemplo de respuesta de lectura

{
    "id": 42,
    "from": "no-reply@app.example",
    "subject": "Your verification code",
    "received_at": "2026-10-03T09:41:07+00:00",
    "text": "Your verification code is 482913.\nOr confirm: https://app.example/verify?token=8f3c",
    "text_truncated": false,
    "codes": [
        "482913"
    ],
    "links": [
        "https://app.example/verify?token=8f3c"
    ],
    "expires_at": "2026-10-03T10:40:12+00:00",
    "attachments": [
        {
            "index": 0,
            "filename": "receipt.pdf",
            "size": 48213
        }
    ],
    "untrusted_content": true
}

Tokens de desarrollador

Crea claves API en «Acceso de desarrollador» cuando hayas verificado tu correo. Una clave de lectura y escritura puede crear, leer y eliminar buzones; una clave de solo lectura puede listar, esperar, leer y descargar. Las claves caducan a los 90 días, una cuenta puede tener 10 claves activas y revocar una clave surte efecto de inmediato.

Cada clave se muestra una sola vez y solo se almacena como hash SHA-256. Revocar una clave no elimina sus buzones: las demás claves válidas de la cuenta conservan el acceso hasta que los buzones caduquen o se eliminen.

Esperar el siguiente correo sin sleep()

GET …/wait mantiene la solicitud abierta y responde en cuanto llega un mensaje, o al agotarse el tiempo de espera (como máximo 20 segundos) con status timeout. Pasa el next_cursor de la respuesta anterior como after para no leer nunca el mismo mensaje dos veces.

Un timeout no es un fallo de entrega: vuelve a esperar con el mismo cursor. Solo se ejecuta una espera por buzón, y una espera más reciente en el mismo buzón sustituye a la anterior; las esperas en buzones distintos se ejecutan en paralelo, hasta 2 a la vez por cuenta.

Pruebas de correo con Playwright, Cypress, pytest y CI

Da a cada test su propio buzón, dispara el correo de registro o de restablecimiento de contraseña de tu app, espéralo y haz tus aserciones sobre el código o el enlace. Elimina el buzón en el teardown.

Guarda la clave como secreto de CI, por ejemplo TEMPGENERATOR_TOKEN en GitHub Actions. Cypress puede hacer las mismas llamadas HTTP con cy.request, y la receta de Python de abajo funciona en pytest o en cualquier otro runner.

Playwright (TypeScript)

import { test, expect } from '@playwright/test';

const api = `${process.env.TEMPGENERATOR_URL}/developer-api/v1`;
const headers = { Authorization: `Bearer ${process.env.TEMPGENERATOR_TOKEN}`, Accept: 'application/json' };

async function call(path: string, method = 'GET') {
  const response = await fetch(api + path, { method, headers });
  if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
  return response.status === 204 ? null : response.json();
}

async function waitForCode(inboxId: string, after = 0): Promise<string> {
  for (let attempt = 0; attempt < 3; attempt++) {
    const result = await call(`/inboxes/${inboxId}/wait?after=${after}&timeout=20`);
    for (const summary of result.messages) {
      const message = await call(`/inboxes/${inboxId}/messages/${summary.id}`);
      if (message.codes.length) return message.codes[0];
    }
    after = result.next_cursor;
  }
  throw new Error('No verification code arrived');
}

test('signup sends a verification code', async ({ page }) => {
  const inbox = await call('/inboxes', 'POST');
  try {
    await page.goto('/signup');
    await page.getByLabel('Email').fill(inbox.address);
    await page.getByRole('button', { name: 'Create account' }).click();
    await page.getByLabel('Verification code').fill(await waitForCode(inbox.id));
    await expect(page.getByText('Welcome')).toBeVisible();
  } finally {
    await call(`/inboxes/${inbox.id}`, 'DELETE');
  }
});

GitHub Actions

- name: End-to-end tests
  run: npx playwright test
  env:
    TEMPGENERATOR_URL: https://www.tempgenerator.com
    TEMPGENERATOR_TOKEN: ${{ secrets.TEMPGENERATOR_TOKEN }}

Comprobación de registro en Python

Ejecútalo con tus variables de entorno configuradas. Muestra un buzón nuevo: envía un correo de registro a esa dirección desde tu propia app de pruebas y pulsa Enter. Espera hasta 15 segundos, muestra cada mensaje con sus códigos y enlaces, y elimina el buzón aunque falle la lectura.

import json, os
from urllib.request import Request, urlopen

base = os.environ["TEMPGENERATOR_URL"].rstrip("/") + "/developer-api/v1"
headers = {"Authorization": "Bearer " + os.environ["TEMPGENERATOR_TOKEN"],
           "Accept": "application/json"}

def request(path, method="GET"):
    with urlopen(Request(base + path, headers=headers, method=method), timeout=30) as response:
        return json.load(response) if response.status != 204 else None

inbox = request("/inboxes", "POST")
print(json.dumps(inbox), flush=True)
try:
    input()
    result = request("/inboxes/" + inbox["id"] + "/wait?after=0&timeout=15")
    print(json.dumps(result))
    for message in result["messages"]:
        detail = request("/inboxes/" + inbox["id"] + "/messages/" + str(message["id"]))
        print(json.dumps(detail))
finally:
    request("/inboxes/" + inbox["id"], "DELETE")

Servidor MCP para agentes de IA

Endpoint https://www.tempgenerator.com/mcp, autenticado con Authorization: Bearer <key>. Streamable HTTP con el protocolo 2026-07-28; los clientes más antiguos se atienden mediante el handshake 2025-11-25 o 2025-06-18.

Conecta tu cliente

Claude Code

claude mcp add --transport http tempgenerator-mail https://www.tempgenerator.com/mcp \
  --header "Authorization: Bearer $TEMPGENERATOR_TOKEN"

Cursor: .cursor/mcp.json

{
  "mcpServers": {
    "tempgenerator-mail": {
      "url": "https://www.tempgenerator.com/mcp",
      "headers": { "Authorization": "Bearer ${env:TEMPGENERATOR_TOKEN}" }
    }
  }
}

VS Code: .vscode/mcp.json

{
  "inputs": [
    { "type": "promptString", "id": "tempgenerator-token", "description": "TempGenerator API key", "password": true }
  ],
  "servers": {
    "tempgenerator-mail": {
      "type": "http",
      "url": "https://www.tempgenerator.com/mcp",
      "headers": { "Authorization": "Bearer ${input:tempgenerator-token}" }
    }
  }
}

Claude en la web y en la app de escritorio: añade un conector personalizado con la URL del endpoint, elige la opción sin inicio de sesión e incluye la cabecera de solicitud Authorization: Bearer <key>. Claude se conecta desde la nube de Anthropic, así que la URL debe ser accesible públicamente.

Herramientas

create_inbox

Crea un buzón privado y devuelve su id y su dirección.

list_messages

Lista resúmenes de mensajes después de un cursor, con filtros opcionales por remitente y asunto.

wait_for_message

Espera hasta 20 segundos el siguiente mensaje.

read_message

Lee el texto, los códigos, los enlaces y la lista de adjuntos de un mensaje.

delete_inbox

Elimina el buzón y sus mensajes.

Ejemplo de prompt

Crea un buzón temporal y dame su dirección. Después espera el correo de verificación de mi app de staging y dime el código.

Deja que los agentes completen registros solo en cuentas que te pertenezcan o que tengas autorización para usar. El correo recibido no es de confianza: el servidor nunca abre enlaces y los agentes nunca deben seguir instrucciones que encuentren en un mensaje.

SDK de MCP para Python

Probado con Python 3 y el paquete oficial mcp 2.3.0: pip install "mcp>=2.3,<3". Configura antes TEMPGENERATOR_URL y TEMPGENERATOR_TOKEN.

import asyncio, os

import httpx2
from mcp import Client
from mcp.client.streamable_http import streamable_http_client

async def main():
    url = os.environ["TEMPGENERATOR_URL"].rstrip("/") + "/mcp"
    headers = {"Authorization": "Bearer " + os.environ["TEMPGENERATOR_TOKEN"]}
    async with httpx2.AsyncClient(headers=headers, timeout=httpx2.Timeout(30, read=60)) as http:
        async with Client(streamable_http_client(url, http_client=http)) as client:
            print([tool.name for tool in (await client.list_tools()).tools])
            created = await client.call_tool("create_inbox", {})
            if created.is_error:
                raise RuntimeError(created.content)
            inbox = created.structured_content
            try:
                print("Send a test email to", inbox["address"])
                waited = await client.call_tool("wait_for_message", {"inbox_id": inbox["id"], "timeout": 20})
                for summary in waited.structured_content["messages"]:
                    message = await client.call_tool("read_message", {"inbox_id": inbox["id"], "message_id": summary["id"]})
                    print(message.structured_content["subject"], message.structured_content["codes"])
            finally:
                deleted = await client.call_tool("delete_inbox", {"inbox_id": inbox["id"]})
                if deleted.is_error:
                    raise RuntimeError(deleted.content)

asyncio.run(main())

Adjuntos

Al leer un mensaje obtienes el índice, el nombre de archivo y el tamaño de cada adjunto. Descarga uno con GET …/attachments/{index}: los archivos de hasta 10 MB se sirven como application/octet-stream con nombres de archivo saneados. Los clientes MCP ven la misma lista y descargan a través de este endpoint REST.

Cuándo usarlo en lugar de otras herramientas

Mailpit, MailHog y Ethereal capturan el correo que tu propia app envía a un servidor SMTP local o ficticio, algo ideal cuando controlas la configuración SMTP. Estos buzones son direcciones reales en un dominio público, así que cualquier remitente puede llegar a ellos: un servicio de terceros, un servidor de staging que usa tu proveedor de correo real o un flujo similar al de producción.

Las API de correo temporal de uso general, como mail.tm o Guerrilla Mail, están pensadas para direcciones desechables personales. Esta API está pensada para la automatización: claves con permisos y caducidad, un buzón por test, una espera acotada con long polling, detección de códigos y enlaces, y un servidor MCP.

No incluye: envío de correo, SMS, vistas previas de HTML o de spam, dominios personalizados ni inicio de sesión OAuth para clientes MCP.

Retención, límites y seguridad

Un dominio receptor puede fijar una duración más corta o un límite de mensajes más bajo.

Solo recepción. Trata el correo y los adjuntos como contenido no fiable; nada se abre automáticamente. Al eliminar un buzón, sus mensajes se borran de inmediato, y los buzones caducados se eliminan mediante una limpieza programada.

Preguntas frecuentes