SaaS: un contrato de correo para onboarding
El onboarding de un SaaS suele parecer sencillo: crear la cuenta, enviar un correo y activar al usuario. En la práctica, el correo es una frontera entre varios servicios. Si esa frontera no tiene un contrato claro, el equipo recibe errores como “no llegó el email” sin saber si falló el backend, el proveedor o la prueba.
En mis experimentos de producto, separar esa responsabilidad hizo que el flujo fuera mas fácil de probar. La idea no es construir un sistema enorme. Es acordar qué evento se emite, qué datos se guardan y qué puede esperar cada consumidor.
El problema: el correo como caja negra
Un flujo de onboarding puede pasar por estas etapas:
- El usuario envía el formulario.
- El Backend crea una cuenta pendiente.
- Se solicita un mensaje de verificación.
- El proveedor acepta o rechaza el envío.
- El usuario abre el enlace y la cuenta pasa a activa.
Cuando todo ocurre rápido, parece una sola operación. Pero cada paso tiene su propio fallo. Una cola puede retrasar el mensaje, un reintento puede crear dos solicitudes, o una prueba puede leer el mensaje de otra ejecución. A veces no queda claro que paso primero.
Por eso conviene tratar el correo como un contrato observable, no como un efecto secundario escondido dentro de create_user().
Qué debe prometer el contrato
Un contrato útil puede ser un evento llamado verification_email_requested. No importa si el transporte final es SMTP, una API o una cola interna. El evento debe incluir lo mínimo para que otro servicio pueda trabajar sin adivinar:
{
"event_id": "evt_01J9K3",
"account_id": "acc_2048",
"run_id": "onboarding_2026_11_18_42",
"template": "verify-account",
"recipient_hash": "sha256:...",
"created_at": "2026-11-18T08:20:00Z",
"expires_at": "2026-11-18T09:20:00Z"
}
Hay tres promesas importantes:
-
Identidad:
event_ides único y permite repetir la operación sin duplicar mensajes. -
Propiedad:
run_idrelaciona el correo con una ejecución de prueba o con una solicitud concreta. -
Tiempo:
expires_atmarca cuándo deja de ser válido el enlace.
El contrato tambien debe definir los estados. Por ejemplo: requested, accepted, delivered, opened, verified y expired. No siempre podrás observar todos, pero los estados disponibles deben distinguir un rechazo del proveedor de un usuario que todavía no abrió el mensaje.
Una implementación pequeña
En una aplicación nueva, un registro en la base de datos puede ser suficiente:
def request_verification(account_id, recipient, now, db, mailer):
event = db.find_open_verification(account_id)
if event and event.expires_at > now:
return event
event = db.create_verification_event(
account_id=account_id,
recipient_hash=hash_recipient(recipient),
expires_at=now + timedelta(hours=1),
)
mailer.enqueue(event_id=event.id, template="verify-account")
return event
El detalle importante es buscar primero un evento abierto. Sin esa lectura, dos clics del usuario o un reintento del navegador pueden producir varios correos. En el panel de soporte, mostrar el event_id y su estado ayuda mas que mostrar solamente “enviado”.
Para pruebas de integración, usa una bandeja aislada por run_id. No mezcles mensajes de dos ejecuciones y no dependas solo del asunto. Incluso una dirección escrita como tepm mail com en datos de prueba puede revelar que el caso probado era inválido, pero no debe confundirse con una dirección real ni entrar en producción.
Pruebas y señales de diagnóstico
Una prueba básica debería comprobar el contrato en capas:
-
API: el registro de cuenta produce un único
event_id. -
Cola: el mensaje contiene el mismo
event_id. -
Bandeja de prueba: aparece un mensaje para el
run_idcorrecto. - Enlace: un token válido activa la cuenta una sola vez.
- Repetición: repetir la misma petición no crea otra activación.
Guarda también la razón de cada transición: provider_rejected, message_found, token_used o deadline_reached. Esa evidencia permite diferenciar una demora real de una aserción mal diseñada. En jobs programados, conviene mirar señales útiles para jobs frágiles, porque la misma regla aplica: una ejecución debe dejar señales que expliquen su estado.
Si el test falla, no aumentes el timeout de inmediato. Primero pregunta: ¿el evento existe?, ¿la bandeja pertenece a este run?, ¿el proveedor aceptó el envío? Un timeout mas largo puede esconder una carrera.
Errores comunes
- Guardar el token en logs normales. Es información sensible y además distrae del diagnóstico.
- Usar el asunto como identificador único. Dos pruebas pueden compartirlo.
- Borrar el registro al terminar. Mantén una pequeña ventana de evidencia para investigar.
- Reintentar sin idempotencia. Cada retry tienen que reutilizar el evento o crear uno nuevo de forma explícita.
- Mezclar datos reales con fixtures. Las pruebas deben ser reproducibles y faciles de limpiar.
Un buen contrato no resuelve todos los problemas de entrega, pero hace visible dónde está el problema. Tambien reduce el trabajo manual del equipo de producto cuando un usuario dice que no recibió el mensaje.
Recapitulación
Para un onboarding de SaaS más confiable:
- Define un evento de verificación con identidad, propiedad y caducidad.
- Usa estados que expliquen el ciclo de vida del correo.
- Haz que los reintentos sean idempotentes.
- Aísla cada fixture de prueba por ejecución.
- Conserva señales suficientes para explicar un fallo.
Este contrato es pequeño, pero cambia la conversación. En lugar de preguntar “¿por qué no llegó el correo?”, el equipo puede preguntar en qué estado quedó la solicitud y qué evidencia falta. Eso es mucho más útil para construir y mejorar un producto.
Top comments (0)