DEV Community: Olivia Cheng

FastAPI: clasifica fallos de correo en vez de reintentar

Olivia Cheng — Sat, 14 Nov 2026 20:23:21 +0000

Un endpoint de FastAPI que envía un correo suele empezar con una regla sencilla: si algo falla, reintenta. Funciona hasta que una dirección no existe, el proveedor responde con límite de frecuencia o la aplicación ya entregó el mensaje pero perdió la respuesta. En esos casos, repetir la misma llamada no arregla el problema; puede duplicar mensajes y esconder la causa.

Cuando automatizo flujos de backend, trato el envío como una operación con estados. Una dirección de correo desechable o una dirección normal puede servir para una prueba, pero el sistema debe saber si el error es temporal, permanente o desconocido. La palabra clave burner email address describe una necesidad de prueba frecuente, no una política de reintento.

El error no siempre significa que hay que reintentar

El primer paso es separar el fallo de transporte del resultado de negocio. Un timeout de red puede merecer un intento adicional. Un 400 porque falta un campo no lo merece. Un 202 Accepted tampoco confirma que el mensaje llegó: solo indica que el proveedor aceptó la petición.

Una clasificación pequeña suele ser suficiente:

transitorio: timeout, conexión cerrada o respuesta 429;
permanente: dirección inválida, credenciales rechazadas o plantilla inexistente;
ambiguo: se perdió la respuesta después de enviar la petición;
de negocio: el usuario ya verificó su cuenta o la solicitud está duplicada.

Sin esta separación, los fallos no es más fáciles de resolver con un bucle infinito. El reintento debe ser una decisión, no un reflejo.

Clasificar antes de decidir

Podemos representar el resultado del proveedor con un modelo pequeño. No hace falta crear una jerarquía compleja de excepciones para cada código.

from enum import StrEnum
from pydantic import BaseModel


class DeliveryClass(StrEnum):
    TRANSIENT = "transient"
    PERMANENT = "permanent"
    AMBIGUOUS = "ambiguous"


class DeliveryResult(BaseModel):
    classification: DeliveryClass
    provider_code: str | None = None
    message_id: str | None = None

Después, la función que llama al proveedor convierte respuestas concretas en este contrato. El resto de la aplicación no necesita conocer cada peculiaridad del SDK. Esta frontera tambien facilita las pruebas: se pueden simular un 429, un timeout y una respuesta ambigua sin levantar un servidor de correo completo.

Un pequeño contrato de errores en FastAPI

El endpoint debe devolver una respuesta estable al cliente, aunque internamente el envío sea asíncrono. Por ejemplo, una petición de verificación puede devolver 202 con un identificador de operación. El cliente consulta el estado, y el worker decide si reintenta.

from fastapi import FastAPI, status
from pydantic import BaseModel, EmailStr

app = FastAPI()


class VerificationRequest(BaseModel):
    email: EmailStr


@app.post("/verification", status_code=status.HTTP_202_ACCEPTED)
async def request_verification(payload: VerificationRequest) -> dict[str, str]:
    operation_id = await enqueue_verification(payload.email)
    return {"operation_id": operation_id, "state": "queued"}

La cola debe conservar una clave idempotente, por ejemplo verification:{user_id}:{purpose}. Así, si el worker no sabe si la primera llamada terminó, puede consultar o repetir con la misma clave. Cada reintento tienen que conservar el mismo identificador de operación; generar uno nuevo crea dos historias que luego nadie puede unir.

Automatizar reintentos con límites

Un worker práctico usa tres límites: número de intentos, tiempo total y tipo de error. Un 429 puede esperar con backoff, mientras que una dirección inválida debe terminar en una cola de revisión o en un estado visible para el usuario.

async def deliver(job: VerificationJob) -> DeliveryResult:
    for attempt in range(3):
        result = await provider.send(job.message, idempotency_key=job.key)
        if result.classification != DeliveryClass.TRANSIENT:
            return result
        await asyncio.sleep(2**attempt)
    return DeliveryResult(classification=DeliveryClass.AMBIGUOUS)

El backoff no es una garantía de entrega. Es solo una forma de no concentrar tráfico cuando el proveedor está lento. Si la respuesta sean ambiguo después del límite, guarda la operación para una reconciliación posterior; no la marques como entregada.

Observabilidad útil para el equipo

Los logs deben responder tres preguntas: qué operación falló, en qué estado quedó y quién puede actuar. Registra operation_id, clasificación, código del proveedor, número de intento y duración. Evita el cuerpo completo del mensaje y los tokens de verificación.

También conviene medir la proporción de cada clase. Un aumento de errores permanentes puede indicar datos malos en el formulario. Muchos ambiguos pueden apuntar a un timeout demasiado corto. Sus logs queda mucho más útil cuando distinguen esas dos situaciones.

En CI, la misma idea evita limpiar evidencia importante junto con datos sensibles. Puedes complementar este flujo con una guía para probar alertas después de un cambio de red y con prácticas para limpiar datos de email en CI sin perder señales. Si una búsqueda informal dice “fake e mail com”, documenta el término como entrada de prueba, pero no lo conviertas en una decisión técnica.

Checklist y preguntas frecuentes

Antes de publicar el endpoint, revisa:

¿Cada error tiene una clasificación explícita?
¿El reintento está limitado por tiempo y cantidad?
¿La operación tiene una clave idempotente?
¿Se puede reconciliar un resultado ambiguo?
¿Los logs excluyen tokens y cuerpos de correo?
¿Las pruebas cubren 429, timeout, 400 y duplicados?

¿Debo reintentar cualquier error 5xx? No siempre. Un 5xx puede ser temporal, pero si el proveedor ya aceptó la operación y solo falló la respuesta, repite únicamente con idempotencia o consulta el estado primero.

¿Es suficiente comprobar que existe un message_id? No. Es una señal de aceptación, no necesariamente de entrega. Conserva el estado del proveedor cuando esté disponible y define qué significa “entregado” para tu producto.

¿Qué hago con una dirección inválida? Marca el fallo como permanente, evita reintentos automáticos y muestra una acción clara. Reintentar datos que no van a cambiar solo consume cuota y ensucia las métricas.

La automatización gana calidad cuando cada fallo tiene un significado operativo. En FastAPI, un contrato pequeño, una clave idempotente y límites visibles suelen aportar más que otro bucle de reintento escondido en el cliente.

FastAPI: contratos de eventos para emails de prueba

Olivia Cheng — Sat, 14 Nov 2026 02:23:38 +0000

Probar un flujo de registro suele parecer sencillo: crear un usuario, esperar un email y abrir el enlace. En CI, sin embargo, “esperar” es una operación ambigua. El mensaje puede llegar tarde, otro worker puede leerlo primero o una prueba anterior puede dejar basura en el inbox.

La solución que más me funciona es tratar cada envío como un evento con contrato propio. No hace falta construir una plataforma enorme. Con FastAPI, una clave de correlación y un pequeño registro de estados podemos hacer que un generador de correos falsos sea útil para probar el backend, no solo para mirar si apareció un mensaje.

El problema: esperar un email no es un contrato

Un test que hace sleep(5) solo expresa una esperanza. No sabe cuándo se solicitó el email, cuál era el destinatario esperado ni si el mensaje encontrado pertenece a la ejecución actual. Cuando falla, el equipo recibe un timeout y poco mas.

Conviene separar tres momentos:

La aplicación acepta la solicitud de envío.
El proveedor o adaptador registra el evento de entrega.
El test encuentra el mensaje correcto y consume el enlace.

Cada momento debe tener un identificador común. Así se puede distinguir “el email todavía no llegó” de “el email llegó, pero el enlace ya fue consumido”. Esa diferencia parece pequeña, pero cambia por completo el diagnóstico.

También ayuda a que la interfaz muestre estados de interfaz que explican el resultado, en vez de esconder un estado pendiente detrás de un spinner infinito.

Diseñar un evento pequeño y trazable

Un contrato mínimo puede tener esta forma:

from datetime import datetime
from pydantic import BaseModel, EmailStr


class EmailEvent(BaseModel):
    event_id: str
    recipient: EmailStr
    kind: str
    created_at: datetime
    status: str = "queued"

El event_id no debe generarse de nuevo cuando se reintenta la misma operación. El cliente puede enviarlo como clave de idempotencia y el servidor lo guarda junto con el estado. Si llega la misma petición, la API devuelve el evento existente en lugar de crear dos emails.

En pruebas, kind también es importante. “welcome” y “verify-account” pueden terminar en el mismo inbox, pero no tienen el mismo asunto ni la misma acción. Un filtro por tipo es mas resistente que buscar solo la palabra “verify”.

Implementación de un endpoint FastAPI

El endpoint puede aceptar el evento y entregar un estado claro al worker que enviará el mensaje:

from fastapi import FastAPI, status

app = FastAPI()


@app.post("/email-events", status_code=status.HTTP_202_ACCEPTED)
async def create_email_event(event: EmailEvent):
    stored = await event_store.get(event.event_id)
    if stored:
        return stored

    await event_store.insert(event)
    await email_queue.publish(event.event_id)
    return event

El ejemplo omite la base de datos y la cola para mantener la idea enfocada. En producción, la inserción y la publicación necesitan una estrategia consistente; de lo contrario puede guardarse el evento y perderse la tarea. Para muchos equipos, un outbox transaccional es un buen siguiente paso.

El endpoint esperan una respuesta rápida: 202 Accepted significa que la solicitud fue aceptada, no que el email ya está en el inbox. Documentar esta diferencia evita que un test intente leer el mensaje inmediatamente y declare una falla que no existe.

Polling con identidad y límite

El test debe buscar por event_id, destinatario, tipo y una ventana de tiempo. Un bucle pequeño es más confiable que un sleep fijo:

for attempt in range(8):
    message = await inbox.find(
        recipient=event.recipient,
        kind=event.kind,
        event_id=event.event_id,
    )
    if message:
        assert message.link
        break
    await asyncio.sleep(1)
else:
    raise AssertionError(f"Email no encontrado: {event.event_id}")

