DEV Community: Silviu Technology

FastAPI: prueba emails sin romper tu entorno

Silviu Technology — Fri, 24 Jul 2026 05:24:23 +0000

Cuando un flujo de registro falla, mucha gente revisa solo si el proveedor "envio algo". En mi experiencia con FastAPI, eso casi nunca alcanza. El problema de verdad suele estar en la frontera entre API, cola, plantilla y entorno. Si usas datos reales o inboxes mezclados, depurar se vuelve lento y medio confuso.

Por eso me gusta separar la prueba funcional de email con una regla bien simple: cada ejecucion de staging recibe su propia identidad, su propia traza y su propia inbox temporal. Si necesitas generar correo desechable para un caso puntual, que sea un recurso de prueba y no una dependencia rara pegada al sistema.

El error comun: mezclar pruebas de email y entorno real

He visto equipos guardar direcciones manuales en variables compartidas, reutilizar la misma inbox por dias y luego preguntarse por que el test "a veces" pasa. Tambien aparecen notas como temp mailid en tickets o mensajes de QA, y eso ya te avisa que el proceso depende demasiado de memoria humana.

El otro error es mirar solo el correo recibido y no el camino completo:

la API acepta la solicitud
la cola crea el trabajo
el worker renderiza la plantilla
el proveedor intenta la entrega
la inbox de prueba confirma el resultado

Si solo validas el paso 5, te pierdes casi todo lo util. Para eso me han servido articulos sobre revisar emails de reactivacion con contexto, porque muestran bien que un email aislado dice poco sin el evento que lo produjo.

Un patron simple para aislar inboxes en FastAPI

Lo que mejor me ha funcionado es crear un run_id por ejecucion y propagarlo desde la request hasta el envio. No hace falta una arquitectura enorme, de hecho algo pequeño suele durar mas.

from fastapi import FastAPI, BackgroundTasks
from uuid import uuid4

app = FastAPI()

def queue_signup_email(user_id: str, inbox: str, run_id: str) -> None:
    payload = {
        "user_id": user_id,
        "inbox": inbox,
        "run_id": run_id,
        "template": "signup_verify",
    }
    print(payload)

@app.post("/signup-test")
def signup_test(user_id: str, background_tasks: BackgroundTasks):
    run_id = str(uuid4())
    inbox = f"{run_id[:8]}@example.test"
    background_tasks.add_task(queue_signup_email, user_id, inbox, run_id)
    return {"run_id": run_id, "inbox": inbox}

La idea no es el print, claro. La idea es que el mismo run_id viva en logs, eventos y revisiones. Asi sabes que inbox corresponde a que intento, y no terminas cazando un tempail mail viejo de otra corrida. Parece obvio, pero cuando no existe esa relacion, el debugging se pone feo muy rapido.

Codigo minimo para crear trazas utiles

Despues del run_id, yo intento guardar solo tres cosas que casi siempre alcanzan:

estado normalizado: queued, sent, failed
identificador del proveedor
marca de tiempo del intento

Con eso puedes contestar preguntas operativas sin exponer contenido sensible ni abrir cinco paneles. Si ademas tu worker registra una razon corta de fallo, ya tienes una base bastante decente.

Tambien conviene que la automatizacion revise el resultado desde dos angulos:

la API devolvio el run_id
la inbox asociada recibio el mensaje esperado

Ese segundo paso se puede conectar con una guia como probar emails de referidos en flujos reales, sobre todo si en tu producto hay varias plantillas y no quieres validar todo con una sola direccion reciclada.

Si tu suite crece, una mejora bastante util es persistir un manifiesto corto por ejecucion:

{
  "run_id": "b51d7c3e",
  "template": "signup_verify",
  "expected_subject": "Confirma tu cuenta",
  "inbox": "b51d7c3e@example.test",
  "status": "sent"
}

No es glamoroso, pero funciona. Ese archivito evita muchas discusiones tontas sobre cual email estabamos mirando, y hace que soporte o QA puedan revisar fallos sin entrar al codigo cada vez.

Que validar antes de automatizar mas

Antes de meter mas scripts, yo revisaria esto:

Cada entorno usa inboxes distintas o nombres claramente aislados.
Las pruebas limpian sus artefactos despues de un tiempo razonable.
El worker puede reintentarse sin duplicar evidencia confusa.
Los logs no guardan cuerpos completos de emails por defecto.
Existe una manera corta de unir request, job e inbox.

Si esas cinco piezas estan, la automatizacion mejora mucho. Si no estan, cualquier herramienta que agregues solo tapa el ruido por un rato. Es mejor resolver primero el contrato minimo entre API y entrega, aun si al principio se siente un poco boring.

Q&A

¿Necesito una inbox temporal para todas las pruebas?

No. Para unit tests y varias integraciones basta con mocks o con una salida a archivo. La inbox temporal sirve mas cuando quieres validar el mensaje final que veria una persona.

¿Conviene revisar el HTML completo del email en cada corrida?

Solo en pruebas bien elegidas. Hacerlo siempre suele volver la suite mas fragil de lo necesario. Yo prefiero revisar asunto, CTA principal y uno o dos fragmentos criticos.

¿Que cambia cuando trabajo con varios entornos?

Que la disciplina importa mas. Si staging, QA y demos comparten destino, tarde o temprano vas a leer el email correcto en el momento equivocado. Y ese tipo de fallo te roba tiempo, aunque paresca pequeño.

React: evita dobles envíos al reenviar email

Silviu Technology — Thu, 23 Jul 2026 23:25:14 +0000

En muchos productos el botón de reenviar verificación parece una tarea menor, pero acaba tocando UX, métricas y soporte a la vez. Si la persona pulsa dos o tres veces porque el estado tarda en reflejarse, el frontend crea ruido innecesario aunque la API esté bien. En equipos de React esto pasa bastante: el evento sale, pero la interfaz no deja claro que ya está trabajando.

Lo he visto sobre todo en flujos donde QA repite pruebas con un correo de usar y tirar o una direccion de correo desechable. Cuando la bandeja tarda unos segundos, la tentación natural es volver a pulsar. Ahí se mezclan eventos, se inflan contadores y luego cuesta saber si el fallo era de entrega, de UI o simplemente de impaciencia humana.

Por que el boton de reenviar suele romper la experiencia

El problema no suele ser un bug enorme. Suele ser una suma de detalles pequeños:

el botón cambia de texto tarde
el spinner aparece sin reservar espacio
el cooldown se muestra en un lugar distinto al foco
la telemetría cuenta cada clic aunque el backend ya haya ignorado el duplicado

Eso deja una sensación rara. La persona piensa "no hizo nada", prueba otra vez, y el flujo se vuelve menos confiable de lo que realmente es. En móvil se nota mas, porque el pulgar ya está encima del CTA y el feedback visual llega un poco despues.

También hay un coste interno. Si tu equipo intenta probar correos transaccionales sin mezclar eventos, un botón poco claro arruina esa señal limpia. El frontend no debería fabricar duplicados que luego obligan a explicar dashboards raros.

Que estados merece el CTA desde el primer commit

Para mi, el error es tratar "reenviar email" como un único estado booleano. En realidad hay, como mínimo, cuatro estados útiles:

idle, cuando la acción está disponible.
sending, cuando ya salió la petición.
cooldown, cuando el backend aceptó el reenvío pero quieres frenar intentos inmediatos.
error, cuando toca explicar qué puede hacer la persona sin sonar brusco.

Separar esos estados hace dos cosas buenas. Primero, la interfaz deja de improvisar. Segundo, la medición mejora porque cada transición tiene significado real. Si sólo alternas entre "activo" y "desactivado", terminas leyendo datos medio opacos.

También ayuda a accesibilidad. Un mensaje corto en aria-live puede anunciar "email reenviado, espera 30 s" sin mover el foco ni esconder el botón. Parece un ajuste pequeño, pero hace la interacción bastante mas honesta.

Un patron de React para enfriar el reenvio sin castigar accesibilidad

Prefiero un patrón simple: el botón conserva tamaño, el texto cambia dentro del mismo bloque y el cooldown usa tiempo restante visible. Nada muy fancy, pero funciona bien.

import { useEffect, useState } from "react";

type ResendState = "idle" | "sending" | "cooldown";

export function ResendEmailButton() {
  const [state, setState] = useState<ResendState>("idle");
  const [secondsLeft, setSecondsLeft] = useState(0);

  useEffect(() => {
    if (state !== "cooldown" || secondsLeft === 0) return;

    const timer = window.setTimeout(() => {
      setSecondsLeft((value) => value - 1);
    }, 1000);

    return () => window.clearTimeout(timer);
  }, [state, secondsLeft]);

  useEffect(() => {
    if (state === "cooldown" && secondsLeft === 0) {
      setState("idle");
    }
  }, [state, secondsLeft]);

  async function handleResend() {
    if (state !== "idle") return;

    setState("sending");

    try {
      await resendVerificationEmail();
      setSecondsLeft(30);
      setState("cooldown");
    } catch {
      setState("idle");
    }
  }

  const label =
    state === "sending"
      ? "Enviando..."
      : state === "cooldown"
        ? `Reenviar en ${secondsLeft}s`
        : "Reenviar email";

  return (
    <div className="resend-block">
      <button onClick={handleResend} disabled={state !== "idle"}>
        {label}
      </button>
      <p aria-live="polite" className="resend-status">
        {state === "cooldown" ? "Ya enviamos un nuevo enlace." : ""}
      </p>
    </div>
  );
}

