DEV Community

Hannah
Hannah

Posted on

SaaS: un contrato de correo para onboarding

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:

  1. El usuario envía el formulario.
  2. El Backend crea una cuenta pendiente.
  3. Se solicita un mensaje de verificación.
  4. El proveedor acepta o rechaza el envío.
  5. 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"
}
Enter fullscreen mode Exit fullscreen mode

Hay tres promesas importantes:

  • Identidad: event_id es único y permite repetir la operación sin duplicar mensajes.
  • Propiedad: run_id relaciona el correo con una ejecución de prueba o con una solicitud concreta.
  • Tiempo: expires_at marca 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
Enter fullscreen mode Exit fullscreen mode

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:

  1. API: el registro de cuenta produce un único event_id.
  2. Cola: el mensaje contiene el mismo event_id.
  3. Bandeja de prueba: aparece un mensaje para el run_id correcto.
  4. Enlace: un token válido activa la cuenta una sola vez.
  5. 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)