Ocho intentos de un segundo son solo un ejemplo; el límite debe salir del tiempo normal de entrega de tu entorno. Lo importante es guardar cada respuesta observada. Si una prueba escribe “temp mailid” por un error de configuración, ese texto puede aparecer en los logs como pista, pero no debe convertirse en una palabra clave del contrato.

Para evitar carreras entre workers, el adaptador del inbox puede marcar el mensaje como reservado usando event_id. Si dos pruebas consultan a la vez, solo una consume el enlace. La limpieza ocurre despues de capturar el resultado, no antes.

Cómo automatizar la evidencia en CI

Cuando el flujo falla, guarda un recibo pequeño:

event_id, commit y nombre del job;
estado del evento y timestamps;
asunto, destinatario enmascarado y message ID;
cantidad de intentos y última respuesta del inbox;
motivo de expiración o consumo duplicado.

No guardes el cuerpo completo si no es necesario. Una evidencia útil debe ayudar a reproducir el problema sin convertir datos de prueba en un archivo permanente. Un SLO útil para emails de CI también puede separar latencia de entrega y disponibilidad del adaptador.

La automatización queda mas simple cuando cada job crea su propio evento y elimina sus fixtures al terminar. Si el worker muere, el estado queda pendiente; un proceso de reconciliación puede marcarlo como expirado y dejar una razón. No conviene reintentar sin mirar el estado anterior: eso produce duplicados y hace el fallo menos visible.

Preguntas frecuentes

¿Necesito una cola para empezar?

No siempre. Para un servicio pequeño, un BackgroundTasks puede servir como primer adaptador. Cuando haya varios workers o reintentos, una cola con una clave de idempotencia será mas segura.

¿Por qué no basta con buscar por asunto?

Porque dos ejecuciones pueden usar el mismo asunto. El asunto es una señal humana; event_id es la identidad técnica que permite automatizar.

¿Qué debe probar el test?

Primero que la API acepta y registra el evento. Después, en una prueba de integración, que llega el mensaje correcto, el enlace funciona una vez y un reintento no crea otra identidad. Ese reparto hace los tests mas rápidos y los fallos mucho más explicables.

Un contrato de eventos no elimina la latencia de email. Lo que hace es convertir una espera opaca en una secuencia observable: solicitado, entregado, encontrado, consumido o expirado. Para un backend FastAPI, esa claridad suele valer más que añadir otro retry al azar.

FastAPI: clasifica fallos de email sin reintentar a ciegas

Olivia Cheng — Fri, 13 Nov 2026 05:23:36 +0000

En una API que envía emails, el reintento suele parecer la solución más fácil: si la entrega falla, esperamos un poco y repetimos. El problema aparece cuando tratamos igual un timeout, una dirección inválida y una bandeja temporal que todavía no ha recibido el mensaje. El sistema insiste, aumenta el ruido y al final nadie sabe qué ocurrió realmente.

En proyectos con FastAPI me resulta más útil clasificar el fallo antes de decidir la siguiente acción. Así una automatización puede reintentar un problema transitorio, detenerse ante un error permanente y dejar el caso en revisión cuando falta información. Es un cambio pequeño, pero hace que las APIs sean más previsibles.

El error no siempre merece otro intento

Hay tres familias que conviene separar desde el principio:

Transitorio: timeout, conexión reiniciada o respuesta 5xx del proveedor. Puede merecer un reintento con límite.
Permanente: formato inválido, dominio inexistente o credenciales rechazadas. Repetirlo no lo arregla.
Indeterminado: el proveedor aceptó la solicitud, pero la respuesta se perdió. Aquí hace falta una consulta de estado o una clave de idempotencia.

El objetivo no es adivinar el futuro. Es evitar que el código convierta cualquier excepción en una orden de “hazlo otra vez”. Una función de dominio puede devolver una decisión clara: retry, stop o review.

Clasifica antes de reintentar

Podemos representar la decisión con un modelo pequeño. No hace falta construir un sistema de reglas enorme para empezar:

from enum import StrEnum
from pydantic import BaseModel


class NextAction(StrEnum):
    RETRY = "retry"
    STOP = "stop"
    REVIEW = "review"


class DeliveryDecision(BaseModel):
    action: NextAction
    reason: str
    retry_after_seconds: int | None = None


def decide_delivery(status_code: int | None, attempts: int) -> DeliveryDecision:
    if attempts >= 3:
        return DeliveryDecision(action=NextAction.REVIEW, reason="límite alcanzado")
    if status_code is None or status_code >= 500:
        return DeliveryDecision(
            action=NextAction.RETRY,
            reason="fallo transitorio",
            retry_after_seconds=2 ** attempts,
        )
    if status_code in {400, 401, 403, 422}:
        return DeliveryDecision(action=NextAction.STOP, reason="fallo permanente")
    return DeliveryDecision(action=NextAction.REVIEW, reason="respuesta no clasificada")

La regla importante está en el orden. Primero se comprueba el límite de intentos y después el tipo de respuesta. Si no, un proveedor que devuelve 503 puede generar una cadena de reintentos infinita. El backoff es sencillo a propósito; luego se le puede añadir un poco de jitter para que varios workers no vuelvan al mismo tiempo.

Un endpoint pequeño en FastAPI

La API no tiene que conocer todos los detalles del proveedor. Puede recibir el resultado normalizado de un worker y exponer la decisión para que el siguiente paso sea explícito:

from fastapi import FastAPI

app = FastAPI()


@app.post("/deliveries/{delivery_id}/decision", response_model=DeliveryDecision)
def delivery_decision(delivery_id: str, status_code: int | None = None, attempts: int = 0):
    # En producción, delivery_id debería resolver el estado persistido.
    return decide_delivery(status_code, attempts)

En producción validaría que delivery_id existe, limitaría attempts recibido por el cliente y guardaría la decisión junto al evento original. El endpoint es un ejemplo del contrato, no una invitación a confiar en datos enviados sin autenticación.

También ayuda separar la entrega de la observación. Un aviso de email con contexto real necesita decir qué evento falló, qué intento era y qué acción se tomó. La interfaz que consume la API no debería recibir solo “error 500”.

Registra la decisión, no solo la excepción

Para depurar una automatización, guardaría al menos estos campos:

delivery_id, event_id, attempt, provider_status,
classification, next_action, retry_after, created_at

No conviene registrar el contenido completo del mensaje ni tokens de acceso. Un identificador de evento y una razón corta suelen bastar. Si el test usa un temp org mail o un dummy e mail, la fixture debe quedar aislada del correo real y tener una caducidad conocida.

En esta parte, el polling también necesita límites sanos: duración máxima, intervalo y condición de salida. Una espera que no sabe cuándo terminar es una fuga de tiempo escondida dentro del test.

Pruebas para automatizaciones previsibles

Las pruebas unitarias deben cubrir la tabla de decisiones, no únicamente el camino feliz:

def test_timeout_retries_with_backoff():
    result = decide_delivery(None, attempts=1)
    assert result.action == NextAction.RETRY
    assert result.retry_after_seconds == 2


def test_invalid_address_stops():
    result = decide_delivery(422, attempts=0)
    assert result.action == NextAction.STOP


def test_max_attempts_goes_to_review():
    result = decide_delivery(503, attempts=3)
    assert result.action == NextAction.REVIEW

Para una prueba de integración, simularía una respuesta 503 seguida de 202 y comprobaría que solo hay dos llamadas. Después probaría un 422 y verificaría que no aparece una segunda llamada. Es facil olvidar este último caso cuando todo el entorno de pruebas responde demasiado bien.

Si el flujo tiene una interfaz web, vale la pena conectar el estado backend con mensajes comprensibles. Un estado “revisar” es mejor que un spinner eterno; este tipo de detalle también aparece al diseñar avisos de email con contexto real. Para comprobar la bandeja, puedes aplicar polling de inbox con límites sanos.

Q&A: dudas habituales

¿Debo reintentar todos los errores 5xx?

No necesariamente. Un 5xx suele ser transitorio, pero el proveedor puede estar rechazando una operación por saturación o por una cuota. Usa un máximo de intentos, backoff y una ruta de revisión. Si existe un encabezado Retry-After, úsalo dentro de un límite razonable.

¿Qué hago si no recibo respuesta?

Trátalo como indeterminado. Antes de enviar otra vez, consulta el estado con un identificador idempotente. Duplicar un email porque se perdió la respuesta es peor que tardar unos segundos en confirmar.

Checklist de implementación

Define las categorías transitorio, permanente e indeterminado.
Pon un límite de intentos fuera del proveedor.
Devuelve una acción explícita: reintentar, detener o revisar.
Registra evento, intento y decisión sin guardar datos innecesarios.
Añade backoff y, cuando aplique, Retry-After.
Prueba una secuencia 5xx → éxito y otra con error permanente.
Establece un timeout para cada polling y para el flujo completo.

La automatización de email no necesita más reintentos, sino mejores decisiones. Cuando FastAPI expone un contrato pequeño y cada fallo deja evidencia suficiente, los workers pueden recuperarse sin ocultar los casos que necesitan atención humana.

FastAPI: un contrato de expiración para emails de prueba

Olivia Cheng — Tue, 10 Nov 2026 20:23:58 +0000

En una prueba de registro o recuperación de contraseña, crear un email temporal suele parecer la parte fácil. El problema aparece después: el buzón queda vivo, otro test lo reutiliza y nadie sabe cuándo se puede borrar. En CI, esa pequeña ambigüedad termina en pruebas intermitentes y datos que se acumulan.

Una solución práctica es tratar cada buzón de prueba como un recurso con contrato de expiración. No hace falta construir una plataforma enorme. Con FastAPI, un identificador de ejecución, una fecha límite y una tarea de limpieza se puede hacer el comportamiento mucho más predecible.

El problema: un buzón de prueba que nunca muere

Un flujo típico hace esto:

Crea una dirección temporal.
La entrega al navegador o al cliente API.
Espera el mensaje de confirmación.
Comprueba el enlace.
Abandona el recurso.