.resend-block {
  display: grid;
  gap: 0.5rem;
}

.resend-block button {
  min-inline-size: 12rem;
}

.resend-status {
  min-block-size: 1.5rem;
}

No es un patrón revolucionario, pero evita dos problemas comunes: el doble clic y el layout nervioso. Si además el backend usa idempotencia o rate limiting, mucho mejor. El frontend no reemplaza esa capa; la hace entendible.

Aquí también intento evitar textos ambiguos. "Inténtalo más tarde" suena seco y no enseña nada. "Ya enviamos un nuevo enlace, espera 30 s" da contexto y baja ansiedad. Es una diferencia chica, pero muy util.

Como medir si el cambio realmente mejora el flujo

Yo miraría cuatro señales:

tasa de clic duplicado dentro de 10 segundos
tiempo hasta el siguiente paso exitoso
errores de reenvío por persona única
sesiones donde hubo foco perdido o navegación frustrada

Si puedes separar los tests con bandejas dedicadas, todavía mejor. Un equipo que ya sabe validar cohortes sin contaminar bandejas tiene medio camino hecho para leer estas métricas con menos ruido. El truco está en distinguir duplicado real de simple repetición manual durante pruebas.

Cuando QA usa temp gamil com en una nota rápida, no pasa nada. El punto es no dejar que ese tipo de shorthand acabe mezclado con criterios de observabilidad o con nombres de escenarios. Cuanto mas nítido sea el estado del CTA, menos dependes de interpretar capturas a ojo.

Una referencia útil aquí es el patrón de optimistic UI de web.dev. No porque haya que aplicar optimismo puro en un flujo de verificación, sino porque recuerda algo importante: el feedback de la interfaz debe llegar en el momento correcto, no varios beats despues.

Preguntas frecuentes

¿Desactivar el botón no perjudica accesibilidad?

No, si mantienes el contexto visible y anuncias el resultado con una región viva. Lo que perjudica mas es dejar un botón activo que parece disponible cuando en realidad no lo está.

¿Hace falta mostrar el contador?

Yo diría que sí en la mayoría de casos. Reduce incertidumbre y evita la sensación de que el sistema se quedó pensando forever. Además, el tiempo restante ayuda a soporte y QA a entender el comportamiento esperado.

¿Esto mejora performance o solo UX?

Las dos cosas, aunque sea de forma indirecta. Menos clics duplicados significa menos trabajo redundante, menos ruido de analítica y una lectura mas limpia de la salud del flujo.

FastAPI: logs utiles para colas de email

Silviu Technology — Thu, 23 Jul 2026 14:24:34 +0000

Cuando una app en FastAPI manda emails desde una cola, el fallo casi nunca está en send_email(). El problema suele ser que no sabes qué pasó entre el request original, el worker, el reintento y la confirmación final. En equipos pequeños eso se nota tarde, y en equipos grandes se vuelve un dolor diario.

En varios backends he visto el mismo patrón: la cola "funciona", pero investigar un email perdido toma demasiado tiempo. Si quieres depurar rapido, necesitas trazabilidad suficiente desde el inicio, no más prints sueltos al final.

Por que una cola de email se vuelve opaca tan rapido

Una tarea de email normalmente cruza varias capas:

endpoint HTTP
validación de payload
enqueue del job
worker async
proveedor externo
actualización de estado

Si cada capa escribe logs distintos, sin una clave común, buscar el origen del problema se vuelve bastante lento. Realesmente no hace falta una plataforma enorme para arreglarlo; hace falta disciplina en los eventos y nombres consistentes.

También conviene diferenciar dos preguntas:

¿el job fue aceptado?
¿el email fue entregado o falló?

Mezclar esas dos respuestas en un solo log complica mucho el soporte. Este enfoque se parece a cómo se diseñan los contratos de inbox para automatización: primero dejas claro qué evento ocurrió, luego validas la siguiente transición.

Que guardar en cada evento del worker

Mi regla simple es: cada intento debe poder entenderse sin abrir cinco dashboards. Para eso, cada evento de log debería incluir como mínimo:

job_id
request_id
user_id o un identificador seguro del destinatario
template_name
attempt
provider
status
duration_ms

Si usas un correlation_id estable desde FastAPI hasta el worker, ya ganaste bastante. No resuelve todo, pero reduce mucho el tiempo de diagnóstico.

Tambien vale la pena registrar el motivo de reintento con una categoría corta. Algo como timeout, provider_5xx o invalid_recipient es más útil que una excepción gigante pegada en una sola línea. La excepción completa puede vivir aparte.

Un detalle que evita bugs tontos: normaliza entradas dudosas antes de encolar. He visto datos de prueba como temp gamil com o tempail mail colarse en staging y contaminar métricas. No es grave por si mismo, pero ensucia el analisis si nadie marca que era un dato artificial.

Un patron simple en FastAPI para seguir cada intento

Un patrón muy usable es separar el evento de negocio del evento de entrega. El endpoint solo registra que se pidió enviar un email. El worker registra cada intento real.

from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel
from uuid import uuid4
import time
import logging

app = FastAPI()
log = logging.getLogger("email_jobs")


class EmailRequest(BaseModel):
    to: str
    template: str


def send_email_job(job_id: str, request_id: str, to: str, template: str) -> None:
    started = time.perf_counter()
    attempt = 1
    log.info(
        "email_attempt_started",
        extra={
            "job_id": job_id,
            "request_id": request_id,
            "template": template,
            "attempt": attempt,
            "status": "started",
        },
    )

    # aqui llamarias a tu proveedor

    log.info(
        "email_attempt_finished",
        extra={
            "job_id": job_id,
            "request_id": request_id,
            "template": template,
            "attempt": attempt,
            "status": "sent",
            "duration_ms": round((time.perf_counter() - started) * 1000, 2),
        },
    )


@app.post("/emails")
def queue_email(payload: EmailRequest, bg: BackgroundTasks):
    job_id = str(uuid4())
    request_id = str(uuid4())
    log.info(
        "email_job_queued",
        extra={
            "job_id": job_id,
            "request_id": request_id,
            "template": payload.template,
            "status": "queued",
        },
    )
    bg.add_task(send_email_job, job_id, request_id, payload.to, payload.template)
    return {"job_id": job_id, "request_id": request_id}

No es una arquitectura exotica, pero funciona muy bien para equipos que todavía no quieren meter otra capa compleja. Si luego migras a Celery, RQ o Dramatiq, la idea base sigue siendo la misma: un identificador por solicitud y eventos cortos, comparables, y faciles de buscar.

Cuando el flujo crece, me gusta combinar esto con runbooks sencillos. Ese enfoque encaja con estos runbooks de email que escalan, porque obligan a documentar qué estados importan de verdad y cuál es la acción esperada en cada uno.

Como depurar reintentos sin duplicar ruido

Los reintentos ayudan, pero si no se diseñan bien esconden el fallo en vez de aclararlo. Un error comun es registrar el mismo mensaje completo en cada vuelta. Eso infla los logs y hace más dificil detectar la causa original.

Prefiero esta secuencia:

un evento corto cuando se agenda el reintento
un evento corto cuando empieza el nuevo intento
un evento final con resultado y duración

Con eso puedes responder preguntas utiles muy rapido:

¿cuántos jobs terminan en el segundo intento?
¿qué plantilla falla más?
¿el proveedor tarda más en ciertas horas?

Si además guardas un resumen final por job, el soporte puede revisar un caso sin leer todo el stream. No necesitas perfección; necesitas señales consistentes. Esa pequeña diferencia hace que una cola de email pase de "mas o menos estable" a algo que el equipo puede operar con calma.

Preguntas frecuentes

¿Necesito tracing distribuido para esto?

No al principio. Con request_id, job_id y eventos bien nombrados ya puedes resolver una parte grande del problema.

¿Cuándo separar logs de negocio y logs técnicos?

Lo antes posible. Los logs de negocio explican qué quería hacer el sistema; los técnicos explican cómo salió ese intento. Juntarlos suele crear confusión.

¿Qué revisaría primero si faltan emails?

Buscaría jobs aceptados sin evento final, luego tiempos altos por proveedor y después errores repetidos por plantilla. Ese orden normalmente te lleva al problema real bastante mas rapido.

Si tu cola ya envia emails pero nadie confía en sus señales, empezar por los logs correctos suele dar más retorno que cambiar de librería. No es glamoroso, pero si muy efectivo.

