FastAPI: separa emails de signup por escenario

Cuando un equipo prueba flujos de registro en FastAPI, casi siempre mira primero si el endpoint devuelve 200. El problema es que eso no alcanza. El bug real suele vivir un paso después: el email llega tarde, cae en el inbox equivocado, o se mezcla con mensajes de otra prueba. Y ahí staging se vuelve raro de leer.

En productos con login social o campañas de adquisición, esto pasa bastante. Un caso común es validar formularios parecidos a los de Facebook, donde conviven alta tradicional, recuperación de cuenta y confirmaciones de seguridad. Si el equipo usa un solo buzón para todo, el ruido tapa señales muy utiles. Por eso cada vez recomiendo más separar el correo temporal para Facebook y otros escenarios de signup por intención de prueba, no solo por ambiente.

Qué problema aparece cuando pruebas signup en bloque

La mayoría de los fallos no nacen en la plantilla del correo. Nacen en la organización de la prueba:

• varias suites usan el mismo inbox
• un retry deja mensajes viejos y nadie los distingue
• QA revisa manualmente correos que pertenecen a otro escenario
• el backend no guarda contexto suficiente para enlazar solicitud y mensaje

Eso genera falsas alarmas. El equipo cree que el signup mandó dos correos, pero uno era de una corrida anterior. O piensa que el email no salió, cuando sí salió pero quedó enterrado entre mensajes de otra automatización. Es un problema muy simple y, aun así, pega fuerte.

En cambios delicados me gusta pensar esto igual que las alertas comprobables en entornos de cambio: no basta con emitir una señal, también tienes que poder demostrar a qué evento pertenece.

La regla que mejor me funciona: un inbox por escenario

La práctica más rentable que he visto es reservar un inbox por escenario de negocio. No uno por entorno, ni uno por tester, sino uno por caso concreto:

• signup-basic
• signup-social
• password-reset
• email-change

Con eso, cuando quiero crear correo temporal para una suite concreta, ya sé qué mensaje espero y qué mensajes sobran. No necesito interpretar una bandeja mezclada ni adivinar si el asunto vino de otra prueba.

También ayuda cuando aparecen búsquedas medio desordenadas en tickets internos, como tepm mail com o dummy e mail. Puede sonar menor, pero si el equipo usa esos términos al reportar incidencias, conviene tener el flujo documentado de forma que todos entiendan a qué inbox o escenario se referían.

Un patrón simple en FastAPI para reservar el inbox

No hace falta una plataforma enorme. En FastAPI, me funciona un patrón pequeño:

1. El test o job declara el escenario.
2. El backend genera un delivery_scope.
3. Ese scope reserva un inbox asociado a la prueba.
4. El email sale con metadatos mínimos para rastreo.

Un ejemplo corto:

from uuid import uuid4
from fastapi import APIRouter

router = APIRouter()

@router.post("/signup/email-preview")
async def signup_email_preview(flow: str):
    delivery_scope = f"{flow}-{uuid4().hex[:8]}"
    inbox_alias = await lease_inbox_alias(flow=flow, scope=delivery_scope)

    payload = await build_signup_email(flow=flow, inbox_alias=inbox_alias)

    return {
        "flow": flow,
        "delivery_scope": delivery_scope,
        "inbox_alias": inbox_alias,
        "subject": payload["subject"],
    }

Luego el worker o la integración de correo reutiliza delivery_scope para etiquetar logs y adjuntar el alias correcto. Lo importante no es el nombre exacto del campo. Lo importante es que el escenario no se pierda entre la API, la cola y la validación final.

Cómo revisar el flujo sin volverlo frágil

Aquí es donde muchos equipos se pasan de complejos. Yo intento mantener tres verificaciones nada más:

• el inbox reservado corresponde al escenario
• el asunto coincide con el paso del flujo
• el mensaje llega dentro de una ventana razonable

Si además el frontend tiene estados de espera o reintento, conviene revisar que no induzcan acciones duplicadas. Ese detalle conecta muy bien con estos estados de carga claros en flujos de email, porque un backend limpio pierde valor si la interfaz provoca dobles envíos por ansiedad del usuario.

Algo que me ha ahorrado tiempo es no reutilizar el mismo inbox entre suites nocturnas y pruebas manuales. Suena obvio, pero muchas veces no se respeta. Cuando lo separas, los falsos positivos bajan enseguida, y la conversación entre backend y QA mejora bastante.

Si quieres una revisión un poco más estricta, añade una comprobación de expiración corta al alias reservado. Así evitas que una corrida vieja “contamine” la siguiente. No resuelve todo, pero reduce bastante el caos y hace que staging se sienta más confiable, cosa que aveces cuesta más de conseguir de lo que parece.

Checklist corto para staging

Antes de aprobar un flujo de signup, yo reviso esto:

• cada escenario tiene su inbox reservado
• el backend guarda un identificador de alcance por corrida
• el test valida asunto, destinatario y momento de entrega
• las pruebas manuales no comparten bandeja con CI
• el equipo sabe limpiar aliases expirados

No es una receta magica. Pero sí es una forma simple de volver legible algo que normalmente se vuelve confuso muy rápido.

Q&A

¿Necesito un inbox distinto por usuario de prueba?

No siempre. Si el escenario está bien delimitado, suele bastar con un inbox por flujo y por corrida.

¿Esto sirve solo para login social?

No. También funciona muy bien en onboarding clásico, cambios de email, invitaciones y recuperación de cuenta.

¿Cuál es la ganancia real?

Menos tiempo interpretando bandejas mezcladas y más tiempo corrigiendo fallos de verdad. Para un equipo pequeño, eso ya paga el esfuerzo.