Saltar al contenido principal

📧 Sistema de Emails

Floutic utiliza un sistema de emails transaccionales completo gestionado desde el backend. Todos los emails se envían automáticamente en respuesta a eventos específicos del sistema.

🏗️ Arquitectura​

Los emails transaccionales se gestionan desde el backend de FastAPI usando:

  • Templates Jinja2 - Templates HTML versionados en código
  • SMTP - Envío directo desde el backend
  • Generación automática de texto plano - Para clientes sin soporte HTML

Los emails de marketing y campañas se gestionan desde GoHighLevel (complementarios, no críticos).

📋 Tipos de Emails por Rol​

👥 Emails para Empresas​

1. Bienvenida (welcome_company.html)​

Cuándo se envía: Al registrarse y verificar el email como empresa.

Contenido:

  • Mensaje de bienvenida personalizado
  • Qué pueden esperar de Floutic
  • Invitación a sesión Discovery (30-45 minutos)
  • Preparación para la sesión Discovery
  • Contacto: soporte_empresas@floutic.com

Variables:

  • {{ username }} - Nombre de la empresa
  • {{ kickoff_url }} - URL del calendario Discovery (opcional)

2. Match Confirmado (match_confirmed_company.html)​

Cuándo se envía: Cuando se confirma un match con un experto.

Contenido:

  • Presentación del experto asignado (nombre, perfil, experiencia)
  • Canal de comunicación compartido
  • Próximos pasos detallados:
    1. Presentarse en el canal con contexto del negocio
    2. Revisar hitos y prioridades de la sesión Discovery
    3. Acordar el primer hito a ejecutar
    4. Contacto directo para dudas
  • Contacto: soporte_empresas@floutic.com

Variables:

  • {{ company_name }} - Nombre de la empresa
  • {{ expert_name }} - Nombre del experto
  • {{ expert_role }} - Rol/especialidad del experto
  • {{ expert_experience }} - Experiencia del experto
  • {{ chat_url }} - URL del canal de chat
  • {{ project_title }} - Título del proyecto (opcional)

3. Solicitud de Reseña (request_review.html)​

Cuándo se envía: Automáticamente cuando un proyecto se completa.

Contenido:

  • Agradecimiento por confiar en Floutic
  • Solicitud de valoración interna rápida (1 minuto)
  • Invitación a dejar reseña pública del experto
  • Enlaces a formularios de feedback y reseña
  • Contacto: soporte_empresas@floutic.com

Variables:

  • {{ company_name }} - Nombre de la empresa
  • {{ project_title }} - Título del proyecto
  • {{ project_reference }} - Referencia del proyecto (ej: "#123 - Proyecto Test")
  • {{ feedback_url }} - URL del formulario de feedback (opcional)
  • {{ review_url }} - URL para dejar reseña (se genera automáticamente si no se proporciona)

🎓 Emails para Expertos​

1. Bienvenida (welcome_expert.html)​

Cuándo se envía: Al registrarse y verificar el email como experto.

Contenido:

  • Mensaje de bienvenida al ecosistema de expertos
  • Qué pueden esperar de Floutic
  • Próximos pasos:
    1. Completar perfil de experto
    2. Pasar verificación oficial (IDV, portfolio, certificaciones, entrevista técnica)
  • Soporte y acompañamiento
  • Contacto: soporte_expertos@floutic.com

Variables:

  • {{ username }} - Nombre del experto
  • {{ expert_profile_url }} - URL del perfil de experto

2. Match Confirmado (match_confirmed_expert.html)​

Cuándo se envía: Cuando se confirma un match con un cliente.

Contenido:

  • Información del cliente y proyecto
  • Razón del match (experiencia relevante)
  • Canal de comunicación compartido
  • Próximos pasos detallados:
    1. Revisar alcance y hitos del proyecto
    2. Presentarse en el canal y resolver dudas
    3. Confirmar el primer hito
    4. Contactar Floutic si algo no encaja
  • Buenas prácticas Floutic
  • Información sobre facturación por hitos
  • Contacto: soporte_expertos@floutic.com