Make Playwright Email Tests Less Flaky

Silviu Technology — Thu, 23 Jul 2026 05:24:49 +0000

I like email verification tests when they prove one narrow thing: a real user can finish signup without a hidden messaging bug. I do not like them when they become a slot machine. If your Playwright suite sometimes sees the email, sometimes grabs the wrong one, and sometimes times out for no obvious reason, the test is usually missing structure rather than missing retries.

This is the workflow I keep coming back to for Playwright and Automation teams. It is not fancy, but it is dependable and a bit easier to explain during failure review.

Why these tests fail in different ways

Most flaky email tests fail for one of three reasons:

two runs read from the same inbox
the test matches the first email instead of the correct email
the failure leaves almost no evidence behind

That sounds simple, yet it creates very different symptoms. One build looks green locally and red in CI. Another run passes but verifies the wrong account. A third one times out and gives you zero clue where the delay realy happened.

Before changing the locator or the timeout again, I try to make the test answer a boring question first: "what exact inbox and message was this run supposed to use?"

1. Give each run its own inbox identity

Shared inboxes are the fastest way to create noisy failures. If your suite points every signup test at the same temp mailbox, you are testing message arrival and accidental cross-talk at the same time. That is not a fair test.

I prefer an address pattern that carries run identity inside it, even if the provider is just a temporary inbox used for QA:

const runId = `${Date.now()}-${test.info().parallelIndex}`;
const email = `signup-${runId}@example.test`;

The exact address format does not matter much. What matters is that the run id appears in the inbox name, your test logs, and ideally the application-side metadata too. The same idea shows up in naming inboxes per test run: once every run has a distinct identity, the wierd failures get much less mysterious.

If your team uses a temp mail so service or a temp mailbox provider for staging checks, keep it scoped to one test run and expire it quickly. I have also seen people type temp org mail into setup notes when they mean "some throwaway inbox here"; that is fine as shorthand, but the test itself should still record the actual mailbox it created.

2. Wait for the right email, not any email

The next problem is matching. A lot of tests poll an inbox and click the first message with "Verify" in the subject. That is a brittle shortcut. In busy environments, that approach drifts fast.

Instead, wait on a small contract:

expected recipient
expected subject pattern
expected creation window
expected text unique to this flow

That contract can stay small and still be strong. For example, if the UI shows the email address back to the user, assert against that exact value before you ever open the inbox. Then look for a message created after the signup action and containing the app or tenant name. This avoids a bunch of fake greens.

Here is the shape I use:

await expect(page.getByText(email)).toBeVisible();

const message = await inbox.waitForMessage({
  to: email,
  subjectIncludes: "Verify your account",
  receivedAfter: startedAt,
  bodyIncludes: "Finish creating your workspace",
});

This does two helpful things. First, it narrows the search space. Second, it tells you what the test believed should happen, which makes failure analysis way more usefull than "timed out after 30s".

If you run email checks in CI, the operational pattern from staging inbox smoke tests is worth borrowing too: keep the inbox logic narrow, observable, and tied to one deploy or one run, not to the whole environment forever. Keeping those concerns seperate helps a lot when a flaky failure only appears under load.

3. Save evidence when the test fails

This is the step teams skip because the happy path already works. Then a red build shows up, and nobody knows if the app failed to send, the inbox API lagged, or the test matched the wrong message.

When a Playwright email test fails, save three bits of evidence:

the generated email address
the poll criteria
the latest inbox snapshot or message list

You do not need to dump everything. A short structured artifact is usualy enough:

test.afterEach(async ({}, testInfo) => {
  if (testInfo.status !== testInfo.expectedStatus) {
    await testInfo.attach("email-debug", {
      body: JSON.stringify({
        email,
        startedAt,
        criteria: {
          subject: "Verify your account",
          bodyIncludes: "Finish creating your workspace"
        },
        inboxSnapshot: await inbox.listRecent(),
      }, null, 2),
      contentType: "application/json",
    });
  }
});

Now the failure review starts from evidence instead of guesswork. That is also why I like storing the inbox name in the same run metadata you use for the rest of the suite. The principle is pretty close to naming inboxes per test run: once artifacts carry the run identity, retries stop erasing the story.

A short checklist I reuse

Before I call an email test "stable enough", I want this checklist to be true:

each test run gets a unique inbox or alias
the app logs the email target for the run
the inbox poll filters by recipient and time window
the assertion checks a flow-specific string, not just any email
failures attach enough evidence for another engineer to debug it
the suite keeps mailbox lifetime short so old mail does not bleed into new runs

It is not a huge list, but it catches most of the avoidable flake I see in QA suites.

Q&A

Should I just increase the timeout?

Only after the matching rules are good. Longer waits can hide shared-inbox bugs and make the suite slower without making it safer.

Is a temporary inbox okay for real projects?

Yes, for staging and test flows. Just keep the scope narrow, avoid real user data, and do not confuse a passing inbox check with full delivery validation.

What if multiple emails are expected in one flow?

Give each message its own assertion contract. If you collapse "verification", "welcome", and "team invite" into one loose poll, the test will get confusing prety fast.

Reliable email tests are mostly about reducing ambiguity. Once the run has one inbox identity, one message contract, and one evidence trail, Playwright failures become much more fixable and much less annoying.

FastAPI: aisla pruebas de email por entorno

Silviu Technology — Wed, 22 Jul 2026 20:24:21 +0000

Cuando un flujo de registro manda correos desde desarrollo, staging y producción usando casi la misma infraestructura, los fallos se vuelven muy confusos. El email llega, pero nadie sabe desde qué entorno salió, qué worker lo disparó ni si el enlace corresponde al escenario que estabas probando. En equipos backend esto pasa mas de lo que admitimos.

En varios proyectos con FastAPI, lo que mejor me funcionó fue tratar cada entorno como un carril separado: su propia etiqueta, su propia bandeja temporal y su propia traza. Mucha gente termina buscando algo tipo crear correo temporal o generador de correos falsos porque nota el síntoma, pero el problema real casi siempre es falta de aislamiento.

Por qué mezclar entornos rompe pruebas útiles

Si una misma bandeja recibe mensajes de staging y de local, una verificación simple deja de ser confiable. Puedes ver el asunto correcto y aun asi estar leyendo el correo equivocado. Eso rompe pruebas manuales, scripts y hasta decisiones de producto.

El daño no solo está en QA. También afecta a backend cuando revisa reintentos, deduplicación o expiración de tokens. Si el equipo quiere medir fallos de verificación, primero necesita datos limpios. Sin eso, el dashboard queda bonito pero dice poco.

Por eso prefiero definir tres reglas sencillas:

Un entorno, una bandeja o alias.
Un request id visible desde la API hasta el correo entregado.
Un nombre de remitente o prefijo que deje claro el origen.

No es glamoroso, pero funciona muy bien y evita bastantes discusiones raras.

Un patrón simple para aislar bandejas en FastAPI

La idea es guardar contexto del entorno antes de encolar el envío. No hace falta un sistema enorme. Con FastAPI, una cola y una convención de nombres ya puedes empezar.

Este patrón pequeño suele alcanzar:

from fastapi import FastAPI, Request
from uuid import uuid4

app = FastAPI()

@app.post("/signup")
async def signup(request: Request, email: str):
    run_id = str(uuid4())
    env_name = request.headers.get("x-env-name", "local")

    payload = {
        "email": email,
        "env_name": env_name,
        "run_id": run_id,
        "template": "verify-signup",
    }

    # envía el job al worker o broker que uses
    return {"queued": True, "run_id": run_id}

Luego, en el worker, uso env_name para decidir una etiqueta visible y también para elegir la bandeja de prueba. En staging, por ejemplo, conviene que cada suite tenga su propio destino. Si el equipo necesita crear cuentas rápidas, una bandeja de tempmailso puede servir como buzón aislado sin mezclar pruebas reales.

Lo importante acá no es la herramienta. Es que el correo deje pistas claras: entorno, hora, tipo de evento y run id. Si una persona de producto abre el mensaje, debería entenderlo sin pedir ayuda al backend.

Qué conviene registrar en la API y en el worker

Cuando una prueba falla, yo intento responder tres preguntas muy rapido:

¿La API aceptó el evento correcto?
¿El worker procesó ese evento una sola vez?
¿El correo observado pertenece a ese intento y no a otro?

Para eso, estos campos ayudan bastante:

run_id para unir logs y pruebas.
env_name para separar staging, local y preview.
template para saber qué copy debía salir.
recipient_kind para distinguir usuario real, seed interno o bandeja temporal.
queued_at y sent_at para detectar atrasos o retries duplicados.

Si ya estás haciendo pruebas de correo en entornos reales, este registro adicional te da la pieza que suele faltar: saber por qué llegó ese mensaje y no solo confirmar que llegó.