El quinto paso es el que suele faltar. Si el test pasa, nadie se acuerda del buzón. Si falla, el diagnóstico puede dejar varios recursos abiertos. Y si dos ejecuciones usan el mismo identificador, una limpieza puede borrar los datos que todavía necesita la otra.

También aparecen entradas poco útiles en los logs cuando alguien escribe tempail mail o tepm mail com y termina probando otra configuración. Parece pequeño, pero después cuesta saber qué dato pertenece a cada corrida.

Conviene separar tres conceptos: propietario, caducidad y estado. El propietario identifica la ejecución que creó el recurso; la caducidad dice hasta cuándo es válido; el estado distingue entre activo, consumido y expirado. Esta separación también ayuda a aislar las pruebas de email por entorno.

Qué debe prometer el contrato

Antes de escribir endpoints, define promesas pequeñas y verificables:

Cada recurso pertenece a un run_id único.
La fecha expires_at se calcula en el servidor, no en el navegador.
Leer mensajes después de expirar devuelve un error claro.
Repetir la operación de expiración no rompe nada.
La limpieza no toca recursos de otra ejecución.

No es un sistema de correo de producción. Es una frontera de datos para testing. Por eso el contrato debe ser sencillo, observable y fácil de borrar. Para flujos más automáticos, también merece la pena pensar en límites seguros para automatizar email.

Los nombres de estado importa más de lo que parecen: si son vagos, cada cliente interpreta el ciclo de vida a su manera. Al principio parece un poco más trabajo, pero ahorra conversaciones raras en el equipo.

Un modelo pequeño en FastAPI

Este ejemplo usa memoria para mostrar la idea. En un servicio real, la misma información iría a PostgreSQL o Redis, con un índice por run_id y expires_at.

from datetime import datetime, timedelta, timezone
from uuid import uuid4

from fastapi import FastAPI, HTTPException

app = FastAPI()
mailboxes: dict[str, dict] = {}
TTL_MINUTES = 15


def now() -> datetime:
    return datetime.now(timezone.utc)


@app.post("/test-mailboxes")
def create_mailbox(run_id: str):
    mailbox_id = str(uuid4())
    expires_at = now() + timedelta(minutes=TTL_MINUTES)
    mailboxes[mailbox_id] = {
        "run_id": run_id,
        "status": "active",
        "expires_at": expires_at,
        "messages": [],
    }
    return {"id": mailbox_id, "expires_at": expires_at}


@app.get("/test-mailboxes/{mailbox_id}/messages")
def list_messages(mailbox_id: str):
    mailbox = mailboxes.get(mailbox_id)
    if mailbox is None:
        raise HTTPException(status_code=404, detail="mailbox not found")
    if mailbox["expires_at"] <= now():
        mailbox["status"] = "expired"
        raise HTTPException(status_code=410, detail="mailbox expired")
    return {"messages": mailbox["messages"]}

El código usa UTC y responde 410 Gone cuando el recurso ya no debe utilizarse. Ese detalle es más útil que devolver una lista vacía: el test sabe si debe reintentar la espera o crear un buzón nuevo. Un detalle que se olvida facil es no mezclar datetime sin zona horaria con valores UTC; tarde o temprano produce comparaciones raras.

Expirar sin carreras ni borrados peligrosos

La expiración no debería depender de que un test llame a un endpoint final. Añade un trabajo periódico que busque recursos vencidos y los marque o borre. Pero hazlo con una condición que incluya la fecha límite:

DELETE FROM test_mailboxes
WHERE expires_at <= CURRENT_TIMESTAMP
  AND status IN ('active', 'consumed');

Si una ejecución todavía está leyendo un mensaje, puedes preferir una fase de gracia: primero marcas expired, esperas unos segundos y después borras. En Redis, un TTL puede servir para el almacenamiento, pero conserva también run_id en los datos para poder auditar qué pasó.

La limpieza ocurren después de la expiración, no antes de que venza el plazo. Esa diferencia evita que un job lento pierda su evidencia justo cuando más la necesita.

La operación debe ser idempotente. Ejecutar el limpiador una vez o cinco veces debe dejar el mismo resultado. También conviene registrar mailbox_id, run_id, motivo y duración de vida; esos cuatro campos dan una pista bastante buena cuando el CI falla de noche.

Evita renovar el TTL en cada lectura. Si el test está bloqueado esperando un mensaje, podría mantener el recurso vivo para siempre. El contrato debe tener una fecha máxima que solo un endpoint explícito y autorizado pueda extender, si de verdad hace falta.

Si el consumidor se queda esperando por mucho tiempo, devuelve un estado intermedio y registra el intento; no lo dejes esperando para siempre. Es una regla sencilla, pero suele olvidarse facil cuando el flujo feliz funciona.

Q&A rápido

¿Por qué no devolver siempre una lista vacía?

Porque una lista vacía puede significar “el email todavía no llegó” o “el buzón ya no existe”. Diferenciar 200, 404 y 410 hace que el cliente tome decisiones más sanas.

¿Es suficiente un `run_id`?

Es una buena base, pero debe ser impredecible entre ejecuciones y no contener datos personales. Añade un índice y comprueba la propiedad antes de leer o borrar.

¿Qué TTL conviene usar?

Empieza con el tiempo máximo real de la prueba más un margen pequeño, por ejemplo 15 minutos para un flujo que normalmente tarda dos. Mídelo después: un TTL gigante solo es una forma lenta de esconder fugas.

Checklist para llevarlo a CI

Genera un run_id nuevo por job y por intento.
Guarda expires_at en UTC y devuelve la fecha al cliente.
Devuelve 410 para un buzón vencido.
Ejecuta una limpieza periódica y otra al terminar el job.
No reutilices direcciones entre pruebas paralelas.
Prueba la doble expiración y la lectura durante la limpieza.
Conserva métricas de recursos activos, vencidos y borrados.

El objetivo no es simular cada detalle de un proveedor de correo. Es hacer explícito el ciclo de vida del dato temporal. Cuando FastAPI expone esa frontera con estados claros, los tests dejan de depender de suerte y la automatización se vuelve un poco más tranquila, incluso cuando algo falla.

FastAPI: un reloj para emails de prueba

Olivia Cheng — Sun, 08 Nov 2026 17:23:43 +0000

FastAPI: un reloj para emails de prueba

Los flujos de registro y recuperación de contraseña suelen fallar por una razón poco visible: nadie ha definido cuanto tiempo debe esperar el sistema por un email. En local, un correo llega enseguida. En CI, la misma prueba puede quedarse esperando, reintentando y dejando datos dificiles de interpretar.

Un correo electrónico desechable o un generador de cuentas de correo temporal puede ayudar a aislar cada ejecución, pero no resuelve por si solo el problema del tiempo. En este artículo propongo un patrón pequeño con FastAPI: tratar el reloj como parte del contrato de la automatización.

Por qué el tiempo es parte del contrato del email

Una prueba de verificación no solo necesita una dirección. Necesita saber:

cuándo se creó el buzón temporal;
cuánto tiempo puede esperar el primer mensaje;
cuántos reintentos están permitidos;
qué evidencia se guarda cuando no llega nada.

Sin estos límites, un sleep(10) termina siendo una política escondida. A veces es demasiado corto y produce un falso fallo; otras veces es demasiado largo y hace lenta toda la suite. El resultado parece aleatorio, aunque el problema real es que la prueba no tiene un deadline explicito.

La automatización gana claridad cuando cada ejecución tiene un run_id, un límite de tiempo y un estado final. Así es mas fácil distinguir entre “el proveedor tardó”, “el webhook llegó tarde” y “la aplicación nunca solicitó el mensaje”.

Un modelo pequeño de deadline en FastAPI

Podemos representar el contrato con un modelo de Pydantic y calcular el tiempo restante antes de cada espera. El ejemplo no depende de un proveedor concreto; la función read_inbox puede ser un cliente HTTP interno o un adaptador de pruebas.

from datetime import datetime, timedelta, timezone
from pydantic import BaseModel, Field


class EmailLease(BaseModel):
    run_id: str
    address: str
    created_at: datetime
    deadline_seconds: int = Field(default=45, ge=1, le=300)

    def expires_at(self) -> datetime:
        return self.created_at + timedelta(seconds=self.deadline_seconds)

    def remaining_seconds(self) -> float:
        now = datetime.now(timezone.utc)
        return max(0.0, (self.expires_at() - now).total_seconds())

El endpoint puede recibir una solicitud de lectura y devolver un estado explícito. No conviene bloquear una petición web durante toda la espera; para una suite de integración, un worker o una tarea de fondo suele ser mejor. Aun así, el mismo contrato sirve para ambos caminos.

from fastapi import FastAPI, HTTPException

app = FastAPI()


@app.get("/runs/{run_id}/email-status")
async def email_status(run_id: str):
    lease = await load_lease(run_id)
    if lease is None:
        raise HTTPException(status_code=404, detail="run_id desconocido")

    remaining = lease.remaining_seconds()
    if remaining <= 0:
        return {"run_id": run_id, "status": "expired", "remaining": 0}

    message = await read_inbox(lease.address, timeout=min(remaining, 5))
    if message is None:
        return {"run_id": run_id, "status": "waiting", "remaining": round(remaining, 2)}

    return {"run_id": run_id, "status": "received", "message_id": message.id}

En producción, load_lease y read_inbox necesitan límites propios y manejo de errores. El punto importante es que nunca deben esperar más que el tiempo que queda en el contrato.

Separar espera, reintentos y evidencia

Un timeout no debe decidir por accidente cuánto reintentar. Son tres decisiones distintas:

Espera: cuánto dura una lectura individual, por ejemplo cinco segundos.
Reintento: cuántas lecturas se permiten antes del fallo, por ejemplo nueve.
Evidencia: qué se registra en cada intento: run_id, número de intento, tiempo restante y resultado.

Para depurar, guardo un evento compacto por intento. No guardo el contenido completo del correo si no hace falta. Esta separación hace mas simple comparar dos ejecuciones y evita que un log lleno de ruido esconda el fallo.

También conviene usar un idempotency key al pedir el mensaje de prueba. Si el worker se reinicia, no debería crear tres buzones por el mismo escenario. Un nombre como signup:{run_id} permite localizar los datos y limpiarlos después.

