Source: https://once-email.com/es/blog/temporary-email-api-testing-guide Pruebas e ingeniería · 7 ago 2026Actualizado 20 ago 2026 # Cómo usar una API de correo temporal sin crear pruebas inestables Diseño de pruebas con buzones aislados, consultas limitadas, tiempos máximos, correlación segura y limpieza determinista. [Equipo de ingeniería de Once Email, Once Email author Equipo de ingeniería de Once Email]() Revisado por Revisión editorial de Once Email Qué te ayuda a hacer esta guía El equipo obtiene un patrón de sondeo con presupuesto, correlación sin secretos y límites de cuota que puede adaptar a su API. Guía del artículo Por qué vale la pena leer este artículo **Análisis original** Modelamos el correo como un sistema asíncrono y separamos creación, espera, selección, validación y limpieza para eliminar dependencias compartidas. **Contexto de tendencias** Las suites CI paralelas y los proveedores con colas variables hacen que esperas fijas y buzones reutilizados fallen de forma intermitente. **Valor práctico** El equipo obtiene un patrón de sondeo con presupuesto, correlación sin secretos y límites de cuota que puede adaptar a su API. El correo es asíncrono. Una aplicación puede solicitar el envío correctamente y el mensaje tardar por colas, DNS, límites o filtros. Una prueba robusta acepta esa variabilidad dentro de un plazo, sin esperar indefinidamente ni consultar la API a máxima velocidad. ## [Un buzón por ejecución]() Crea una dirección única para cada caso o ejecución paralela. Reutilizar un buzón hace que mensajes antiguos satisfagan condiciones nuevas y que dos workers compitan por el mismo correo. Guarda el identificador del recurso, no dependas de reconocer una dirección por posición. No uses cuentas o destinatarios de producción. El entorno de ensayo debe dirigir únicamente a dominios aprobados para pruebas. ## [Separa los pasos]() Un flujo claro contiene: 1. crear buzón con una vigencia suficiente; 2. iniciar la acción en la aplicación; 3. consultar la lista con intervalo y límite total; 4. seleccionar por señales no secretas; 5. leer y validar el mensaje correcto; 6. eliminar el buzón y los datos asociados incluso si falla la prueba. Esta separación permite saber si el defecto está antes del proveedor, en entrega o en contenido. ## [Sondeo con presupuesto]() No uses una espera fija de diez segundos: será lenta cuando el mensaje llegue pronto e inestable cuando tarde más. Consulta periódicamente con un plazo máximo y, si la API lo requiere, retroceso gradual con pequeña variación aleatoria. Respeta ` 429 ` y cualquier cabecera de reintento. Establece también un máximo de solicitudes para que un fallo no consuma la cuota del equipo. La recepción ilimitada de mensajes no equivale a solicitudes ilimitadas. Pseudocódigo conceptual: ``` fecha_limite = ahora + 90 segundos intervalo = 2 segundos mientras ahora < fecha_limite: mensajes = listar(buzon) candidato = encontrar_por_asunto_y_marca(mensajes) si candidato: validar(candidato); terminar esperar(intervalo) fallar_con_diagnostico_sin_secretos() ``` ## [Correlación sin filtrar secretos]() Incluye en el evento de prueba un identificador aleatorio que pueda aparecer en el asunto o metadatos no sensibles. No utilices el propio código de verificación como correlación ni lo escribas en registros. Enmascara la dirección y conserva horas UTC, plantilla y estado. Seleccionar solo «el mensaje más reciente» es frágil. Filtra por destinatario, tipo esperado, ventana de tiempo y una marca controlada por la prueba. ## [Validaciones por capas]() Comprueba primero metadatos: remitente, asunto, fecha y número de adjuntos. Descarga el cuerpo solo cuando sea necesario. Analiza texto y HTML sin ejecutar contenido remoto. Para enlaces y códigos, valida presencia y forma, pero no imprimas el valor. Los adjuntos deben utilizar archivos inocuos generados para el caso. Comprueba nombre, MIME, tamaño y hash esperado. Elimina inmediatamente copias temporales. ## [Limpieza garantizada]() Coloca eliminación en un bloque final que se ejecute ante éxito, fallo o cancelación. Borra también la cuenta creada en la aplicación. Añade una tarea periódica para detectar recursos huérfanos sin depender de ella como mecanismo normal. El buzón puede caducar automáticamente, pero la prueba debería limpiarlo para liberar recursos y demostrar aislamiento. ## [Seguridad de claves y cuotas]() Guarda la clave API en el almacén secreto de CI, limita su acceso por proyecto y revócala si aparece en un registro. No la incluyas en URL, capturas o artefactos. Utiliza claves distintas por entorno cuando el proveedor lo permita. Define presupuestos de creación y de solicitudes. En Once Email, el contrato candidato contabiliza creación o cambio de buzón, mientras recibir y leer mensajes no consume esa cuota mensual; todos los endpoints conservan límites de velocidad. La documentación pública y la compra permanecen ocultas hasta completar el cierre comercial, por lo que no debes asumir disponibilidad sin confirmación. ## [Diagnóstico de un fallo]() Informa identificador de prueba, horas, número de consultas, último estado y fase fallida. No adjuntes cuerpos, códigos ni enlaces. Distingue timeout sin mensajes, mensaje inesperado, contenido incorrecto y error de limpieza: cada uno conduce a una investigación diferente. La estabilidad aparece cuando cada prueba controla su buzón, espera con límites, selecciona de forma inequívoca y limpia siempre. La [lista de pruebas de correo de extremo a extremo]() aporta las validaciones visuales, de accesibilidad y caducidad que complementan la API. ## [Diagnostica la etapa, no solo “no llegó el correo”]() Antes de activar CI, registra solo etapa, duración limitada, estado HTTP, ID de solicitud cuando exista, número de candidatos y un ID de ejecución sin secretos. No registres dirección, código, enlace, asunto, cuerpo, adjunto, clave de API ni consulta completa. Clasifica antes de repetir: disparador rechazado corresponde a la aplicación; entrega pendiente significa que venció el plazo; ` 429 ` o ` 503 ` debe respetar ` Retry-After `; varios candidatos indican correlación ambigua; destino controlado incorrecto es fallo de aserción; y un fallo de limpieza se informa por separado. Verifica además que el proveedor documente API, autenticación, borrado, caducidad y límites. Once Email aún no ofrece una API pública de producción: estos son patrones independientes del proveedor, no endpoints disponibles. ## [Usa un SDK sin ocultar el diseño de la prueba]() Once Email ofrece candidatos SDK probados para TypeScript, Python, Java, Go, .NET, PHP y Ruby. Empieza en la [página de SDK]() , elige el lenguaje que ya usa tu servicio y revisa su directorio de código; no añadas otro runtime solo para consultar un buzón. Los candidatos proceden de una GitHub Release inmutable, no de un registro. Compara el archivo con ` SHA256SUMS `, lee el README incluido y fija la versión. No se muestran comandos de npm, PyPI, Maven Central, NuGet, Packagist o RubyGems hasta que esas publicaciones existan. El SDK reduce serialización HTTP, pero no decide el plazo, la coincidencia ni la limpieza. Usa un buzón, un responsable de sondeo y un plazo por prueba autorizada; respeta ` Retry-After ` en ` 429 `, distingue ` 503 ` de buzón vacío, rechaza coincidencias ambiguas y elimina en ` finally `. Revisa también el [contrato API de solo recepción]() . ## Guías relacionadas Lista de pruebas de correo para desarrolladores: de la solicitud a la caducidad Un plan reproducible para comprobar generación, entrega, contenido, enlaces, adjuntos, accesibilidad y limpieza sin usar datos reales. [Lista de pruebas de correo para desarrolladores: de la solicitud a la caducidad]() Cómo guardar evidencias de pruebas de correo sin exponer secretos Qué conservar, qué ocultar y cómo demostrar un resultado sin archivar códigos, enlaces de acceso o mensajes completos. [Cómo guardar evidencias de pruebas de correo sin exponer secretos]() Postfix vs Dovecot: funciones distintas en un servidor de correo entrante Ubica Postfix, Dovecot, LMTP, la cola e IMAP en la ruta de entrada y decide con evidencias dónde falla una entrega. [Postfix vs Dovecot: funciones distintas en un servidor de correo entrante]() [Códigos de verificación por correo: cómo copiar, comprobar y usarlos con seguridad Un proceso para manejar códigos de un solo uso sin compartirlos, confundir mensajes antiguos ni dejar secretos en el portapapeles.]() [¿No llega el correo de verificación? Lista segura de diagnóstico Un orden de comprobación para encontrar un mensaje retrasado sin solicitar códigos repetidamente ni exponer información sensible.]()