También me gusta dejar el keyword tempail en notas internas o fixtures si el equipo ya lo usa como referencia informal, pero no lo usaría como anchor ni como nombre oficial. Sirve para capturar búsquedas o costumbres viejas, nada más.

Errores pequeños que suelen colarse

Hay varios fallos repetidos que veo en automatización de correos:

Reutilizar la misma bandeja para varias suites paralelas.
Validar solo el asunto y no el enlace final.
Reintentar jobs sin registrar si el primer envío ya salió.
Probar con cuentas que comparten estado entre local y staging.
Esconder el entorno en logs pero no en el propio email.

Otro error muy comun es poner toda la lógica de aislamiento en tests y nada en la app. Eso hace que la prueba sepa demasiado del sistema y el sistema muy poco de sí mismo. Prefiero que FastAPI y el worker publiquen contexto útil por defecto, aunque el test sea sencillo.

Un detalle practico: si tienes varios templates, no metas todas las verificaciones en una sola bandeja y luego filtres por texto. Eso parece rapido al principio, pero se vuelve frágil en cuanto cambian copys o llegan reintentos.

Preguntas frecuentes

¿Necesito una bandeja distinta por cada entorno?

Sí, si quieres depurar con calma. Incluso cuando el volumen es bajo, separar local, staging y preview te ahorra tiempo luego.

¿Esto aplica solo a FastAPI?

No. El patrón vale para cualquier backend con colas o envíos asíncronos. FastAPI simplemente lo hace facil de integrar porque el request y el tipado quedan bastante claros.

¿Qué reviso primero si veo correos duplicados?

Primero revisa el run_id y el registro del worker. Si dos mensajes comparten destinatario pero no comparten el mismo origen lógico, casi seguro el problema está en reintentos o en falta de idempotencia.

¿Hace falta una gran plataforma de observabilidad?

No necesariamente. Con buenos nombres, campos mínimos y una bandeja separada por entorno ya mejoras mucho. Luego, si el sistema crece, agregas métricas y alertas sin rehacer todo.

React: reenvíos de verificación sin ansiedad

Silviu Technology — Tue, 21 Jul 2026 17:24:37 +0000

En muchos productos el botón de "reenviar verificación" parece un detalle menor, pero suele decidir si el usuario termina el alta o abandona. Cuando la interfaz no explica si el correo ya salió, cuánto falta para volver a intentarlo o por qué el botón sigue desactivado, la sensación es rara. No parece rota del todo, pero tampoco transmite confianza.

En frontend me encuentro este problema bastante seguido. El backend responde bien, la cola manda el email, pero la UI deja al usuario adivinando. Algunos equipos incluso prueban con cuentas de tem email o con inboxes temporales para ver si "más o menos" funciona, y justo ahí aparecen los bordes raros: loaders que parpadean, temporizadores que cambian de ancho y mensajes que desaparecen demasiado pronto.

Por qué el botón de reenviar crea desconfianza

El usuario no piensa en estados finitos ni en throttling. Piensa algo mucho más simple: "¿ya envié el correo o lo vuelvo a tocar?". Si la interfaz no responde eso rápido, empieza el martilleo del botón, llegan solicitudes duplicadas y soporte recibe tickets que eran evitables.

También hay un tema claro de accesibilidad. Un temporizador visual sin anuncio comprensible deja fuera a usuarios con lector de pantalla, y un mensaje efímero puede perderse si el foco sigue en otro sitio. La guía de WAI sobre mensajes de estado explica por qué conviene anunciar cambios relevantes sin romper la navegación: https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html.

Desde rendimiento percibido, el problema tampoco es pequeño. Nielsen Norman Group lleva años señalando que el feedback visible dentro de los primeros segundos reduce ansiedad y mejora la sensación de control: https://www.nngroup.com/articles/response-times-3-important-limits/. No hace milagros, pero si baja bastante la fricción cuando el correo tarda un poco más de lo esperado.

Qué estados necesita un reenvío usable

Para mí el patrón mínimo tiene cuatro estados: idle, sending, cooldown y sent-with-help. El primero permite enviar. El segundo confirma que ya se disparó la acción. El tercero evita reintentos impulsivos y explica cuánto falta. El cuarto da una salida si el correo no aparece: revisar spam, corregir dirección o usar otra bandeja de prueba.

Lo importante es que esos estados no cambien la estructura principal. El mismo botón debe seguir ocupando el mismo espacio. El mensaje de ayuda necesita una altura estable. Y el contador no debería empujar el layout cada segundo, por que ese tipo de micro salto se siente mas de lo que parece.

Aquí también entra la parte pragmática: si tu equipo usa una bandeja temporal para QA, conviene separar el flujo de usuario real del flujo de prueba. A veces basta con documentar cuándo usar una cuenta normal y cuándo una herramienta como temp mail so. No necesita ser protagonista del artículo ni del producto, solo un recurso contextual cuando el equipo valida entregas o tiempos de llegada.

Un patrón simple en React

Este ejemplo mantiene el ancho del CTA, anuncia cambios útiles y evita que el contador rehaga media interfaz a cada tick. No es el único enfoque, pero sale bastante bien en productos con onboarding:

import { useEffect, useRef, useState } from "react";

const COOLDOWN_SECONDS = 30;

export function ResendVerification() {
  const [status, setStatus] = useState("idle");
  const [secondsLeft, setSecondsLeft] = useState(0);
  const [message, setMessage] = useState("");
  const timerRef = useRef(null);

  useEffect(() => {
    if (status !== "cooldown") return;

    timerRef.current = window.setInterval(() => {
      setSecondsLeft((current) => {
        if (current <= 1) {
          window.clearInterval(timerRef.current);
          setStatus("idle");
          setMessage("Ya puedes reenviar el correo otra vez.");
          return 0;
        }

        return current - 1;
      });
    }, 1000);

    return () => window.clearInterval(timerRef.current);
  }, [status]);

  async function handleResend() {
    setStatus("sending");
    setMessage("Enviando otro correo de verificación...");

    const response = await fetch("/api/email/resend", { method: "POST" });

    if (!response.ok) {
      setStatus("idle");
      setMessage("No pudimos reenviar el correo. Revisa la dirección e inténtalo de nuevo.");
      return;
    }

    setStatus("cooldown");
    setSecondsLeft(COOLDOWN_SECONDS);
    setMessage("Correo reenviado. Espera un momento antes de repetir la acción.");
  }

  return (
    <section aria-live="polite">
      <p style={{ minHeight: 24 }}>{message}</p>

      <button
        type="button"
        onClick={handleResend}
        disabled={status === "sending" || status === "cooldown"}
        style={{ minWidth: 220 }}
      >
        {status === "cooldown"
          ? `Reenviar en ${secondsLeft}s`
          : status === "sending"
            ? "Enviando..."
            : "Reenviar verificación"}
      </button>
    </section>
  );
}

Hay tres cosas pequeñas que me gustan aquí. Una: el texto de estado vive en un contenedor estable. Dos: el botón mantiene ancho mínimo, así que el cambio entre "Enviando..." y el contador no provoca brincos feos. Tres: el usuario entiende qué pasa sin tener que deducirlo, que suena básico, pero no siempre pasa.

Si quieres ir un poco más lejos, separa el countdown visual del anuncio accesible. Por ejemplo, puedes mantener aria-live solo para eventos grandes y no para cada segundo del contador. Eso evita ruido en lector de pantalla, que a veces se vuelve medio insoportable.

Cómo medir si la experiencia mejora

No me quedaría solo con "se siente mejor". Hay métricas concretas que ayudan:

ratio de clicks repetidos sobre reenviar en menos de 10 segundos
tiempo hasta completar verificación después del primer resend
tickets de soporte ligados a "no me llegó el correo"
abandono del onboarding tras ver el estado de cooldown

Si el ratio de clicks repetidos baja, normalmente la UI está explicando mejor lo que ya hacía el sistema. Y si además reduces abandono, mejor todavía. Para equipos que conectan estas pruebas con operaciones o automatización, me parecen utiles estos ejemplos sobre checks de email en ventanas de mantenimiento reales y runbooks de email que si escalan. Muestran bien cómo una interacción pequeña puede terminar afectando observabilidad y soporte.

Preguntas rápidas

¿El cooldown no frustra más al usuario?

Solo si aparece sin contexto. Si explicas que el correo ya salió y muestras cuánto falta, suele bajar la ansiedad en vez de subirla. Lo confuso no es esperar; lo confuso es esperar sin saber por qué.

¿Debo ocultar el botón por completo durante el cooldown?

Yo no lo haría. Prefiero dejar el mismo botón desactivado con texto útil. Cuando desaparece del DOM, el flujo se siente inconsistente y aveces rompe foco o layout.

¿Qué pasa si el correo tarda mucho?

Añade una vía de escape después de cierto tiempo: revisar spam, editar dirección o pedir ayuda. El peor caso no es la latencia; es la sensación de que la interfaz te dejó solo.