Si el equipo busca una implementación de colas, este enfoque combina bien con unas colas de email con trazas útiles. Y cuando una ejecución sí termina en incidente, los correos de incidentes sin ruido operativo ofrecen una buena referencia para decidir qué contexto conservar.

Cómo probar el reloj sin pruebas lentas

No hace falta esperar 45 segundos en cada test. Inyecta un reloj y un lector de bandeja falsos. Para una prueba, el reloj puede empezar en 12:00:00; el primer intento devuelve None, el segundo también y el tercero devuelve un mensaje. Otra prueba avanza el reloj más allá del deadline y verifica expired.

El test debe comprobar el comportamiento, no los segundos exactos de una máquina compartida. Un esquema útil es:

crea una lease con un deadline de 10 segundos;
simula dos lecturas sin mensaje;
devuelve un mensaje con el tercer intento;
verifica que el estado final es received;
verifica que cada lectura recibió un timeout menor o igual al tiempo restante.

Para documentación y datos de ejemplo, algunas personas escriben nombres como dummy e mail o temp gamil com. Pueden servir para probar búsqueda y validación, pero mantenlos como texto de prueba, nunca como direcciones reales ni como una regla de negocio.

Checklist para automatización estable

[ ] Cada ejecución tiene un run_id único.
[ ] La lease guarda creación y expiración.
[ ] El timeout de lectura respeta el tiempo restante.
[ ] Los reintentos tienen un máximo explícito.
[ ] Los eventos registran resultado y contexto mínimo.
[ ] Los tests usan reloj y lector inyectables.
[ ] Un proceso de limpieza elimina buzones y mensajes expirados.

Este patrón es pequeño, pero cambia la conversación del equipo. En lugar de preguntar “¿por qué a veces falla el email?”, podemos preguntar “¿en qué estado terminó la lease y cuánto tiempo quedaba?”. Esa pregunta suele llevar mas rápido a la causa.

Preguntas frecuentes

¿Debo hacer polling o usar webhooks?

Usa webhooks si el proveedor y tu entorno los soportan de forma fiable. Mantén un polling acotado como respaldo para pruebas locales o servicios que no tienen eventos. En ambos casos, el deadline debe ser único y visible.

¿Un buzón temporal sustituye las pruebas de email reales?

No. Es útil para flujos de integración, aislamiento y datos efímeros. Las pruebas de entrega, reputación y compatibilidad de plantillas necesitan otros entornos y destinatarios controlados.

¿Qué métrica empezaría a medir?

Mide el tiempo desde la solicitud hasta la recepción, la tasa de expiración y el número de reintentos. Separar esos valores revela si el cuello de botella está en FastAPI, en la cola o en el proveedor de correo.

FastAPI: eventos de email sin polling ciego

Olivia Cheng — Sat, 07 Nov 2026 14:23:32 +0000

En un flujo de signup, el email suele parecer una tarea secundaria: crear la cuenta, enviar un enlace y esperar que aparezca en una bandeja de prueba. El problema llega cuando el test pregunta cada pocos segundos si ya hay un mensaje nuevo. Ese polling funciona al principio, pero pronto se vuelve lento, frágil y dificil de explicar.

He visto el mismo fallo en proyectos con Python: el endpoint responde bien, el worker envia el mensaje, pero la prueba mira la bandeja demasiado pronto. Luego se añade un sleep(3), despues otro reintento y, finalmente, un test que pasa en local pero falla en CI. No es que el correo sea misterioso. Falta un contrato claro entre el evento que produce el backend y la evidencia que consume la prueba.

El problema de esperar una bandeja

Un polling ciego mezcla varias preguntas distintas:

¿Se creó la cuenta?
¿Se generó el evento de verificación?
¿El proveedor aceptó el mensaje?
¿La bandeja de prueba lo recibió?
¿El test está leyendo el mensaje correcto?

Cuando todas se convierten en “espera hasta que aparezca un email”, cualquier retraso parece un fallo de aplicación. Ademas, si se reutiliza la misma bandeja entre tests paralelos, un mensaje viejo puede hacer que el caso equivocado pase.

Una solución sencilla es tratar el email como un evento observable. El endpoint no necesita esperar a que llegue el mensaje. Solo debe devolver una identidad de operación y registrar qué evento se produjo. La bandeja puede seguir siendo útil, pero ya no es la única fuente de verdad.

En un proyecto reciente, esta separación me resultó más clara junto con una guía para separar emails de signup por escenario. Cada escenario tiene su propio destino, y el evento lleva el contexto suficiente para no confundir registros.

Un contrato de eventos pequeño

No hace falta empezar con una plataforma de mensajería grande. Un contrato mínimo puede tener estos campos:

{
  "event_id": "evt_7f21",
  "event_type": "verification_email_requested",
  "account_id": "acc_204",
  "inbox_id": "test-inbox-17",
  "created_at": "2026-11-07T14:20:00Z",
  "status": "queued"
}

La combinación de event_id e inbox_id es importante. El primero permite deduplicar. El segundo mantiene aislado el correo de un test respecto a los demás. Si usamos un generador de correo temporal para crear el destino, la aplicación debe guardar solo la referencia necesaria para ese caso, no copiar mensajes enteros a cada log.

Los estados pueden ser pocos: queued, sent, delivered y failed. No intentaria representar todas las situaciones del proveedor. El objetivo es que una prueba pueda saber si está esperando un evento que todavía no existe o una entrega que ya falló.

Un endpoint de webhook en FastAPI

El endpoint que recibe una confirmación del proveedor debe ser idempotente. Si llega dos veces el mismo evento, la segunda petición no debe crear una entrega nueva ni cambiar un estado final a otro más confuso.

from datetime import datetime
from typing import Literal

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()


class EmailEvent(BaseModel):
    event_id: str
    inbox_id: str
    status: Literal["sent", "delivered", "failed"]
    occurred_at: datetime


@app.post("/webhooks/email", status_code=204)
async def receive_email_event(event: EmailEvent) -> None:
    current = await load_event(event.event_id)
    if current is None:
        raise HTTPException(status_code=404, detail="event not found")

    if current.status in {"delivered", "failed"}:
        return

    await save_event_status(
        event_id=event.event_id,
        inbox_id=event.inbox_id,
        status=event.status,
        occurred_at=event.occurred_at,
    )

En código real, load_event y save_event_status estarían detrás de una transacción o una operación condicional. La idea importante es que el evento tenga una clave estable y que la transición sea explícita. Si el proveedor reintenta el webhook, nuestra API responde igual sin duplicar trabajo.

Cómo probar sin carreras

Para un test de signup, prefiero este orden:

Crear un inbox_id único para el caso.
Crear la cuenta con ese identificador en el contexto de prueba.
Esperar el evento verification_email_requested, no tres segundos arbitrarios.
Consultar solo mensajes posteriores a created_at.
Confirmar que el mensaje pertenece al event_id y al inbox_id.
Consumir el enlace y guardar la evidencia mínima.

Si el sistema todavía no tiene eventos consultables, se puede envolver el polling en un helper que tenga un límite, una hora de inicio y una razón visible para cada reintento. Eso es mucho mejor que un while True con una pausa fija. Cuando el test falla, el log debe decir si no hubo evento, si hubo un evento sin mensaje o si el mensaje llegó pero no coincidía.

También conviene distinguir un timeout de infraestructura de un rechazo funcional. Un proveedor lento no significa que el token sea invalido. Esta distinción parece pequeña, pero reduce bastante el tiempo de diagnostico.

Checklist para el siguiente flujo

Antes de publicar otro endpoint de verificación, revisaria esto:

¿Cada ejecución tiene un event_id y una bandeja propia?
¿El endpoint puede recibir el mismo webhook dos veces?
¿Los estados terminales se protegen contra cambios accidentales?
¿El test espera una condición observable en vez de un tiempo fijo?
¿Los logs omiten el contenido sensible del mensaje?
¿Se conserva suficiente evidencia para explicar el fallo?

Un compañero puede escribir tempail en una búsqueda o en una nota de QA mientras intenta localizar una herramienta. No pasa nada, pero esa pista no debe convertirse en una regla de negocio ni en una dirección compartida por todos los tests.

La meta no es eliminar por completo el polling. En algunos entornos sigue siendo la integración disponible. La meta es darle un contexto: identidad, límite, evento esperado y motivo de salida. Con ese pequeño contrato, FastAPI queda más fácil de probar, los reintentos dejan mejor evidencia y el equipo puede corregir el punto real del flujo, no solo aumentar el sleep.

FastAPI: eventos de email sin polling frágil

Olivia Cheng — Tue, 03 Nov 2026 23:23:32 +0000

Los tests de email suelen empezar con una solución sencilla: enviar el mensaje, hacer sleep(5) y buscar el correo más reciente. Funciona en local, pero en CI se vuelve lento y bastante fragil. Un proveedor tarda más, dos jobs comparten inbox o el test encuentra un mensaje viejo.

Una alternativa práctica es tratar cada email de prueba como un evento correlacionado. La aplicación publica una señal con un identificador de ejecución y el lector busca exactamente ese evento, dentro de una ventana de tiempo. No elimina los retrasos de red, pero evita que el test adivine qué mensaje le pertenece.

El síntoma: un test que espera a ciegas

El polling no es malo por sí mismo. El problema aparece cuando es la única forma de saber que algo paso. Un flujo típico tiene estas decisiones escondidas:

cuánto tiempo esperar antes del primer intento;
qué ocurre si hay dos mensajes con el mismo asunto;
cómo distinguir un email de esta ejecución de uno anterior;
quién guarda la evidencia cuando el timeout expira.

Cuando esas reglas no están en un contrato, cada helper las resuelve de una forma distinta. En una búsqueda de documentación puede aparecer incluso tempail mail o tamp mail com, pero el nombre que se usa no arregla la falta de correlación.

El objetivo no es convertir un email en un sistema distribuido enorme. Es adjuntar contexto mínimo: run_id, destinatario, tipo de evento, momento de emisión y estado de consumo.