Variables:

  • {{ expert_name }} - Nombre del experto
  • {{ client_name }} - Nombre del cliente
  • {{ client_sector }} - Sector del cliente (opcional)
  • {{ project_summary }} - Resumen del proyecto
  • {{ project_reference }} - Referencia Floutic
  • {{ match_reason }} - Razón del match
  • {{ chat_url }} - URL del canal de chat

🔄 Emails Comunes​

1. Verificación de Email (verify_email.html)​

Cuándo se envía: Al registrarse, antes de activar la cuenta.

Variables:

  • {{ username }} - Nombre del usuario
  • {{ verification_url }} - URL de verificación (expira en 48 horas)

Notas de seguridad:

  • El reenvío está limitado por tiempo (EMAIL_VERIFICATION_RESEND_LIMIT_MINUTES)
  • Se registra la IP de solicitud para auditoría (headers de proxy con fallback)

2. Recuperación de Contraseña (password_reset.html)​

Cuándo se envía: Cuando se solicita recuperación de contraseña.

Variables:

  • {{ username }} - Nombre del usuario
  • {{ reset_url }} - URL de recuperación
  • {{ expires_at }} - Fecha de expiración

3. Reseña Recibida (review_received.html)​

Cuándo se envía: Cuando alguien deja una reseña.

Variables:

  • {{ reviewed_name }} - Nombre del usuario reseñado
  • {{ reviewer_name }} - Nombre del revisor
  • {{ rating }} - Calificación (1-5 estrellas)
  • {{ project_title }} - Título del proyecto
  • {{ review_url }} - URL para ver la reseña

📧 Emails de Proyectos​

Para Empresas​

Nueva Aplicación (project_application.html)​

Cuándo se envía: Cuando un experto aplica a un proyecto.

Variables:

  • {{ company_name }} - Nombre de la empresa
  • {{ project_title }} - Título del proyecto
  • {{ expert_name }} - Nombre del experto
  • {{ project_url }} - URL del proyecto

Proyecto Aprobado/Rechazado (project_approved.html, project_rejected.html)​

Cuándo se envía: Cuando un administrador aprueba o rechaza un proyecto.

Variables:

  • {{ company_name }} - Nombre de la empresa
  • {{ project_title }} - Título del proyecto
  • {{ status }} - Estado del proyecto
  • {{ reason }} - Razón (opcional)
  • {{ project_url }} - URL del proyecto

Para Expertos​

Experto Seleccionado (expert_selected.html)​

Cuándo se envía: Cuando una empresa selecciona a un experto.

Variables:

  • {{ expert_name }} - Nombre del experto
  • {{ project_title }} - Título del proyecto
  • {{ company_name }} - Nombre de la empresa
  • {{ project_url }} - URL del proyecto

Invitación a Proyecto (expert_invited.html)​

Cuándo se envía: Cuando un administrador invita a un experto a un proyecto.

Variables:

  • {{ expert_name }} - Nombre del experto
  • {{ project_title }} - Título del proyecto
  • {{ project_budget }} - Presupuesto del proyecto
  • {{ project_deadline }} - Fecha límite (opcional)
  • {{ project_url }} - URL del proyecto

📧 Emails de Hitos​

Para Empresas​

Hito Completado (milestone_completed.html)​

Cuándo se envía: Cuando un experto completa un hito.

Variables:

  • {{ company_name }} - Nombre de la empresa
  • {{ milestone_title }} - Título del hito
  • {{ expert_name }} - Nombre del experto
  • {{ project_title }} - Título del proyecto
  • {{ milestone_url }} - URL del hito

Para Expertos​

Hito Aprobado (milestone_approved.html)​

Cuándo se envía: Cuando una empresa aprueba un hito.

Variables:

  • {{ expert_name }} - Nombre del experto
  • {{ milestone_title }} - Título del hito
  • {{ project_title }} - Título del proyecto
  • {{ project_url }} - URL del proyecto

Hito Rechazado (milestone_rejected.html)​

Cuándo se envía: Cuando una empresa rechaza un hito y solicita revisión.