Un buen flujo de reenvío en React no necesita más animación ni más complejidad. Necesita estados honestos, espacio estable y mensajes que bajen la duda en vez de amplificarla. Cuando eso está cuidado, la experiencia se nota más rapida, más clara y bastante más humana.

React: validación sin saltos ni foco roto

Silviu Technology — Tue, 21 Jul 2026 14:24:09 +0000

Los flujos de verificación por correo suelen romperse por detalles de interfaz, no por la API. Cuando el usuario pega una direccion de correo falsa para probar, o compara un mejor correo desechable con su email real, espera una pantalla estable, foco claro y mensajes que no cambien de sitio cada dos segundos. Si eso falla, la sensación de calidad cae bastante rapido.

Por qué el flujo falla aunque la API responda bien

En equipos frontend veo el mismo patrón una y otra vez: el backend entrega estados correctos, pero la UI empuja el contenido hacia abajo, cambia el botón por un spinner enorme o borra el foco al llegar un error. Eso afecta accesibilidad y tambien rendimiento percibido.

No es un detalle menor. Google considera bueno un CLS de 0.1 o menos, y explica por qué los saltos de layout dañan la experiencia en tareas sensibles como formularios y checkouts: https://web.dev/cls/. En verificación por correo el problema se nota mas, porque el usuario ya está esperando una respuesta externa.

También hay un tema de consistencia. Si el formulario muestra "Revisa tu inbox" y luego reemplaza todo por un bloque distinto, lectores de pantalla y usuarios de teclado pierden contexto. A veces no es un bug "grave", pero si es cansado, y termina subiendo abandono.

Tres decisiones de UI que estabilizan el formulario

La primera es reservar espacio para mensajes de estado. No esperes a que aparezca el error para crear el contenedor. Un bloque con min-height evita que el botón y el campo salten. Es simple, medio aburrido, pero funciona de verdad.

La segunda es mantener el foco donde aporta valor. Si la petición falla, devuelve el foco al campo o al resumen de error. Si la petición sale bien, muévelo a la confirmación solo cuando esa confirmación sea una región clara con aria-live. Hacer foco "porque sí" suele empeorar las cosas.

La tercera es no mezclar carga con desaparición. Puedes desactivar el botón y cambiar su etiqueta a "Enviando..." sin desmontarlo. Cuando reemplazas un botón entero por otro nodo, es facil perder estilos, foco y métricas. He visto este problema muchisimas veces en formularios React que parecían ya terminados.

Un ejemplo simple en React

Este patrón me gusta porque mantiene la estructura estable y hace visibles los estados para teclado y lector de pantalla, aunque sea un ejemplo chico:

import { useId, useRef, useState } from "react";

export function VerifyEmailForm() {
  const statusId = useId();
  const inputRef = useRef(null);
  const [email, setEmail] = useState("");
  const [status, setStatus] = useState("idle");
  const [message, setMessage] = useState("");

  async function onSubmit(event) {
    event.preventDefault();
    setStatus("loading");
    setMessage("Enviando enlace de verificación...");

    const response = await fetch("/api/verify-email", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ email })
    });

    if (!response.ok) {
      setStatus("error");
      setMessage("No pudimos enviar el correo. Revisa el campo e inténtalo otra vez.");
      inputRef.current?.focus();
      return;
    }

    setStatus("success");
    setMessage("Listo. Revisa tu bandeja de entrada para continuar.");
  }

  return (
    <form onSubmit={onSubmit}>
      <label htmlFor="email">Correo</label>
      <input
        id="email"
        ref={inputRef}
        type="email"
        value={email}
        onChange={(event) => setEmail(event.target.value)}
        aria-describedby={statusId}
      />

      <div id={statusId} aria-live="polite" style={{ minHeight: 24 }}>
        {message}
      </div>

      <button type="submit" disabled={status === "loading"}>
        {status === "loading" ? "Enviando..." : "Enviar verificación"}
      </button>
    </form>
  );
}

No resuelve todo, claro. Pero deja dos ventajas utiles: el layout no brinca, y el usuario entiende qué pasó sin pelear con la interfaz. Si además mides CLS en laboratorio y en campo, verás cambios pequeños pero bastante consistentes.

Cuando pruebo esto con cuentas de test, incluso usando cadenas raras como temp org mail dentro de casos internos, prefiero observar dos cosas: si el mensaje aparece en el mismo lugar y si el foco vuelve adonde debe. Parece obvio, pero muchas regresiones entran por ahí.

Si tu equipo además necesita coordinar pruebas de correo entre producto y operaciones, me gustó cómo otros posts explican probar correos de mantenimiento en equipos reales y medir fallos de verificacion sin friccion. Son buenos ejemplos de cómo conectar la UI con el resto del sistema, no solo con el componente.

Checklist rapido antes de publicar

Reserva espacio fijo para mensajes de estado.
Mantén el mismo botón durante la carga.
Usa aria-live="polite" para confirmaciones cortas.
Devuelve el foco al campo cuando el error bloquea la tarea.
Comprueba el flujo con teclado completo, no solo con mouse.
Revisa que el primer párrafo del estado sea corto y entendible, por que luego DEVs y QA lo leen muy rápido.

Preguntas que salen siempre

¿Debo mover el foco al mensaje de éxito?

Solo si el siguiente paso depende de leerlo enseguida. En muchos formularios basta con anunciar el cambio por aria-live y dejar el foco quieto. Menos movimiento suele ser mejor.

¿Y si el spinner cambia el ancho del botón?

Define un ancho mínimo o usa una etiqueta parecida en longitud. Otra opción es renderizar el spinner dentro del botón sin quitar el texto. No es elegante siempre, pero evita brincos feos.

¿Vale la pena medir esto si el backend ya va bien?

Sí. Si la interfaz pierde foco o desplaza el contenido, la tarea se siente lenta aunque la red responda rapido. En frontend, esa percepción pesa un monton.

Pequeños detalles de React, CSS y Accesibilidad suelen decidir si una verificación se siente confiable o improvisada. No hace falta una arquitectura enorme; hace falta una interfaz estable, clara y un poco menos ansiosa.

React: evita saltos en flujos de verificación

Silviu Technology — Tue, 21 Jul 2026 08:24:21 +0000

Cuando una pantalla de verificación de email se siente torpe, casi siempre pensamos en el backend primero. Pero muchas veces el problema real está en el frontend: el mensaje aparece tarde, el botón salta de sitio y el foco queda raro justo cuando la persona necesita claridad. En equipos de producto esto se nota enseguida, porque una UI que cambia demasiado durante la espera da una sensación medio rota aunque la API responda bien.

En flujos de registro o login, ese detalle importa mas de lo que parece. Web.dev explica que el Cumulative Layout Shift mide cambios inesperados en el layout que afectan percepción y usabilidad, y eso pega de lleno en formularios, banners de error y mensajes de confirmación. Si encima tu QA usa una direccion de correo desechable o un correo de usar y tirar para repetir pruebas rápido, cualquier salto visual hace mas dificil distinguir si falló la entrega o falló la interfaz.

Por que el layout shift rompe mas de lo que parece

He visto este patrón varias veces: el usuario envía el formulario, React muestra un spinner minimo, luego entra un mensaje de éxito de dos líneas, y por ultimo aparece un CTA adicional. Todo funciona, pero el bloque cambia de altura tres veces. En desktop molesta; en móvil se siente peor, porque el dedo ya iba hacia un lugar que dejó de existir.

Ese tipo de salto no solo se ve feo. También complica accesibilidad. Si el contenido principal cambia de posición mientras un lector de pantalla anuncia una región viva, la experiencia queda un poco confusa. No es un bug enorme ni glamuroso, pero sí una fuente muy real de friccion.

Una pista util: si soporte recibe capturas de una pantalla "que parpadea" o QA dice que el estado "se mueve solo", yo reviso layout antes que lógica. A veces nos vamos directo a depurar fetches, cuando el problema era muchisimo más terrenal.

Que medir antes de tocar el CSS

Antes de cambiar componentes, intento observar tres cosas:

Cuánto cambia la altura del contenedor entre idle, loading, success y error.
Si el foco termina en un encabezado o mensaje estable.
Si el CTA principal conserva posición aproximada entre estados.

No hace falta montar una auditoría gigante. Un perfil básico con Lighthouse ya deja ver si la pantalla castiga CLS, y el propio equipo de Chrome recomienda reservar espacio para contenido dinámico cuando sabes que va a llegar después. En auth flows eso aplica a mensajes, ayudas inline y bloques de acciones secundarias.

También conviene separar el problema de entrega del problema visual. Si tu equipo ya tiene un proceso para revisar emails de reactivacion trial sin mezclar señales, úsalo como capa de validación externa. Así sabes si el correo llegó bien antes de discutir si React se desordenó durante la espera.

Y aquí aparece algo muy cotidiano: en notas internas alguien pone tempail o fake e mail com porque va deprisa. No pasa nada. Lo que sí conviene evitar es que el procedimiento de prueba dependa de nombres improvisados y no de estados verificables.