De polling a eventos correlacionados

Imagina que el backend genera un evento cuando crea el email de verificación. Ese evento no tiene que contener el cuerpo completo del mensaje. Puede incluir un identificador, un hash del contenido y la referencia al destinatario:

{
  "event_id": "evt_8f2a",
  "run_id": "ci_2026_11_04_001",
  "kind": "verification_email.created",
  "recipient": "test-42@example.invalid",
  "created_at": "2026-11-04T00:15:20Z"
}

El test espera una señal con run_id=ci_2026_11_04_001. Después puede consultar el inbox para confirmar el enlace, pero ya no necesita decidir cuál de cinco mensajes recientes es el correcto.

Este patrón también mejora el diagnóstico. Si el evento existe pero el mensaje no llega, el problema está entre la cola y el proveedor. Si no existe el evento, hay que revisar la aplicación. La frontera queda bastante más clara.

Un contrato pequeño en FastAPI

FastAPI puede exponer un endpoint interno para registrar y consultar eventos de prueba. En producción conviene usar PostgreSQL o una cola real; este ejemplo se concentra en el contrato HTTP:

from datetime import datetime, timezone
from uuid import UUID

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field

app = FastAPI()
events: dict[str, dict] = {}


class EmailEvent(BaseModel):
    event_id: str = Field(min_length=4)
    run_id: str = Field(min_length=4)
    kind: str = "verification_email.created"
    recipient: str
    created_at: datetime


@app.post("/test-events/email", status_code=202)
def record_event(event: EmailEvent):
    if event.event_id in events:
        return {"accepted": True, "duplicate": True}
    events[event.event_id] = event.model_dump(mode="json")
    return {"accepted": True, "duplicate": False}


@app.get("/test-events/email/{run_id}")
def find_event(run_id: str):
    match = next((item for item in events.values() if item["run_id"] == run_id), None)
    if match is None:
        raise HTTPException(status_code=404, detail="Evento no encontrado")
    return match

El endpoint devuelve duplicate=true para un reintento del mismo event_id. Esa respuesta es útil para un runner: repetir una llamada no crea una segunda señal que pueda confundir al lector.

Si el proyecto todavía usa polling, se puede introducir este contrato poco a poco. Primero registra el evento, luego conserva el polling como fallback y finalmente mide cuántos tests siguen necesitándolo. La transición es mas segura cuando cada paso deja métricas.

Idempotencia y reintentos

El evento debe ser idempotente, pero también lo debe ser el consumidor. Una secuencia razonable es:

crear un run_id único para el caso;
registrar el evento de emisión;
esperar la señal con un timeout explícito;
buscar el mensaje usando run_id, destinatario y fecha;
marcar el evento como consumido una sola vez;
guardar un resumen y limpiar los datos temporales.

No marques el evento como consumido antes de validar el enlace. Si el parser falla y el test reintenta, perderías una pista importante. También conviene registrar razones distintas para event_not_found, message_not_found y invalid_message; “email timeout” dice muy poco.

Para operar el flujo, las alertas de rollback con contexto real ofrecen una idea útil: una señal debe incluir contexto accionable, no solo un contador rojo.

Cómo llevarlo a CI

Antes de abrir el navegador o llamar al endpoint de registro, el job puede preparar:

un run_id que incluya el número de intento;
un artefacto JSON con el evento y sus timestamps;
un timeout total y un intervalo de polling definidos en configuración;
una política para conservar solo el resumen, no todo el contenido sensible;
un paso finally para liberar la bandeja o borrar el evento.

También ayuda aislar pruebas de email por entorno, porque el mismo contrato puede aplicarse a local, staging y CI sin mezclar bandejas. Si un job falla, guarda el run_id en el mensaje del error. Parece un detalle menor, pero ahorra bastante tiempo al revisar logs.

Preguntas rápidas

¿Esto elimina el polling?

No necesariamente. El evento indica qué esperar; el inbox todavía puede requerir polling si el proveedor no ofrece webhook. La diferencia es que el polling tiene una identidad y un límite.

¿Debo guardar el email completo?

Solo cuando haga falta para depurar. Un hash, el asunto, el remitente y los timestamps suelen ser suficientes para la mayoría de los fallos.

¿Qué pasa si dos tests usan el mismo destinatario?

El run_id debe seguir siendo distinto y el filtro debe comprobar también el tiempo de emisión. Si el proveedor permite direcciones aisladas, usarlas reduce todavía más la ambigüedad.

Cierre

Un evento correlacionado convierte “espera hasta que llegue algo” en “espera este mensaje de esta ejecución”. Con FastAPI, un endpoint pequeño, una clave idempotente y razones de fallo explícitas bastan para dar el primer paso.

El resultado no es solo un pipeline un poco mas rápido. Es una prueba que explica qué esperaba, qué recibió y en qué frontera se perdió la señal.

FastAPI: un lease para emails de verificación

Olivia Cheng — Tue, 03 Nov 2026 05:23:01 +0000

Un email de verificación puede romper un test aunque el endpoint funcione bien. El mensaje llega tarde, el polling encuentra una copia vieja o dos ejecuciones leen la misma bandeja. Luego el equipo repite el pipeline y la causa queda medio escondida.

Una forma práctica de ordenar este problema es tratar la bandeja de prueba como un recurso alquilado: cada ejecución obtiene un lease, una identidad, una hora de comienzo y una fecha de expiración. El test solo puede leer mensajes que pertenecen a ese periodo. No es una solución magica, pero convierte un fallo confuso en un contrato que se puede inspeccionar.

El problema: una bandeja que nadie posee

En un flujo de registro, la aplicación suele enviar un enlace a un correo temporal para pruebas. Si todos los tests usan la misma dirección, aparecen tres riesgos:

una ejecución consume el mensaje de otra;
el filtro por asunto elige un email antiguo;
un reintento parece pasar, pero nadie sabe que uso datos de la primera ejecución.

He visto este patrón en automatizaciones pequeñas: primero se añade un sleep(5), despues otro reintento y finalmente un timeout más largo. El pipeline tarda más, pero no es mas confiable. Incluso búsquedas como temp gamil com o fake e mail com en notas de QA suelen mostrar que la convención de datos no está clara.

La idea del lease es sencilla: el sistema que prepara el test crea una reserva con un identificador único. Ese identificador acompaña la petición de verificación y también queda guardado junto al mensaje esperado.

Qué debe representar un lease

Un lease útil necesita pocos campos, pero tienen que ser explícitos:

lease_id: UUID de la ejecución o del caso de prueba.
mailbox: dirección aislada para recibir el mensaje.
created_at: límite inferior para ignorar mensajes viejos.
expires_at: límite superior para no dejar polling infinito.
status: activo, consumido o expirado.

Con esto, el test deja de preguntar “¿cuál es el último email?” y pregunta “¿cuál es el mensaje de mi lease, creado después de mi acción?”. Esa diferencia parece pequeña, pero hace el diagnóstico bastante mas facil.

También conviene que el lease sea idempotente. Si el runner repite la llamada con el mismo lease_id, la API debe devolver la reserva existente, no crear otra bandeja que después nadie limpia.

Un contrato pequeño en FastAPI

Este ejemplo solo modela la parte de control. El proveedor real de correo se puede conectar detrás de MailboxService sin mezclarlo con las rutas HTTP.

from datetime import datetime, timedelta, timezone
from uuid import UUID, uuid4

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field

app = FastAPI()
leases: dict[UUID, dict] = {}


class LeaseRequest(BaseModel):
    mailbox: str = Field(min_length=3)
    ttl_seconds: int = Field(default=180, ge=30, le=900)


@app.post("/test-email/leases", status_code=201)
def create_lease(request: LeaseRequest):
    now = datetime.now(timezone.utc)
    lease_id = uuid4()
    lease = {
        "lease_id": lease_id,
        "mailbox": request.mailbox,
        "created_at": now,
        "expires_at": now + timedelta(seconds=request.ttl_seconds),
        "status": "active",
    }
    leases[lease_id] = lease
    return lease


@app.get("/test-email/leases/{lease_id}")
def get_lease(lease_id: UUID):
    lease = leases.get(lease_id)
    if lease is None:
        raise HTTPException(status_code=404, detail="Lease no encontrado")
    return lease

En producción, el diccionario debe ser una tabla o un almacén con expiración. El ejemplo sirve para mostrar el límite: la API es dueña del estado del lease y el lector de emails no necesita adivinarlo.

Polling con límites y liberación

El consumidor puede enviar lease_id al servicio que consulta la bandeja. El servicio aplica estos filtros en este orden:

comprobar que el lease existe y sigue activo;
descartar mensajes con fecha anterior a created_at;
comprobar que el destinatario y el asunto corresponden al caso;
marcar el mensaje como consumido después de validarlo;
liberar la bandeja al terminar, también si el test falla.

La última parte se olvida bastante. En Python, una función de cleanup llamada desde finally suele ser suficiente para el runner. Si el proveedor permite una clave de correlación, úsala junto al lease_id; el asunto por sí solo es demasiado debil.

El timeout debe pertenecer al contrato, no estar repartido entre tres helpers. Por ejemplo, un lease de 180 segundos puede tener polling cada dos segundos, pero debe devolver una razón clara al expirar: lease_expired, message_not_found o message_rejected. Un error así ayuda mucho mas que “Timeout waiting for email”.

Para un flujo completo, también vale la pena probar upgrades por email sin ruido y revisar cómo mantener pruebas de email sin deriva en CI. Son piezas distintas, pero comparten la misma regla: cada ejecución debe dejar evidencia propia.

Cómo llevarlo a CI

Antes de lanzar el navegador o la llamada API, el job debe:

crear el lease y guardar su JSON como artefacto;
pasar lease_id y mailbox como variables del test;
registrar el momento exacto en que se dispara el email;
adjuntar el mensaje seleccionado y la razón de selección;
ejecutar la liberación en un paso de cleanup.

Cuando hay reintentos, conserva los artefactos por intento. Sobrescribirlos es tentador, pero hace que el segundo intento borre la evidencia del primero. Un nombre como email-lease-{lease_id}.json ya ayuda a mantener el contexto.

