Ir a la documentación
API

Bandejas desechables

Una dirección funcional para quien no tiene ninguna: sin cuenta, sin clave y desaparecida el mismo día.

Qué es una bandeja desechable

Quien llama pide una dirección en un dominio que posee esta instalación, la vigila unos minutos, lee lo que llegue y la abandona. Existe para el código de confirmación, para la pregunta de «qué envía realmente este formulario» y para el registro que no quieres asociar a la dirección que seguirás usando dentro de cinco años.

  • Solo recibe, nada más. No hay envío: una bandeja de entrada no tiene identidad con la que enviar, y ninguna de estas nueve llamadas pondrá un mensaje en la red.
  • El arrendamiento es de 60 minutos por defecto y puede llevarse hasta 24 horas, de hora en hora.
  • Admite 50 mensajes, contados a medida que llegan. El correo que llega a una bandeja llena se descarta en lugar de encolarse, y eliminar uno no compra sitio para otro.
  • Al final del arrendamiento el correo se ELIMINA: no se oculta ni se archiva. La fila le sobrevive una semana para que la dirección no pueda reemitirse mientras un remitente lento siga reintentando hacia ella.
  • Nada de esto toca un buzón. Un mensaje desechable vive en su propia tabla, y ninguna consulta de esta ruta puede alcanzar uno real.

Estas son las mismas llamadas que hace la herramienta gratuita de este sitio, así que todo lo que puede hacer la página lo puede hacer tu código. La API está aquí para el caso en que la página no sirva: una batería de pruebas que quiere una dirección nueva en cada ejecución.

La dirección no es la credencial

Una dirección desechable se escribe en un formulario de registro en el mismo momento en que se emite. Desde ahí viaja en una cabecera To:, por los registros del remitente, y hasta el CRM que haya al otro lado. Si conocer la dirección bastara para leer el correo, la herramienta filtraría todas las bandejas que emitiera, por diseño, y precisamente a la parte que quien llamaba mantenía a distancia.

Por eso crear una bandeja devuelve un segundo valor: un token, 32 bytes aleatorios en forma de oe_inbox_ más 43 caracteres base64url. Aparece en esa única respuesta y en ninguna otra. La fila guarda solo un hash con clave del mismo, así que nada lo recupera: ni una solicitud de soporte ni un volcado de la base de datos. Pierde el token y habrás perdido la bandeja, que es el resultado correcto para una credencial que lee el correo de alguien.

El flujo completo
# 1. Mint one. This is the only response that carries a token.curl -s -X POST "$OE/temp-mail/inboxes" -H "Content-Type: application/json" -d '{}' # 2. Keep it, and read with it.export INBOX="Authorization: Bearer oe_inbox_kQ8v…"curl -s "$OE/temp-mail/inboxes/tinb_9c2f…/messages" -H "$INBOX"

Si envías una clave de API oe_live_ u oe_test_ a una de estas rutas, se rechaza como invalid_credential_type y no como un 401 escueto. Aquí dos tipos de credencial comparten un mismo host y una misma cabecera, y «no autorizado» te dejaría adivinando cuál de las tuyas estaba mal.

El arrendamiento y su ampliación

Una hora, en lugar de los diez minutos que dan nombre al género. Diez bastan para un código de confirmación y no bastan para la otra mitad de los usos: una prueba gratuita que te vuelve a escribir a la mañana siguiente, un formulario rellenado dos veces porque el primer intento caducó. ttlMinutes al crear pide otra cosa, de 1 a 1440; un número fuera de ese rango se rechaza con un 422 en lugar de ajustarse en silencio, porque una caducidad que no pediste es una con la que ya has contado.

POST /temp-mail/inboxes/{id}/extend añade una hora a la caducidad, no al momento actual, así que ampliar pronto no desperdicia el tiempo que te queda. Funciona 23 veces, y el día contado desde el momento en que se creó la bandeja es el más estricto de los dos topes: un arrendamiento que ya llega hasta él no tiene nada más que comprar, por pocas ampliaciones que se hayan gastado. extensionsLeft en cada respuesta de bandeja cuenta ambos, de modo que un cliente puede atenuar el botón; en cero, la llamada responde 409 extension_limit.

Una bandeja caducada deja de autenticar en el instante en que caduca: su token responde 404 sin esperar al barrido. El barrido es lo que elimina el correo, y se ejecuta en el cron horario; DELETE /temp-mail/inboxes/{id} es esa misma eliminación bajo demanda.

Los topes