Un patron simple de React para reservar espacio

La idea mas útil que me ha funcionado es aburrida, y justo por eso sirve: reservar espacio desde el inicio. En vez de dejar que cada estado crezca libremente, defino un bloque con altura mínima razonable, encabezado persistente y zona de acciones estable.

type VerifyState = "idle" | "loading" | "success" | "error";

const messages: Record<VerifyState, string> = {
  idle: "Revisa tu email para continuar",
  loading: "Validando enlace...",
  success: "Email verificado, ya puedes seguir",
  error: "No pudimos validar el enlace"
};

export function VerifyPanel({ state }: { state: VerifyState }) {
  return (
    <section className="verify-panel" aria-live="polite">
      <h1 tabIndex={-1}>Verificación de cuenta</h1>
      <p className="verify-copy">{messages[state]}</p>
      <div className="verify-actions">
        <button>Volver al acceso</button>
      </div>
    </section>
  );
}

.verify-panel {
  min-block-size: 16rem;
  display: grid;
  align-content: start;
  gap: 0.75rem;
}

.verify-copy {
  min-block-size: 3.5rem;
}

.verify-actions {
  min-block-size: 2.5rem;
}

No es una receta magica, pero reduce sorpresas. El mensaje puede cambiar, el layout no tanto. Esto además facilita testing visual, porque la diff entre estados deja de ser un terremoto y pasa a ser un cambio legible.

Si el flujo se integra con automatizaciones o pruebas repetidas, tener entradas y salidas predecibles también ayuda a diseñar mejores contratos de inbox para automatizaciones mas estables. Aunque ese artículo va por otra capa del sistema, comparte una idea que me gusta mucho: menos ambigüedad en cada tramo del flujo.

Como probar el flujo completo con bandejas aisladas

Cuando QA revisa verificación de email en frontend, yo no me quedo solo con "llegó el correo". Prefiero este mini checklist:

Enviar el formulario desde una viewport móvil y otra desktop.
Abrir el enlace de verificación y comprobar que el título principal no salta de sitio.
Revisar con teclado que el foco sigue una ruta entendible.
Comparar estados loading, success y error con capturas o snapshots.

Si la prueba usa una bandeja temporal para repetir escenarios, mejor todavía. Ahí es donde una direccion de correo desechable ahorra tiempo y hace mas simple aislar señales. Pero el objetivo no es el inbox en sí; el objetivo es ver si la transición completa se siente estable, clara y rapida.

Otra cosa que conviene mirar: errores largos. Muchos equipos escriben un mensaje corto para éxito y un párrafo entero para error. Resultado: el estado que peor se siente también es el que más mueve la interfaz. Yo intento mantener una caja estable y poner detalles extendidos detrás de un enlace o bloque secundario. Es una decisión simple, pero suele arreglar bastante UX con poco codigo.

Preguntas frecuentes

¿Hace falta medir CLS en una pantalla tan pequeña?

Sí. Justo en estos flujos pequeños es donde un salto de layout cambia la percepción del producto completo. Parece un detalle menor, pero no lo es.

¿Reservar espacio no deja huecos feos?

Un poco, a veces. Pero prefiero un layout quieto a una interfaz nerviosa. Con buen ritmo visual y copy corto, el compromiso suele valer la pena.

¿Esto mejora también accesibilidad?

Sí, porque combina estabilidad visual con mensajes más previsibles y rutas de foco mas limpias. No resuelve todo, pero deja una base bastante sana para seguir iterando.

Cypress Email Retries Need Inbox Leases

Silviu Technology — Mon, 20 Jul 2026 23:23:57 +0000

I have seen plenty of end-to-end suites look stable in the dashboard while the email step was quietly cheating. A retry fires, the test passes on the second attempt, and everyone moves on. Later, a real bug slips through because the passing run actually read a message from the first attempt. That kind of flake is annoyng because it feels random until you inspect the timeline closely.

For QA work, I now treat mailbox ownership as part of the test contract. If a Cypress spec can retry, parallelize, or resume after a failed setup step, it needs an inbox lease tied to that attempt. That does not mean building a huge system. It means one test run claims one inbox for a short window, tags every message with the same trace value, and cleans up when the assertion is done.

Why retries create false confidence

Email assertions fail in a few predictable ways:

a second attempt reads the first attempt's message
two workers poll the same mailbox during parallel Automation runs
the app sends a valid email, but later than the test expected
cleanup happens too slowly, so yesterday's mail still looks fresh enough

This is where a use and throw email setup helps, but only if it is wrapped in rules. The disposable mailbox is not the strategy by itself. The strategy is ownership, expiration, and traceability. That is also why I like articles about traceable email verification: they focus on proving which run produced which message, not just "something arrived."

When teams skip that piece, they start saying weird stuff like "the retry probably picked the right email, looks fine." It might be fine. It might also be silently reading the wrong artifact and teaching the suite to lie.

What an inbox lease actually solves

An inbox lease is just a short claim:

lease_id maps to the test attempt
owner maps to the spec name or worker
expires_at prevents stale reuse
trace_id appears in the app payload and assertion logs

That tiny bit of metadata does a lot. If a retry starts, it requests a new lease instead of inheriting the old mailbox. If the app is slow, the waiting logic can say "this message belongs to lease B, ignore it for lease C." If a test crashes mid-run, the cleanup job can sweep expired leases later. It is not fancy, but it is very, very practical.

For teams that need a quick mailbox source, I have used a disposable email address provider in test environments, but the helpful part was always the lease wrapper around it. The provider gives you the inbox. Your test harness decides who owns it and for how long.

A Cypress workflow that survives reruns

The workflow below is small enough to keep in a real repo:

Before the spec starts, request an inbox lease from a helper service.
Store leaseId, inboxAddress, and traceId in Cypress env.
Pass traceId through the signup or reset flow.
Poll only messages attached to the active lease.
Release the lease in afterEach, even if the assertion fails.

Here is the rough shape:

beforeEach(() => {
  cy.task("leaseInbox").then((lease) => {
    Cypress.env("leaseId", lease.id);
    Cypress.env("inboxAddress", lease.address);
    Cypress.env("traceId", lease.traceId);
  });
});

it("verifies the reset email for this attempt only", () => {
  cy.request("POST", "/test/reset", {
    email: Cypress.env("inboxAddress"),
    traceId: Cypress.env("traceId"),
  });

  cy.task("waitForLeaseMessage", {
    leaseId: Cypress.env("leaseId"),
    traceId: Cypress.env("traceId"),
  }).then((message) => {
    expect(message.subject).to.include("Reset your password");
    expect(message.html).to.include(Cypress.env("traceId"));
  });
});

afterEach(() => {
  cy.task("releaseInbox", { leaseId: Cypress.env("leaseId") });
});

The key is that waitForLeaseMessage should filter on both lease and trace ID. If you only match on recipient address, reruns can still collide. That bug is more common than teams admit, and it makes the suite feel haunted for no good reason.

Where the temp inbox fits without taking over the article

I do not think every QA guide needs to become a pitch for inbox tools. Most of the value comes from test design. Still, if you need a short-lived mailbox pool for CI, a disposable email account can be useful as plumbing behind the lease service. The important thing is keeping the mailbox lifecycle small and boring:

create one inbox per attempt
tag the app request with a trace value
reject messages outside the lease window
archive logs with lease IDs when a test fails

That pattern also lines up with general flake-reduction guidance. Cypress itself recommends controlling external side effects and avoiding shared mutable state in end-to-end tests because nondeterminism is where false passes and false failures begin (Cypress best practices). Different stack, same lesson basicly.

One extra note: if somebody still writes "send it to the dummy e mail inbox" in the runbook, update the runbook. Name the mailbox source, state the retention window, and document who clears expired leases. Tiny docs fixes save suprising amounts of debug time.

A checklist for less flaky email tests

Before I trust a Cypress email check, I want these boxes ticked:

each retry gets a fresh lease, not a reused address
the app payload includes a trace ID or attempt ID
polling filters by lease and trace, not just by subject
expired inboxes are cleaned automatically
failure logs show the lease ID, worker, and timestamps
parallel jobs never share the same mailbox pool record

If you only change one thing this week, make it the lease boundary. That one fix removes a lot of spooky behavior from test reruns, and it gives QA engineers a cleaner story when a failure is real.

Q&A

Do I need a lease system for every product email test?

Not always. If the flow is single-threaded and never retries, a lighter setup may be enough. But once retries or parallel workers enter the picture, leases pay for themself pretty fast.

Why not just delete all messages before each test?

Because deletion is a weak ownership model. Slow delivery, duplicate sends, and parallel specs can still race each other. A fresh lease is more explicit and easier to audit later.

What usually breaks first?

In my experiance, teams either forget to pass a trace ID through the app flow or they reuse the same mailbox between attempts. Both issues make failures harder to trust, even when the test looks green.