Preguntas rápidas

¿Un lease reemplaza una dirección aislada por test?

No. La dirección aislada sigue siendo buena práctica. El lease añade tiempo, propiedad y estado, así que protege cuando la dirección se reutiliza o el proveedor no puede crear una nueva para cada caso.

¿Debo guardar el contenido completo del email?

Solo si es necesario para depurar. En muchos casos basta con guardar asunto, remitente, fecha, identificador y un hash del cuerpo. Así reduces datos sensibles en los artefactos de CI.

¿Qué hago si el proveedor no tiene expiración?

Mantén la expiración en tu propia base de datos y ejecuta una tarea de limpieza. La ausencia de una función remota no debe convertir el polling en un proceso sin fin.

Cierre

Un contrato de lease no hace que el correo sea instantáneo. Hace algo más útil: define qué ejecución tiene derecho a leer qué mensaje y durante cuánto tiempo. Con FastAPI, unas rutas pequeñas, un lease_id y un cleanup fiable bastan para empezar.

La próxima vez que un test de verificación falle, busca primero la propiedad del inbox y la ventana temporal. Si esas dos cosas están documentadas, el equipo puede arreglar el sistema en vez de solo subir el timeout.

FastAPI: callbacks de email sin duplicados

Olivia Cheng — Thu, 29 Oct 2026 14:22:45 +0000

Cuando un servicio de email avisa que un mensaje fue entregado, abierto o rechazado, el callback parece una operación sencilla: recibir JSON, actualizar una fila y devolver 200 OK. En realidad, los proveedores reintentan, las redes cortan conexiones y dos eventos pueden llegar casi al mismo tiempo.

En una API pequeña, esto puede terminar en estados imposibles: un mensaje marcado como entregado despues de haber sido rechazado, dos tareas de automatización para el mismo evento o un contador de notificaciones que crece cada vez que el proveedor repite la petición.

La solución que suelo aplicar en backend es tratar cada callback como un evento con identidad propia. FastAPI ayuda con la validación y el tipado, pero la parte importante es el contrato de idempotencia: recibir el mismo evento dos veces debe tener el mismo efecto que recibirlo una sola vez.

El problema de los callbacks duplicados

Supongamos que una aplicación envía un enlace de verificación. El proveedor acepta el mensaje y luego manda un callback delivered. Si nuestra API tarda demasiado en responder, el proveedor puede reenviar el mismo evento. También puede ocurrir que el worker procese el primer evento mientras el segundo ya está esperando en la cola.

Guardar solo status = "delivered" no alcanza. Hace falta conservar un identificador del evento, el identificador del mensaje y un estado que permita decidir si una transición es válida. Tambien conviene guardar una marca de tiempo y el cuerpo mínimo necesario para investigar, sin copiar datos privados que no aportan.

Un contrato práctico puede tener esta forma:

{
  "event_id": "evt_01J9ABC123",
  "message_id": "msg_7f31",
  "type": "email.delivered",
  "occurred_at": "2026-10-29T14:00:00Z"
}

event_id identifica la notificación del proveedor. message_id identifica el email dentro de nuestro sistema. Si el proveedor no entrega un event_id estable, podemos calcular una huella de los campos confiables, aunque es mejor documentar esa decisión y no depender de todo el JSON.

Un contrato pequeño para el webhook

Antes de escribir el endpoint, definiria tres reglas:

Un event_id nuevo se registra una sola vez.
Un evento ya registrado devuelve éxito sin ejecutar otra vez el efecto.
Una transición antigua no puede sobrescribir un estado más avanzado.

La segunda regla es importante. Devolver un error para cada repetición hace que el proveedor siga reintentando. Si el evento ya fue procesado, 200 OK significa “lo conozco y no necesito repetirlo”.

Para las transiciones, una tabla sencilla puede guardar received, processed, delivered y failed. No todos los proveedores usan los mismos nombres, por eso es mejor mapear sus estados a un vocabulario interno. Un callback opened no deberia cambiar un mensaje que ya está en failed si ese cambio no está permitido por el producto.

Implementación idempotente en FastAPI

El endpoint puede validar la forma del evento y dejar el trabajo pesado a una tarea. La restricción única en la base de datos es la última defensa contra carreras entre peticiones:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class EmailEvent(BaseModel):
    event_id: str
    message_id: str
    type: str
    occurred_at: str

@app.post("/webhooks/email")
def receive_email_event(event: EmailEvent):
    inserted = event_store.insert_once(
        event_id=event.event_id,
        message_id=event.message_id,
        event_type=event.type,
        occurred_at=event.occurred_at,
    )

    if not inserted:
        return {"accepted": True, "duplicate": True}

    queue.publish("email-event", event.model_dump())
    return {"accepted": True, "duplicate": False}

El ejemplo omite la implementación de event_store, pero su operación insert_once deberia apoyarse en un índice único para event_id. No confiaría solamente en un SELECT seguido de un INSERT: dos requests pueden pasar el SELECT antes de que cualquiera escriba.

El worker puede aplicar la transición dentro de una transacción. Si falla después de registrar el evento, el sistema necesita una estrategia de reintento basada en el estado, no un evento nuevo con otro identificador. Un correlation_id facilita seguir el recorrido desde el callback hasta la tarea que actualiza el mensaje.

Pruebas y observabilidad del flujo

Primero probaría la lógica con una secuencia pequeña:

Enviar un callback nuevo y comprobar que se crea un registro.
Enviar el mismo event_id dos veces y comprobar que solo se encola una tarea.
Enviar un evento antiguo despues de uno más avanzado y comprobar que el estado no retrocede.
Simular un fallo del worker y verificar que el reintento es seguro.

En una prueba de integración, una bandeja aislada permite revisar asunto, enlace y contenido sin usar una cuenta personal. Para ese tipo de verificación, un correo temporal gratis puede servir como entorno descartable; no lo usaría para datos reales ni para ocultar la identidad de usuarios.

Los logs deberían incluir event_id, message_id, tipo y resultado de la transición. No incluiría el cuerpo completo del email ni tokens. Un panel sencillo con eventos recibidos, duplicados, rechazados y tiempo de procesamiento responde preguntas mas utiles que un contador general de requests.

Si la interfaz muestra el resultado del envío, el backend y el frontend deben compartir estados claros. Vale la pena diseñar estados async accesibles sin saltos para que “procesando” no se confunda con “entregado”. Y cuando el usuario vuelve a abrir una pantalla, verificar emails sin perder el contexto ayuda a no lanzar una segunda acción por accidente.

En búsquedas y pruebas internas pueden aparecer expresiones como tempmail so o el typo tempail mail. Son términos de contenido, no contratos técnicos: no deberían terminar en nombres de eventos, tablas o respuestas de la API.

Checklist para llevarlo a producción

¿Existe una restricción única para event_id?
¿Una repetición devuelve éxito sin repetir efectos?
¿Las transiciones inválidas quedan registradas?
¿El worker puede reintentarse sin duplicar notificaciones?
¿Los logs evitan tokens y contenido privado?
¿Hay una forma de relacionar callback, mensaje y tarea?
¿El endpoint valida el tamaño y la forma del payload?

Tambien revisaría qué ocurre cuando la base de datos está temporalmente fuera de servicio. En ese caso, devolver un error para que el proveedor reintente suele ser más seguro que confirmar un evento que nunca se guardó. El tiempo de respuesta debe ser corto; el procesamiento detallado puede ocurrir después.

Preguntas rápidas

¿Idempotencia significa ignorar todos los eventos repetidos?

No. Significa que una repetición no vuelve a ejecutar el mismo efecto. Aun puede ser útil actualizar un contador de intentos o registrar una métrica de duplicados, siempre que eso sea una operación separada y controlada.

¿Debo procesar el callback antes de responder?

Normalmente no. Valida, persiste o encola lo mínimo y responde. El worker puede hacer el cambio de estado con más tiempo y con reintentos. Una cola no arregla un contrato ambiguo, pero hace el flujo mas resistente cuando el proveedor entrega ráfagas.

¿Qué debo probar primero?

El caso feliz y la repetición inmediata. Quizas el bug más caro no sea un callback que falla, sino uno que parece funcionar dos veces y manda dos mensajes o activa dos procesos.

Un webhook de email confiable no necesita mucha magia. Necesita identidad, restricciones en la base de datos, transiciones explícitas y pruebas que imiten los reintentos reales. Con ese contrato, FastAPI deja de ser solo la puerta de entrada y se convierte en una base clara para automatizar sin sorpresas.

FastAPI: un contrato para emails de prueba

Olivia Cheng — Wed, 28 Oct 2026 14:22:44 +0000

Un endpoint de FastAPI puede devolver 202 Accepted en milisegundos y aun así dejar al test esperando un correo que llega después. En muchos proyectos, el problema no es el endpoint: es que la aplicación y el buzón de prueba no tienen un contrato claro.

Cuando el test solo hace sleep(5) y busca el último mensaje, los reintentos se vuelven confuso. Puede leer un email de una ejecución anterior, mezclar dos usuarios o fallar sin decir si el mensaje nunca salió. La solución que me resulta más práctica es tratar el buzón como una dependencia con reglas explícitas, igual que una API externa.

El problema: el endpoint funciona, pero el test no sabe qué esperar

Imagina un registro que crea un usuario y dispara un email de confirmación. El test necesita saber al menos cuatro cosas:

qué identidad de prueba pertenece a la ejecución;
desde qué instante debe aceptar mensajes;
cómo reconocer el mensaje correcto;
qué evidencia guardar si el mensaje no aparece.

Sin esas reglas, "último email" parece una atajo, pero no es una aserción confiable. También dificulta auditar señales de onboarding en un SaaS cuando el flujo crece y hay varios eventos parecidos.

Qué debe prometer el contrato del buzón

Un contrato pequeño puede tener esta forma:

El test obtiene un buzón único antes de llamar al endpoint.
Guarda inbox_id y triggered_at junto con el caso de prueba.
Solo acepta mensajes posteriores a triggered_at.
Verifica asunto, destinatario y un identificador de ejecución.
Devuelve el mensaje elegido o un diagnóstico con lo que observó.

Ese identificador puede ser un run_id incluido en un header interno o en los datos del usuario. No hace falta inventar una plataforma compleja. Basta con que el criterio sea reproducible y que el test no dependa de coincidencias.

Un cliente pequeño para esperar el mensaje correcto

La parte útil puede vivir en una clase de Python. El cliente real puede hablar con el proveedor de correo, pero la interfaz del test debería quedarse simple:

from datetime import datetime, timezone
import asyncio

async def wait_for_message(mail, inbox_id, run_id, timeout=30):
    started = datetime.now(timezone.utc)
    deadline = asyncio.get_running_loop().time() + timeout
    seen = []

    while asyncio.get_running_loop().time() < deadline:
        messages = await mail.list_messages(inbox_id)
        for message in messages:
            seen.append(message.id)
            received = message.received_at
            if received <= started:
                continue
            if run_id not in message.text:
                continue
            if "Confirma tu cuenta" not in message.subject:
                continue
            return message
        await asyncio.sleep(1)

    raise AssertionError(f"Email no encontrado; inbox={inbox_id}, vistos={seen}")

El detalle importante no es el sleep, sino el filtro. El test espera una propiedad del mensaje y conserva los ids observados. Si la API de correo tiene paginación, conviene ordenar por fecha y deduplicar por id para que la misma notificación no se procese dos veces.

Para aislar la integración, un temp mail so puede servir como bandeja temporal durante pruebas controladas. No lo usaría como una identidad permanente ni para datos reales: el objetivo es que cada ejecución tenga un buzón limitado y fácil de retirar.

Aislamiento, reintentos y limpieza

Un reintento debe crear una nueva identidad de prueba o reutilizar la misma de forma deliberada. Reutilizar sin registrar la decisión hace que el segundo intento herede mensajes viejos. En CI, yo guardaría un objeto mínimo por intento:

{
  "run_id": "ci-4821",
  "inbox_id": "inbox-91",
  "triggered_at": "2026-10-28T14:00:00Z",
  "message_id": "msg-204",
  "status": "accepted"
}

También define una política de limpieza. El buzón se debe cerrar después del test, incluso cuando falla una aserción. En Python, try/finally suele ser suficiente; si la creación del buzón ocurre dentro de un fixture de pytest, el yield deja ese ciclo bastante claro.

Si varios tests comparten una cuenta por ahorrar tiempo, al menos usa un prefijo de ejecución en el destinatario o en el contenido. Un dummy e mail escrito en una nota puede parecer igual que el correo real para un compañero que depura deprisa. Y "tem email" no explica nada si no viene acompañado de un id, una hora y una razón de descarte.

Checklist para llevarlo a CI

Crea el buzón antes de disparar el endpoint.
Genera un run_id único y pásalo al flujo.
Filtra por fecha, destinatario, asunto y run_id.
Registra los ids vistos y el motivo de cada descarte.
Configura un timeout basado en polling, no en una espera fija.
Limpia el buzón en éxito y en error.
Evita imprimir tokens o el contenido completo del mensaje en logs.

Para el caso de emails transaccionales, ayuda también probar emails transaccionales sin mezclar bandejas. La idea encaja bien con FastAPI porque separa la lógica del endpoint de la lógica de observación. El test no necesita saber cómo se entrega el correo, solo qué contrato puede exigir.

Preguntas rápidas

¿Cuánto debe esperar un test?

Depende del entorno y del proveedor. Empieza con un límite razonable para CI y mide los tiempos reales. Si cada test espera 60 segundos, el problema es de diseño aunque casi siempre pase.

¿Debo buscar el email más reciente?

Solo si además validas la identidad de la ejecución. Fecha reciente por sí sola no evita que dos mensajes lleguen juntos.

¿Qué registro es suficiente?

El run_id, el buzón, la hora de disparo, ids observados y la decisión final suelen dar una explicación rapida sin convertir el log en una copia del correo.

Un contrato de recepción pequeño hace que la automatización sea menos misteriosa. Cuando un test falla, puedes ver si falló la API, la entrega o el filtro; y esa diferencia ahorra mas tiempo que añadir otro reintento ciego.

FastAPI: contratos claros para emails de prueba

Olivia Cheng — Wed, 28 Oct 2026 11:22:45 +0000

Cuando un test solicita un email de verificación, muchas aplicaciones consideran que el trabajo terminó al recibir un 202 Accepted. Ese resultado solo dice que la API aceptó la petición. No confirma que el mensaje se haya generado, entregado al buzón de prueba o que el contenido sea el esperado.

En proyectos Python he encontrado que el problema no suele ser enviar el email, sino definir qué significa que el flujo terminó bien. Un contrato pequeño en FastAPI puede separar esas etapas y hacer que un fallo sea mucho mas facil de investigar. Tambien evita que un test pase por accidente porque leyó un mensaje viejo.

El problema: aceptar no es verificar

Imagina un registro de usuario con este flujo:

El test llama a POST /users.
La aplicación publica un evento de verificación.
Un worker construye y envía el email.
El buzón de prueba lo hace visible.
El test lee el enlace y confirma la cuenta.

Cada paso puede tener una latencia diferente. Si el endpoint responde de inmediato y el test busca el mensaje una sola vez, aparecerán fallos intermitentes. Si el buzón se reutiliza sin un identificador único, el test puede encontrar el email de otra ejecución y mostrar un falso positivo.

Para el frontend, también es útil que cada estado sea explicable; este artículo sobre estados accesibles para email de prueba muestra por qué “esperando” y “falló” no deberían verse como el mismo resultado.

Define el contrato del flujo

Antes de escribir el test, define una respuesta y una evidencia mínima. Por ejemplo, POST /test-email puede devolver:

{
  "run_id": "ci-2026-1042",
  "mailbox": "ci-2026-1042@example.test",
  "status": "queued"
}

El run_id debe viajar en el evento y en el asunto o cuerpo del mensaje. El endpoint de lectura puede ser GET /test-email/{run_id}, con estados como queued, delivered, mismatch y expired. Así el consumidor no necesita adivinar si “no encontrado” significa que el worker sigue trabajando o que el mensaje nunca llegará.

Este contrato tambien debe especificar una ventana de espera, qué campos se comparan y qué datos se guardan. Para depurar normalmente alcanza con el identificador del mensaje, timestamps, asunto, destinatario de prueba y resultado de cada intento. Guardar todo el contenido durante meses es una decisión de privacidad que no deberia ser automática.

Un endpoint FastAPI pequeño y observable

La API no necesita hacer polling dentro de la petición que crea el usuario. Puede encolar el trabajo y exponer una consulta separada:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class EmailRun(BaseModel):
    run_id: str
    mailbox: str
    status: str

@app.post("/test-email", response_model=EmailRun, status_code=202)
async def queue_test_email(run_id: str, mailbox: str):
    # La implementación real publica un evento idempotente.
    return EmailRun(run_id=run_id, mailbox=mailbox, status="queued")

@app.get("/test-email/{run_id}", response_model=EmailRun)
async def read_test_email(run_id: str):
    result = await lookup_email_run(run_id)
    if result is None:
        raise HTTPException(status_code=404, detail="run not found")
    return result

El ejemplo es intencionalmente pequeño: el valor está en el límite entre estados, no en esconder toda la lógica en el endpoint. En producción, lookup_email_run debería leer de una fuente consistente y no depender de una variable global mutable.

La respuesta de estado también ayuda a medir activación y abandono. Si el producto tiene varios pasos de onboarding, conviene revisar cohortes de activación por email con el mismo identificador de ejecución, en vez de mezclar eventos de usuarios reales y tests.

Polling, idempotencia y limpieza

El cliente puede consultar cada pocos segundos con un límite total. Un backoff de 2, 4, 8 y 16 segundos suele ser suficiente para un smoke test; no hace falta bombardear el buzón. Al terminar el plazo, devuelve un error con la última evidencia, no solo un timeout genérico.

La creación del evento debe ser idempotente. Si CI reintenta la petición por un corte de red, el mismo run_id no debería crear dos usuarios ni dos procesos de verificación. El servidor puede conservar una clave de idempotencia corta y responder con el estado existente.

También hay que separar “mensaje no visible todavía” de “mensaje incorrecto”. Un correo que aparece con otro run_id suele indicar aislamiento roto; un asunto correcto pero sin enlace apunta a una plantilla; un buzón sin respuesta puede ser un problema de proveedor o autenticación. Esa distinción ahorra bastante tiempo en una guardia.

Por último, limpia los mensajes y buzones al finalizar. Si la limpieza falla, registra el incidente sin ocultar el resultado principal del test. Para nombres de búsqueda que aparecen en documentación informal, alguien puede escribir “tempail” o “tem email”; el código y los contratos deben usar siempre la misma nomenclatura correcta.

Preguntas frecuentes

¿Conviene esperar el email dentro de `POST /users`?

No para la mayoría de tests. Mantener la petición abierta mezcla creación de usuario con entrega de correo y hace mas dificil distinguir dónde falló el flujo. Un 202 más una consulta de estado representa mejor el trabajo asíncrono.

¿Debo usar un buzón diferente por cada ejecución?

Es lo mas sencillo. Si no es posible, añade un run_id único, filtra por él y aplica una limpieza confiable. Reutilizar sin esos controles convierte un test rápido en una fuente de resultados dudosos.

¿Qué evidencia debería conservar CI?

El identificador de ejecución, estado final, tiempos de cola y entrega, asunto, identificador del mensaje y causa de fallo. El cuerpo completo solo debe conservarse cuando sea necesario para depurar y con una retención corta.

Checklist para el test

[ ] La API devuelve un run_id estable y un estado explícito.
[ ] El evento y el mensaje incluyen el mismo identificador.
[ ] La lectura distingue queued, delivered, mismatch y expired.
[ ] Los reintentos no duplican la operación de negocio.
[ ] El polling tiene backoff y un límite total.
[ ] CI guarda evidencia mínima y útil.
[ ] Los mensajes de prueba se limpian después de cada ejecución.