Todos estos son recuentos de filas y no un limitador de velocidad. En este código no hay ningún limitador al que recurrir, y decirlo es más útil que insinuar una defensa que no existe. Están puestos donde estaría el daño: la acuñación y el almacenamiento.

TopeValorQué ocurre al alcanzarlo
Arrendamiento60 minutos, ampliable hasta 24 horas409 conflict_error / extension_limit
Mensajes por bandeja50El correo adicional se descarta en la puerta. No se escribe ningún rebote, no se encola nada, y eliminar un mensaje no devuelve la plaza.
Bandejas acuñadas6 por hora, 30 por día, por cliente429 rate_limit_error / too_many_inboxes
Cuerpo almacenado2 MBtruncated: true en el mensaje; el resto ha desaparecido.
Bytes de adjunto8 MB cada unocontent es null y se conservan los metadatos, lo que no es lo mismo que un archivo vacío.

El tope de acuñación se contabiliza contra un hash con clave de la IP del cliente, y una bandeja destruida sigue contando, así que tirar una no es forma de comprar otra. Detrás del proxy de otra persona se puede falsificar la cabecera reenviada, lo cual es una debilidad conocida del tope y no un agujero en la credencial: aquí nada autoriza en función de ese valor.

Lo que no está aquí

Aún no disponible

Descubrirlo probando es peor que que te lo digan:

  • Nada de envíos, de ninguna forma. Una bandeja desechable no tiene ninguna conexión con la que enviar, y añadir una convertiría un endpoint anónimo y sin autenticar en un relay abierto.
  • Nada de renombrar. Cambiar de dirección implica crear una segunda bandeja: renombrar sobre la marcha liberaría la antigua local-part en el instante en que se pulsara, y una confirmación que ya viniera en camino se entregaría a quien la recibiera a continuación.
  • Nada de reglas, filtros, reenvíos, webhooks ni IA. spam es una marca en el mensaje y nada actuó sobre ella. No se archivó nada, y aquí nada se resume ni se convierte en embeddings.
  • Nada de rebotes. El correo dirigido a un dominio del conjunto que no nombra ni una bandeja desechable activa ni una dirección creada por el operador se descarta en silencio, a propósito: un generador público de direcciones atrae ataques de diccionario, y escribir un informe de entrega a la ruta de retorno que el ataque declare convertiría la instalación en una fuente de backscatter.
  • Sin dominio configurado no hay servicio. Cuando TEMP_MAIL_DOMAINS está vacío, GET /temp-mail/domains responde con una lista vacía y crear una bandeja responde 503 temp_mail_unavailable. La entrega entrante a un dominio del conjunto no se ha observado de extremo a extremo en un dominio real.

Configurar un dominio, si administras la instalación

La lista es configuración: lo que nombre TEMP_MAIL_DOMAINS es lo que se reparte. Nada automatiza el DNS, así que cuatro de estos cinco pasos son una persona ante un registrador.

  1. Registra un dominio para ello. Usa uno que estés dispuesto a dejar que repartan desconocidos. Todas las direcciones de ese dominio comparten su reputación, que es también la razón por la que el selector reparte las bandejas nuevas al azar por todo el conjunto en lugar de llenar el primero.
  2. Añádelo en la aplicación, en Ajustes → Dominios. Eso acuña la identidad de envío e imprime los registros DNS que hay que publicar.
  3. Publica los registros MX, SPF, DKIM y el TXT _openemail-challenge en el registrador. La verificación lee el DNS en vivo y se vuelve a comprobar en el cron; solo se ofrece un dominio verificado.
  4. Añade el dominio verificado a TEMP_MAIL_DOMAINS en el servidor, separado por comas. Hasta que no esté en la lista, es un dominio corriente del espacio de trabajo.
  5. Deja catch-all ACTIVADO. Es lo que hace que una dirección desechable exista sin crearla, porque el correo dirigido a cualquier local part se acepta y se resuelve antes de la búsqueda de destinatario habitual, de modo que nunca se escribe una fila de dirección para un dominio del conjunto; dejar catch-all activado empezaría a archivar correo desechable en un buzón real.

Las local-parts reservadas (postmaster, abuse, security y el resto de RFC 2142) nunca pueden ser desechables y pasan en su lugar al buzón habitual. Un dominio del conjunto que se traga sus propios informes de abuso es un dominio que deja de poder entregar en ninguna parte. Una dirección que crees tú mismo en un dominio del conjunto, como legal@ o privacy@, se comporta igual: el correo dirigido a ella llega a tu buzón, y a nadie se le puede emitir como dirección desechable.

En esta sección