UnCorreoTemporal /Documentación/API REST

API REST Reference

La API REST de UnCorreoTemporal permite crear y gestionar buzones temporales de forma programática. Base URL: https://uncorreotemporal.com/api/v1

1 Inicio rápido

Crea un buzón, envía un email y lee el contenido en menos de 5 líneas:

cURL — Flujo completo

# 1. Crear buzón (sin registro)
curl -X POST https://uncorreotemporal.com/api/v1/mailboxes      -H "Content-Type: application/json"

# Respuesta → guarda address y session_token
{ "address": "mango-panda-42@uncorreotemporal.com",
  "expires_at": "2026-03-02T15:00:00Z",
  "session_token": "a8f3k2..." }

# 2. Leer mensajes
curl https://uncorreotemporal.com/api/v1/mailboxes/mango-panda-42/messages      -H "X-Session-Token: a8f3k2..."

# 3. Leer un mensaje completo
curl https://uncorreotemporal.com/api/v1/mailboxes/mango-panda-42/messages/{id}      -H "X-Session-Token: a8f3k2..."

Autenticación

La API soporta dos métodos de autenticación:

Tipo	Header	Uso
API Key	`Authorization: Bearer uct_xxx`	Planes de pago — acceso completo
Session Token	`X-Session-Token: <token>`	Buzones anónimos — plan gratuito

Las API Keys se almacenan como hash SHA-256. El valor raw se muestra una única vez al crearse y nunca se persiste en logs.

POST

/mailboxes

Crea un nuevo buzón temporal. Sin autenticación genera un buzón anónimo con session_token. Con API key usa las cuotas del plan asociado.

Query params (opcionales)

ttl_minutes

Integer ≥ 1. TTL del buzón en minutos. Por defecto usa el TTL del plan. Máximo limitado por plan.

Respuesta 201

{
  "address": "slug@uncorreotemporal.com",
  "expires_at": "2026-03-02T15:00:00Z",
  "session_token": "a8f3k2..."
}

cURL

# Anónimo (sin header)
curl -X POST https://uncorreotemporal.com/api/v1/mailboxes

# Con API key y TTL de 2 horas
curl -X POST "https://uncorreotemporal.com/api/v1/mailboxes?ttl_minutes=120"      -H "Authorization: Bearer uct_xxxxx"

GET

/mailboxes

Lista todos los buzones activos del usuario autenticado. Requiere API key — no disponible para sesiones anónimas.

curl https://uncorreotemporal.com/api/v1/mailboxes      -H "Authorization: Bearer uct_xxxxx"

# Respuesta 200
[
  { "address": "slug@uncorreotemporal.com",
    "expires_at": "2026-03-02T15:00:00Z",
    "message_count": 5 }
]

DELETE

/mailboxes/{address}

Desactiva el buzón. Retorna 204 No Content. Los mensajes existentes se conservan hasta que expiren.

# Con API key
curl -X DELETE https://uncorreotemporal.com/api/v1/mailboxes/mango-panda-42      -H "Authorization: Bearer uct_xxxxx"

# Con session token (buzón anónimo)
curl -X DELETE https://uncorreotemporal.com/api/v1/mailboxes/mango-panda-42      -H "X-Session-Token: a8f3k2..."

GET

/mailboxes/{address}/messages

Lista los mensajes del buzón (sin body). Ordenados por received_at DESC.

Query params

limit — Integer 1-200, default 50

offset — Integer ≥ 0, default 0

Campos por mensaje

id, from_address, to_address
subject, received_at
is_read, has_attachments

curl "https://uncorreotemporal.com/api/v1/mailboxes/mango-panda-42/messages?limit=10"      -H "X-Session-Token: a8f3k2..."

GET

/mailboxes/{address}/messages/{id}

Retorna el mensaje completo incluyendo body_text, body_html y adjuntos. Marca el mensaje como leído automáticamente.

curl https://uncorreotemporal.com/api/v1/mailboxes/mango-panda-42/messages/550e8400-...      -H "X-Session-Token: a8f3k2..."

# Respuesta 200
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "from_address": "noreply@github.com",
  "subject": "Please verify your email address",
  "body_text": "Your verification code is 847291...",
  "body_html": "<html>...</html>",
  "attachments": [],
  "received_at": "2026-03-02T14:32:00Z",
  "is_read": true
}

DELETE

/mailboxes/{address}/messages/{id}

Elimina permanentemente un mensaje. Retorna 204 No Content.

curl -X DELETE      https://uncorreotemporal.com/api/v1/mailboxes/mango-panda-42/messages/550e8400-...      -H "X-Session-Token: a8f3k2..."

WebSocket — Tiempo real

Conecta al inbox y recibe notificaciones push en menos de 200ms cuando llega un nuevo email. Sin polling.

URL: wss://uncorreotemporal.com/ws/inbox/{address}?token={session_token}

Evento new_message

{
  "event": "new_message",
  "message_id": "550e8400-..."
}

Evento ping (keepalive)

{
  "event": "ping"
}

JavaScript

// 1. Crear buzón
const { address, session_token } =
  await fetch('https://uncorreotemporal.com/api/v1/mailboxes',
    { method: 'POST' }).then(r => r.json());

// 2. Conectar WebSocket
const ws = new WebSocket(
  `wss://uncorreotemporal.com/ws/inbox/${address}?token=${session_token}`
);

ws.onmessage = async ({ data }) => {
  const evt = JSON.parse(data);
  if (evt.event === 'new_message') {
    const msg = await fetch(
      `https://uncorreotemporal.com/api/v1/mailboxes/${address}/messages/${evt.message_id}`,
      { headers: { 'X-Session-Token': session_token } }
    ).then(r => r.json());
    console.log('Email de:', msg.from_address);
  }
};

Códigos de respuesta

Código	Significado
`200`	OK — respuesta exitosa
`201`	Created — buzón creado
`204`	No Content — eliminación exitosa
`400`	Bad Request — JSON inválido o parámetro incorrecto
`403`	Forbidden — token inválido o sin acceso al buzón
`404`	Not Found — buzón o mensaje no existe
`429`	Too Many Requests — cuota del plan agotada
`500`	Server Error — error interno

Siguiente: MCP Server