Un contrato claro no hace que el email sea instantáneo, pero sí convierte una espera ambigua en una señal que el equipo puede entender. Con FastAPI, unos pocos estados bien definidos suelen dar más confianza que una cadena de reintentos sin contexto.

FastAPI: contratos de tiempo para emails de prueba

Olivia Cheng — Mon, 26 Oct 2026 20:22:50 +0000

Cuando una prueba espera un email de verificación, el timeout suele ser el primer sospechoso. Pero subirlo de 30 a 90 segundos no arregla una prueba que no sabe distinguir entre un mensaje nuevo y uno viejo. En una API de FastAPI, el problema real suele ser la falta de un contrato de tiempo claro.

Un contrato sencillo define cuándo empieza la espera, qué señales cuentan como éxito, cuántos reintentos se permiten y qué evidencia queda si la prueba falla. Esta idea hace que los emails de prueba sean más previsibles y que la automatización de CI tenga algo útil que explicar.

El problema no es solo el timeout

Imagina un endpoint que crea una cuenta y dispara un correo. El test hace una petición, consulta el buzón y busca el mensaje más reciente. Si el proveedor tarda, la consulta puede devolver cero mensajes. Si otro test comparte el buzón, puede devolver el mensaje equivocado. La prueba falla en la linea de lectura, aunque el bug esté en el aislamiento.

También hay una carrera menos visible: la API responde antes de que el proveedor acepte el mensaje, pero el test empieza a buscar demasiado pronto. Un sleep(5) parece ayudar, aunque solo mueve el problema. En el siguiente runner, el retraso puede ser diferente.

La respuesta no es llamar a cualquier correo temporal y esperar más. Es registrar una referencia propia para cada ejecución: run_id, instante de inicio y destinatario. Así la prueba sabe que debe aceptar un mensaje posterior a su inicio y dirigido a su identidad.

Define un contrato de tiempo

Antes de hacer polling, crea un objeto pequeño con las reglas de la espera:

from dataclasses import dataclass
from datetime import datetime, timedelta, timezone

@dataclass(frozen=True)
class EmailWait:
    started_at: datetime
    deadline: datetime
    recipient: str
    run_id: str

    @classmethod
    def start(cls, recipient: str, run_id: str, seconds: int = 30):
        now = datetime.now(timezone.utc)
        return cls(now, now + timedelta(seconds=seconds), recipient, run_id)

El contrato hace explícito algo que normalmente queda repartido entre fixtures y variables de entorno. started_at filtra mensajes antiguos, deadline limita el coste y run_id permite unir el resultado con el log de CI. Si la prueba utiliza una dirección compartida, el destinatario solo no será suficiente: añade también un asunto o una marca única.

Conviene medir el tiempo desde una señal estable. Si el endpoint devuelve 202 Accepted, empieza la espera cuando la API confirma que el trabajo fue encolado, no varios pasos antes. Para procesos largos, un SLO para emails de CI ayuda a convertir esa expectativa en una métrica operable.

Implementa el polling en FastAPI

La ruta no debería bloquearse durante toda la espera. Una opción práctica es que el endpoint de prueba cree un trabajo y que un worker consulte el proveedor. El código del test puede usar un cliente asíncrono con pausas cortas y un límite absoluto:

import asyncio
from datetime import datetime, timezone

async def wait_for_message(mailbox, wait: EmailWait):
    while datetime.now(timezone.utc) < wait.deadline:
        messages = await mailbox.list_messages(recipient=wait.recipient)
        for message in messages:
            received = message.received_at
            if received >= wait.started_at and wait.run_id in message.subject:
                return message
        await asyncio.sleep(1.5)
    raise TimeoutError(f"No llegó un email para {wait.run_id} antes del límite")

En producción, el adaptador de mailbox puede llamar a una API externa; en tests unitarios, puede ser un fake. Esa separación vuelve la prueba más rápida y permite comprobar los casos difíciles: mensaje tardío, respuesta vacía, duplicados y error temporal del proveedor. Un detalle pequeño pero importante es que el sleep debe tener una pausa razonable, no un bucle ocupado que consuma CPU.

No escondas todos los errores detrás de TimeoutError. Si el proveedor devuelve 401, 429 o 500, guarda esa diferencia en el resultado. Un retry para un 429 tiene sentido; repetir una credencial inválida solo hace el diagnóstico más confuso.

Guarda evidencia sin guardar todo el correo

Cuando falla un test, conserva un resumen seguro: run_id, destinatario anonimizado, número de mensajes vistos, IDs de mensajes, timestamps y causa final. No hace falta guardar el cuerpo completo, porque puede contener tokens o datos personales.

En los logs, normaliza los errores de entrada. Una búsqueda mal escrita como temp gamil com no debe transformarse en una regla de producción ni en un filtro de aceptación. Parece obvio, pero este tipo de texto acaba a veces en variables de configuración copiadas de una incidencia.

Para interfaces que muestran el estado del trabajo, los mensajes de error también deben ser estables. Las ideas de formularios con errores accesibles aplican aquí: una persona debe entender si el proceso está esperando, terminó o necesita reintento, sin depender solo del color.

Checklist para CI

Antes de dar por estable el flujo, comprueba lo siguiente:

Cada ejecución tiene un run_id único y un instante de inicio.
El filtro usa destinatario, timestamp y una señal del flujo.
Hay un límite absoluto; el polling no es infinito.
Los códigos 429 y 5xx tienen reintentos acotados.
El reporte conserva IDs y tiempos, pero no el contenido sensible.
La limpieza ocurre en un bloque finally, incluso tras una aserción fallida.
El adaptador externo tiene un fake para tests unitarios.
Un fallo de entrega se distingue de un fallo de parsing.

Esto tambien facilita comparar ejecuciones. Si el tiempo de entrega crece durante varios días, tienes una señal para investigar antes de que todos los tests se vuelvan lentos.

Preguntas frecuentes

¿Debo esperar en el endpoint de FastAPI?

Normalmente no. Devuelve una respuesta que represente el trabajo encolado y deja el polling a un worker o al cliente de pruebas. Bloquear el request puede agotar los workers de la aplicación cuando el proveedor de correo está lento.

¿Cuántos reintentos son suficientes?

Depende del proveedor, pero el límite debe estar relacionado con el presupuesto de la prueba. Tres reintentos rápidos no son una garantía; son una política que debe quedar visible y medirse.

¿Qué hago con un mensaje duplicado?

Trátalo como un resultado ambiguo y registra sus IDs. Elegir silenciosamente el primero puede ocultar una entrega repetida o una fuga entre pruebas.

El objetivo no es hacer que el email llegue siempre rápido. Es convertir una dependencia externa en una operación con identidad, tiempo y evidencia. Con ese contrato, FastAPI queda más fácil de probar, y la automatización deja de depender de pausas mágicas.

DEV Community: Olivia Cheng

FastAPI: clasifica fallos de correo en vez de reintentar

El error no siempre significa que hay que reintentar

Clasificar antes de decidir

Un pequeño contrato de errores en FastAPI

Automatizar reintentos con límites

Observabilidad útil para el equipo

Checklist y preguntas frecuentes

FastAPI: contratos de eventos para emails de prueba

El problema: esperar un email no es un contrato

Diseñar un evento pequeño y trazable

Implementación de un endpoint FastAPI

Polling con identidad y límite

Cómo automatizar la evidencia en CI

Preguntas frecuentes

¿Necesito una cola para empezar?

¿Por qué no basta con buscar por asunto?

¿Qué debe probar el test?

FastAPI: clasifica fallos de email sin reintentar a ciegas

El error no siempre merece otro intento

Clasifica antes de reintentar

Un endpoint pequeño en FastAPI

Registra la decisión, no solo la excepción

Pruebas para automatizaciones previsibles

Q&A: dudas habituales

¿Debo reintentar todos los errores 5xx?

¿Qué hago si no recibo respuesta?

Checklist de implementación

FastAPI: un contrato de expiración para emails de prueba

El problema: un buzón de prueba que nunca muere

Qué debe prometer el contrato

Un modelo pequeño en FastAPI

Expirar sin carreras ni borrados peligrosos

Q&A rápido

¿Por qué no devolver siempre una lista vacía?

¿Es suficiente un run_id?

¿Qué TTL conviene usar?

Checklist para llevarlo a CI

FastAPI: un reloj para emails de prueba

FastAPI: un reloj para emails de prueba

Por qué el tiempo es parte del contrato del email

Un modelo pequeño de deadline en FastAPI

Separar espera, reintentos y evidencia

Cómo probar el reloj sin pruebas lentas

Checklist para automatización estable

Preguntas frecuentes

¿Debo hacer polling o usar webhooks?

¿Un buzón temporal sustituye las pruebas de email reales?

¿Qué métrica empezaría a medir?

FastAPI: eventos de email sin polling ciego

El problema de esperar una bandeja

Un contrato de eventos pequeño

Un endpoint de webhook en FastAPI

Cómo probar sin carreras

Checklist para el siguiente flujo

FastAPI: eventos de email sin polling frágil

El síntoma: un test que espera a ciegas

De polling a eventos correlacionados

Un contrato pequeño en FastAPI

Idempotencia y reintentos

Cómo llevarlo a CI

Preguntas rápidas

¿Esto elimina el polling?

¿Debo guardar el email completo?

¿Qué pasa si dos tests usan el mismo destinatario?

Cierre

FastAPI: un lease para emails de verificación

El problema: una bandeja que nadie posee

Qué debe representar un lease

Un contrato pequeño en FastAPI

Polling con límites y liberación

Cómo llevarlo a CI

Preguntas rápidas

¿Un lease reemplaza una dirección aislada por test?

¿Debo guardar el contenido completo del email?

¿Qué hago si el proveedor no tiene expiración?

Cierre

FastAPI: callbacks de email sin duplicados

El problema de los callbacks duplicados

Un contrato pequeño para el webhook

¿Es suficiente un `run_id`?

¿Conviene esperar el email dentro de `POST /users`?