Contratos de inbox para agentes LLM

Silviu Technology — Mon, 20 Jul 2026 17:24:12 +0000

Cuando un agente LLM dispara correo, el bug molesto no suele estar en el texto final. Suele estar en la evidencia: una inbox compartida, un assert flojo o una corrida que pisa a otra. En varios equipos he visto la misma escena, mas o menos: el agente "parece" correcto, pero nadie puede probar qué acción produjo qué mensaje. Sin ese borde claro, la automatización se vuelve cara de operar.

Mi forma de pensarlo es bastante simple. El sistema no termina en el prompt ni en la tool call. Termina cuando puedes mirar una corrida concreta, abrir su evidencia y decidir en pocos minutos si el flujo está sano o no. Ahí es donde un contrato de inbox bien definido hace diferencia real para LLMs y Automatización.

El contrato correcto empieza en la inbox

Si la herramienta de correo solo recibe to, subject y body, el agente queda con demasiada libertad y el equipo con muy poca trazabilidad. Prefiero modelar una inbox de prueba como una pieza de arquitectura, no como un detalle de QA.

Ese contrato mínimo debería incluir:

run_id
scenario_key
recipient_alias
expected_template
assertion_window
evidence_retention

Eso evita una clase entera de fallos raros. Dos corridas pueden usar el mismo backend, incluso la misma feature flag, pero nunca deberían competir por la misma bandeja lógica. Si ya estás trabajando en versionar acciones de correo en agentes, este paso completa la frontera: acción cerrada por un lado, evidencia aislada por el otro.

También ordena el vocabulario del equipo. Mucha gente mezcla términos como inbox temporal, correo de usar y tirar o incluso cosas medio rotas que quedan en tickets, como tepm mail com. No es grave por sí mismo, pero muestra que el flujo aún depende más del contexto humano que de un contrato reproducible.

Qué campos hacen la evidencia reutilizable

Para mí, una prueba de correo útil necesita responder cuatro preguntas sin leer veinte logs:

¿Qué acción pidió el agente?
¿Qué inbox quedó reservada para esa corrida?
¿Qué mensaje terminó llegando?
¿Qué aserción de negocio se validó al final?

Un payload pequeño puede cubrirlo:

{
  "run_id": "eval_2026_07_21_001",
  "scenario_key": "signup_magic_link",
  "recipient_alias": "signup-eval-001",
  "expected_template": "magic_link_v3",
  "assertion_window": "120s",
  "evidence_retention": "24h"
}

Con algo así, el ejecutor deja de "interpretar" y pasa a validar. Además, puedes separar mejor qué vive en la capa del agente y qué vive en la capa de la tool. El agente decide el caso; la tool garantiza aislamiento, consulta y retención. Ese reparto suele bajar bastante el tiempo de debugging, y va en la misma línea que reportes de entrega como DORA, que asocian feedback claro y ciclos cortos con mejor desempeño operativo source.

Un flujo simple para equipos pequeños

No hace falta montar una plataforma gigante. Para un equipo chico, yo empezaría así:

La corrida crea un run_id y reserva una inbox lógica única.
El agente elige una acción cerrada y una ventana de espera explícita.
El ejecutor persiste request, metadata y resultado en el mismo sobre de evidencia.
La prueba consulta solo esa inbox y valida contenido, destinatario y efecto final.
La limpieza expira la evidencia sin tocar corridas activas.

Ese patrón también viene bien cuando necesitas aislar emails por branch en FastAPI. Branches, retries y escenarios manuales tienden a contaminarse entre sí si comparten naming o retention policy.

Cuando necesito un enlace contextual para explicar el tipo de proveedor que encaja aquí, suelo hablar de servicios tipo temp mail com. No por el marketing, sino porque la idea de fondo importa: inbox efímera, consulta determinista y eliminación predecible. Si el proveedor no te da eso, la herramienta puede verse comoda al inicio, pero luego castiga cada suite paralela.

Tradeoffs y checkpoints antes de publicarlo

Este diseño mete más estructura, sí. Pero casi siempre paga solo:

Más ids y metadata, pero menos ambigüedad.
Un setup un poco más estricto, pero corridas mucho mas auditables.
Menos magia en demos, pero mejor operación diaria.

Mis checkpoints antes de darlo por bueno son estos:

Cada corrida reserva una inbox única o un alias exclusivo.
La tool rechaza lecturas sin run_id o scenario_key.
La evidencia tiene TTL y dueño claro.
La aserción final valida negocio, no solo "llegó un correo".
El historial permite reconstruir fallos sin reejecutar todo.

Si uno de esos puntos falta, el sistema aún depende demasiado de memoria humana. Y eso no escala, especialmente cuando varios agentes o pipelines corren a la vez.

Preguntas frecuentes

¿Cuándo conviene una inbox por escenario y no por usuario?

Cuando estás probando concurrencia, retries o ramas paralelas. Por usuario suele ser demasiado amplio y genera cruces dificiles de explicar después.

¿Hace falta guardar el prompt completo?

No siempre. Normalmente basta con la acción elegida, los ids de contexto y el resultado normalizado de la tool. Guardar más ruido no necesariamente ayuda.

¿Esto aplica fuera de LLMs?

Sí. La diferencia es que con agentes el beneficio aparece antes, porque la frontera entre decisión y ejecución necesita ser aburrida, estable y muy legible.

FastAPI: evita correos duplicados al reintentar

Silviu Technology — Sat, 18 Jul 2026 23:24:17 +0000

Cuando una API de registro o verificación falla a medias, el equipo suele reintentar rapido. El problema es que ese segundo intento muchas veces manda un correo extra aunque el primero ya estaba en cola. En FastAPI esto pasa bastante cuando el endpoint responde antes de que el worker termine y nadie define una clave idempotente para el envio.

En proyectos pequeños no hace falta montar una arquitectura enorme para corregirlo. Lo que sí conviene hacer es separar dos decisiones: "la app debe enviar este correo" y "el proveedor ya recibió este correo". Esa distinción evita varios sustos, sobre todo cuando soporte empieza a ver usuarios con dos links de verificación distintos y no sabe cual abrió primero.

Por que los reintentos duplican correos

El patrón que veo más seguido es este:

El cliente llama POST /verify-email.
La API crea un token y encola el envio.
La conexión se corta o el worker tarda más de lo esperado.
El cliente reintenta.
El backend vuelve a crear otro envio porque no sabe que el primero ya existía.

Eso genera ruido para producto, para soporte y para métricas. También rompe pruebas de staging, porque una bandeja compartida ya no deja claro qué mensaje corresponde al escenario actual. En temas de trazabilidad, me gusta bastante esta idea de automatizacion de correos entre servicios: si el flujo cruza varios componentes, hay que dejar un identificador estable y visible entre ellos.

Un patron simple para volver idempotente el envio

La versión más simple que me ha funcionado usa una tabla email_jobs con una clave única por intención de negocio. Por ejemplo:

user_id
template
intent_key
status
provider_message_id

intent_key puede ser algo como verify-email:<user_id>:<version>. Si entra el mismo request otra vez, la API no crea un nuevo job. Solo devuelve el existente o confirma que el envío ya está programado. Ese pequeño detalle suele bajar muchisimo los duplicados.

Si además quieres una bandeja temporal para validar el flujo completo de extremo a extremo, un correo burner puede servir para aislar pruebas manuales o smoke tests. No lo volvería el centro del sistema, pero ayuda cuando necesitas comprobar que solo salió un mensaje real y no tres variaciones casi iguales.

Lo importante es que la idempotencia viva en tu backend, no en la paciencia del equipo. Si dependes de "ojalá el cliente no reintente" o "ojalá el proveedor ignore duplicados", tarde o temprano pagas ese atajo.

Ejemplo pequeno con FastAPI y PostgreSQL

Una implementación minima puede verse así:

from fastapi import FastAPI, HTTPException

app = FastAPI()

def build_intent_key(user_id: str, version: int) -> str:
    return f"verify-email:{user_id}:{version}"

@app.post("/verify-email")
def send_verification_email(user_id: str, version: int = 1):
    intent_key = build_intent_key(user_id, version)

    job = find_email_job(intent_key)
    if job:
        return {"ok": True, "status": job["status"], "intent_key": intent_key}

    created = create_email_job(
        user_id=user_id,
        template="verify-email",
        intent_key=intent_key,
    )
    if not created:
        raise HTTPException(status_code=409, detail="job_conflict")

    enqueue_email_job(intent_key)
    return {"ok": True, "status": "queued", "intent_key": intent_key}

No es un sistema completo, claro, pero muestra la idea central: primero registras la intención, luego encolas el trabajo. Si el request vuelve, respondes usando el mismo intent_key. En PostgreSQL esto suele quedar bien con un índice único y un INSERT ... ON CONFLICT DO NOTHING.