Variables:

  • {{ expert_name }} - Nombre del experto
  • {{ milestone_title }} - Título del hito
  • {{ project_title }} - Título del proyecto
  • {{ rejection_reason }} - Razón del rechazo (opcional)
  • {{ project_url }} - URL del proyecto

💰 Emails de Pagos​

Para Expertos​

Pago Liberado (payment_released.html)​

Cuándo se envía: Cuando se libera un pago al experto.

Variables:

  • {{ expert_name }} - Nombre del experto
  • {{ amount }} - Cantidad del pago
  • {{ amount_formatted }} - Cantidad formateada
  • {{ project_title }} - Título del proyecto
  • {{ milestone_title }} - Título del hito (opcional)
  • {{ project_url }} - URL del proyecto

Pago Recibido (payment_received.html)​

Cuándo se envía: Cuando un experto recibe un pago.

Variables:

  • {{ expert_name }} - Nombre del experto
  • {{ amount }} - Cantidad del pago
  • {{ project_title }} - Título del proyecto
  • {{ payment_url }} - URL del pago

🔔 Otros Emails​

Mensaje Recibido (message_received.html)​

Cuándo se envía: Cuando llega un nuevo mensaje en el chat del proyecto.

Variables:

  • {{ recipient_name }} - Nombre del destinatario
  • {{ sender_name }} - Nombre del remitente
  • {{ project_title }} - Título del proyecto
  • {{ preview }} - Vista previa del mensaje (opcional)
  • {{ project_url }} - URL del proyecto

Disputa (dispute_notification.html)​

Cuándo se envía: Cuando se crea o resuelve una disputa.

Variables:

  • {{ recipient_name }} - Nombre del destinatario
  • {{ project_title }} - Título del proyecto
  • {{ message }} - Mensaje de la disputa
  • {{ project_url }} - URL del proyecto

🔧 Configuración​

Variables de Entorno​

# SMTP Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
EMAIL_FROM_NAME=Floutic
EMAIL_FROM_ADDRESS=noreply@floutic.com

# Frontend URLs (para enlaces en emails)
FRONTEND_URL=https://app.floutic.com

# URLs de calendarios (opcionales)
COMPANY_KICKOFF_CALENDAR_URL=https://calendly.com/floutic/discovery
EXPERT_ONBOARDING_CALENDAR_URL=https://calendly.com/floutic/onboarding

Estructura de Templates​

Todos los templates extienden de email_base.html que proporciona:

  • Estructura HTML base
  • Header con logo y tagline
  • Footer con copyright
  • Bloques personalizables:
    • {% block page_title %} - Título de la página
    • {% block content %} - Contenido principal
    • {% block contact_block %} - Bloque de contacto
    • {% block signature_block %} - Firma personalizada

📝 Ejemplo de Uso​

from app.services.email_service import email_service

# Enviar email de bienvenida
await email_service.send_welcome_email(
    user_email="empresa@example.com",
    username="Empresa Test",
    role="empresa"
)

# Enviar email de solicitud de reseña
await email_service.send_review_request_email(
    company_email="empresa@example.com",
    company_name="Empresa Test",
    project_title="Proyecto Automatización",
    project_reference="#123 - Proyecto Automatización",
    project_id=123,
    expert_id=456
)

🧪 Testing​

Todos los emails tienen tests unitarios en tests/unit/test_services.py que verifican:

  • Renderizado correcto de templates
  • Envío con parámetros correctos
  • Generación automática de enlaces
  • Contenido HTML y texto plano

📊 Métricas​

Los emails se envían de forma asíncrona y los errores se registran en los logs. Para monitoreo:

  • Revisar logs del backend para errores de envío
  • Verificar configuración SMTP si hay problemas de entrega
  • Los emails fallidos no bloquean el flujo principal (se registran como warnings)

🔗 Enlaces de Contacto​

  • Empresas: soporte_empresas@floutic.com
  • Expertos: soporte_expertos@floutic.com
  • General: hola@floutic.com (en algunos emails legacy)