Donde varios equipos se tropiezan es en regenerar el token cada vez que reintentan. Ahí el correo A y el correo B ya no son equivalentes, así que el usuario recibe dos links validos o uno válido y otro vencido. Ese escenario es molesto de depurar y bastante feo para la experiencia final, la verdad.

Como probarlo sin contaminar bandejas

Para verificar que la solución funciona, intentaría algo muy concreto:

Crear un usuario de prueba nuevo.
Llamar dos veces al endpoint con el mismo intent_key.
Confirmar que solo existe un email_job.
Revisar que la bandeja recibe un solo mensaje.
Abrir el link y validar el estado final del usuario.

Si ya vienes probando flujos parecidos, te puede servir este artículo sobre probar emails transaccionales en FastAPI. La lección que más rescato es no mezclar trazabilidad con intuición: si API, worker y bandeja no comparten una clave, cualquier debug termina siendo medio artesanal.

También pondría atención a las notas improvisadas del equipo. Cuando en Slack o en un ticket aparece algo como tepm mail com, normalmente no es solo un typo gracioso. Suele ser la señal de que el procedimiento manual todavía está difuso y cualquiera puede terminar revisando una bandeja incorrecta o un run viejo.

Preguntas frecuentes

¿Debo resolverlo con locks distribuidos?

No siempre. Para muchos productos basta una clave única de negocio y una cola razonable. Los locks ayudan cuando hay mucha concurrencia real, pero meterlos demasiado pronto complica el backend sin necesidad.

¿`BackgroundTasks` alcanza?

Para volumen bajo, sí. Si necesitas reintentos, observabilidad y control más fino, prefiero un worker dedicado con una tabla de jobs. Es menos elegante en teoria, pero en producción suele ser más facil de operar.

¿Qué reviso primero si siguen saliendo duplicados?

Primero miraría si el intent_key cambia entre intentos. Después revisaría si el worker vuelve a crear el envio en vez de consumir el job ya registrado. Es un fallo pequeño, pero aparece más veces de lo que deberia.

React: loaders honestos para flujos lentos

Silviu Technology — Sat, 18 Jul 2026 17:25:10 +0000

En frontend solemos dedicar mucho tiempo a la vista final y bastante menos al tiempo de espera. Es curioso, porque esa espera aparece en momentos delicados: enviar un formulario, activar una cuenta, validar permisos o esperar un email de confirmación. Si el loader se siente falso, la interfaz pierde credibilidad muy rapido.

Lo he visto sobre todo en productos donde el flujo depende de varios sistemas. El usuario pulsa un botón, aparece un spinner perfecto, pero nadie explica si faltan dos segundos o treinta. En pruebas internas, incluso cuando alguien usa un generador de correo desechable para validar onboarding o anota algo como temp gamil com, el problema real no es la latencia sola. El problema es no saber si la app sigue trabajando o si ya se quedo colgada.

Por qué un loader puede romper la confianza

Muchos loaders fallan por una razon simple: muestran actividad, pero no contexto. Un spinner girando no dice si la petición llegó, si falta una confirmación externa o si hay que revisar otra pantalla.

Cuando eso pasa, suelen aparecer tres conductas:

la persona hace clic otra vez
abre otra pestaña por inseguridad
abandona porque asume que algo salio mal

Ese comportamiento no es raro. Google lleva años recomendando estados de progreso claros para reducir incertidumbre y mejorar la percepción de rapidez (https://m3.material.io/components/progress-indicators/overview). No basta con "decorar" la espera. Hay que explicar qué está ocurriendo y cuál es la siguiente señal que debe observar el usuario.

También me gusta pensar estos estados con la misma disciplina que usamos para construir contratos de email que siguen siendo comprobables. Si un flujo asincrono no comunica bien sus etapas, el usuario termina interpretando síntomas en vez de entender el sistema.

Qué debe comunicar un buen estado de espera

Un loader útil no necesita mucho texto, pero sí necesita intención. Normalmente intento cubrir estas cuatro piezas:

Qué acción se está procesando.
Qué paso externo puede tardar.
Qué debería hacer la persona mientras tanto.
Cuándo conviene preocuparse de verdad.

Por ejemplo, "Cargando..." casi nunca alcanza. En cambio, "Estamos enviando tu enlace de verificación. Suele tardar menos de 20 segundos" orienta mucho mejor. Si además agregas "puedes seguir en esta pantalla", bajas la ansiedad un monton.

En apps donde backend y frontend trabajan por separado, también ayuda nombrar el origen del retraso sin tecnicismos innecesarios. Decir "esperando confirmación del servicio de email" suele ser más honesto que mostrar un spinner infinito y listo. Esa claridad se vuelve aun más valiosa cuando el equipo ya ha invertido en emails aislados por branch: si internamente separas estados y causas, la UI deberia reflejar esa misma precision.

Un patron en React para loaders honestos

En vez de tener un booleano isLoading para todo, me funciona mejor modelar el estado como fases. Así evitas mensajes ambiguos y puedes adaptar el feedback segun el paso real.

type SubmitPhase = "idle" | "sending" | "waiting_email" | "done" | "error";

const phaseCopy: Record<SubmitPhase, { title: string; message: string }> = {
  idle: {
    title: "Listo para enviar",
    message: "Completa el formulario y continua.",
  },
  sending: {
    title: "Enviando solicitud",
    message: "Estamos guardando tus datos ahora mismo.",
  },
  waiting_email: {
    title: "Revisa tu bandeja",
    message: "El enlace de verificación suele llegar en menos de 20 segundos.",
  },
  done: {
    title: "Todo listo",
    message: "Tu cuenta ya quedó verificada.",
  },
  error: {
    title: "No pudimos completar el proceso",
    message: "Vuelve a intentarlo o revisa tu conexión.",
  },
};

Y el componente:

function ProgressNotice({ phase }: { phase: SubmitPhase }) {
  const copy = phaseCopy[phase];

  return (
    <section aria-live="polite" className="progress-notice">
      <h2>{copy.title}</h2>
      <p>{copy.message}</p>
      {phase === "sending" || phase === "waiting_email" ? (
        <div className="spinner" aria-hidden="true" />
      ) : null}
    </section>
  );
}

No es una arquitectura revolucionaria, pero mejora bastante el comportamiento de la interfaz. También hace más facil medir cada fase por separado. Si notas que la mayoría de usuarios pasa demasiados segundos en waiting_email, ya no culpas al frontend por intuición nomas. Tienes una pista concreta para investigar.

Detalles de accesibilidad y CSS que importan

Hay varios matices pequeños que cambian mucho la experiencia:

Usa aria-live="polite" cuando el contenido cambie tras una acción del usuario.
No reemplaces toda la pantalla si solo cambia una parte del flujo.
Evita loaders gigantes con mucho movimiento si la acción tarda poco.
Acompaña el spinner con texto; el icono solo se queda medio vacio semánticamente.

En CSS suelo preferir un bloque estable, con jerarquía de texto clara, antes que un overlay invasivo:

.progress-notice {
  display: grid;
  gap: 0.75rem;
  padding: 1rem 1.25rem;
  border: 1px solid var(--border-subtle);
  border-radius: 14px;
  background: linear-gradient(180deg, #fffdf7, #fff8ec);
}

.progress-notice p {
  max-width: 52ch;
  color: var(--text-muted);
}

Sobre rendimiento percibido, una referencia util es el Web Almanac, que sigue mostrando el costo real de añadir JavaScript y complejidad extra a la experiencia web (https://almanac.httparchive.org/en/2024/javascript). A veces un loader "sofisticado" añade más peso del que compensa. Se ve bonito en review, pero en producción queda un poco meh si retrasa el render o distrae demasiado.

Q&A rapida

¿Skeleton o spinner?

Si ya sabes la forma del contenido que va a aparecer, skeleton. Si el sistema está procesando una accion donde el resultado puede variar, prefiero texto + spinner pequeño. Mezclar ambos sin criterio suele confundir.

¿Hace falta mostrar tiempos estimados?

Solo cuando tienes datos razonables. Inventar "5 segundos" y fallar seguido erosiona confianza. Mejor usar rangos prudentes, o frases como "suele tardar menos de 20 segundos".

¿Debo bloquear toda la interfaz?

No siempre. Si el usuario todavía puede leer, corregir o navegar sin romper el flujo, deja esas opciones activas. Bloquear todo por costumbre vuelve la app torpe y un poco brusca.

Checklist para revisar antes de enviar

El loader explica qué está ocurriendo, no solo que "algo pasa".
El texto distingue entre espera interna y dependencia externa.
La fase de carga tiene una salida clara o un umbral de error.
El componente usa accesibilidad básica sin sobreanunciar cambios.
El estilo visual acompaña la espera sin volverla mas pesada.

Los loaders honestos no hacen magia con la latencia, pero sí mejoran la relación entre la persona y el sistema. Cuando la interfaz explica bien la espera, el producto parece más confiable, más cuidado y bastante menos fragil.