Sistema de envíos y workflows de Growork
Es el sistema operativo interno que reduce el riesgo de Growork: sincroniza clientes desde el CRM, controla el onboarding con n8n, valida documentos en Drive, crea cuentas de Google Workspace, regula los envíos con warmup, deja trazabilidad de cada email y convierte las respuestas en trabajo accionable.
8
áreas operativas de la web interna
5
workflows secuenciales por cliente
16
módulos backend conectados
24/7
crons, worker, syncs y monitorización
El reto
No era enviar emails. Era reducir el riesgo de toda una operación.
Un cliente de Growork no necesita solo que se envíe un correo. Antes tiene que existir en el CRM, tener su plan activo, avanzar por un onboarding, tener los documentos ordenados, contar con un CV final, recibir una cuenta corporativa y entrar en una cadencia de envíos que no dañe la reputación del dominio.
Por eso construí una web interna que no es un dashboard decorativo: es una consola de operaciones. Cada botón toca un proceso real, cada estado tiene consecuencias y cada envío deja la trazabilidad suficiente para responder, auditar y mejorar.
Antes / después
De tareas dispersas a control operativo
El cambio importante no fue automatizar por automatizar. Fue convertir acciones frágiles en un sistema con reglas, estados y puntos de control visibles.
01
Antes
Los estados de cada cliente vivían repartidos entre CRM, Drive, Gmail, hojas de cálculo, n8n y la memoria del equipo.
Después
La web interna convierte esos estados en una única consola: listo, bloqueado, pendiente de revisión, enviado, respondido o en riesgo.
02
Antes
Un error pequeño podía duplicar contactos, enviar desde la cuenta equivocada o usar un CV no definitivo.
Después
Cada envío pasa por validaciones de plan, cuenta corporativa, carpeta DEFINITIVA, historial de ofertas y reputación.
03
Antes
La supervisión dependía de revisar herramientas externas y reconstruir qué había pasado cliente por cliente.
Después
Jobs, emails, respuestas, workflows y notificaciones quedan trazados para auditar la operación sin salir del sistema.
Mapa de la web
Qué hace cada apartado
La interfaz está dividida por responsabilidades. Así se puede operar el negocio sin entrar a la base de datos, a n8n, a Google Admin o a los logs del servidor para cada decisión diaria.
MÓDULO 01
Dashboard
Qué resuelve
Vista ejecutiva con KPIs de clientes, distribución por estado, estadísticas de envío y actividad reciente. Sirve para saber si la operación está sana sin abrir cada módulo.
Conexión real
Lee agregados del backend sobre clients, email_sends y notifications. Se refresca en intervalos distintos según el peso de cada consulta.
MÓDULO 02
Clientes
Qué resuelve
Centro de control por cliente: estado CRM, plan, pareja, envío activo, modo preview, warmup, criterios de matching, estadísticas y respuestas.
Conexión real
Sincroniza con Twenty CRM, guarda client_send_settings en PostgreSQL y propaga los ajustes a la pareja cuando existe.
MÓDULO 03
Pipeline de workflows
Qué resuelve
Kanban operativo para ver en qué punto está cada cliente: carpetas, creador de CV, nuevo archivo, aprobación de CV y correo corporativo.
Conexión real
Cada columna se alimenta de client_workflow_states y se actualiza con los webhooks de n8n. Los pasos manuales disparan workflows desde la propia interfaz.
MÓDULO 04
Creadores de CV
Qué resuelve
Gestión de los profesionales que preparan los CV: idiomas, estado, asignación y visibilidad del trabajo activo.
Conexión real
Se vincula con los clientes y con el workflow WKF-1.1 para compartir carpetas de Drive y registrar el creador asignado.
MÓDULO 05
Dominios
Qué resuelve
Administración de los dominios de envío: activo/inactivo, prioridad, usuarios actuales y capacidad máxima.
Conexión real
n8n consulta estos datos antes de crear cuentas en Google Workspace, y el backend los usa para validar los emails corporativos gestionados.
MÓDULO 06
Correos corporativos
Qué resuelve
Inventario de las cuentas creadas para clientes: estado de gracia, borrado manual, sincronización con Google Workspace y limpieza de inconsistencias.
Conexión real
Habla con la Admin Directory API de Google, y se apoya en clients.emailOperativo, dominios y notificaciones de borrado.
MÓDULO 07
Preview de emails
Qué resuelve
Bandeja de aprobación donde los emails generados por IA se pueden revisar, editar, regenerar, rechazar o aprobar antes del envío.
Conexión real
Consume los email_sends en estado pending_review y, al aprobar, llama al EmailService para enviar con la Gmail API.
MÓDULO 08
Centro de envíos
Qué resuelve
Módulo unificado con tres pestañas: monitor diario de jobs, historial de enviados y gestión de respuestas.
Conexión real
Une scheduler, worker, sent-emails, email-responses, clasificación con IA y threading de Gmail en una sola pantalla operativa.
Conexiones
Cómo se conectan todas las piezas
La arquitectura separa producto, automatización, datos y servicios externos. La web no hace trabajo sensible directamente: habla con el backend, y el backend decide qué sistema debe intervenir.
01
CRM
→02
Backend
→03
n8n
→04
Drive
→05
Workspace
→06
Scheduler
→07
Worker
→08
Gmail
→09
Respuestas
Capa de producto
Next.js organiza la operación en pantallas: clientes, workflows, preview, envíos, respuestas, dominios y correos corporativos. El usuario ve procesos humanos, no endpoints.
Capa de negocio
NestJS concentra los módulos de clients, scheduler, worker, email, responses, n8n, workflow-state, corporate-emails, dominios, dashboard, Drive, Twenty y finance.
Capa de datos
PostgreSQL guarda la verdad operacional: cliente, estado, plan, settings, jobs, emails, respuestas, workflows, dominios, reputación y notificaciones.
Automatización visual
n8n ejecuta procesos que no deberían vivir en la UI: crear carpetas, compartir Drive, detectar archivos, mover CV y crear cuentas de Workspace.
Google Workspace
Google Admin crea las cuentas corporativas; la Gmail API envía y responde; Drive almacena los CV y cartas finales que se adjuntan a cada candidatura.
IA aplicada
OpenAI genera emails, resume CV, redacta cartas de presentación, clasifica respuestas y propone réplicas, siempre con fallback para que el proceso no se detenga.
Workflows
El onboarding visual de cada cliente
Cada cliente avanza por una secuencia de workflows. La UI muestra el primer paso pendiente, permite ejecutar los manuales y registra los automáticos cuando n8n devuelve el webhook.
WKF-1
Automático
Crear estructura en Drive
Ver workflowCuando entra un cliente desde Twenty, n8n crea la carpeta principal y las subcarpetas CV, OLD, NEW y DEFINITIVA. Devuelve los identificadores al backend para que el resto del sistema sepa dónde leer y escribir.
WKF-1.1
Manual
Asignar creador de CV
Ver workflowDesde el Kanban se dispara el workflow que comparte las carpetas con el creador correcto según el idioma. El backend registra el creador y mueve al cliente al siguiente paso.
WKF-1.2
Automático
Detectar nuevo CV
Ver workflown8n revisa la carpeta NEW y avisa cuando aparece un archivo nuevo. El cliente se coloca en la columna de aprobación, con la metadata del archivo recibido.
WKF-1.3
Manual
Mover a DEFINITIVA
Ver workflowEl operador selecciona el CV correcto desde la interfaz. n8n lo mueve a la carpeta definitiva, retira los accesos temporales y el backend marca el CV como finalizado.
WKF-1.4
Automático
Crear email corporativo
Ver workflowTras aprobar el CV, se crea la cuenta de Google Workspace, se guardan email y contraseña, se sincroniza con Twenty y, si hay pareja, se reutiliza o propaga la misma cuenta.
Envíos
Cómo se gestiona el envío de emails por cliente
El sistema cuida el volumen, la calidad, el origen del envío, los adjuntos, la trazabilidad y las respuestas. Es un flujo diseñado para operar muchos clientes sin perder el control.
Cliente activo y con plan
Solo los clientes en estado In Progress, con envío activo y plan vigente, entran en el circuito. El worker vuelve a validar el plan justo antes de enviar (fail-closed).
Scheduler diario
A las 6:00 (zona Atlantic/Canary) crea un SendJob por cliente activo. En parejas solo procesa al primario y exige que ambos estén activos para evitar duplicados.
Warmup
El límite diario sube de forma gradual con currentDailyLimit, targetDailyLimit y warmupDailyIncrement, solo si el job del día anterior se completó. La reputación se protege antes de escalar volumen.
Matching de ofertas
El worker busca ofertas recientes por país, ciudad y puesto (modo AND/OR). Excluye las ofertas ya contactadas por el cliente o su pareja y los emails con mala reputación.
IA y documentos
OpenAI genera el email, resume el CV y puede preparar la carta de presentación. Drive aporta los PDF de la carpeta DEFINITIVA, con caché para no descargar lo mismo en cada tick.
Preview o envío directo
Por defecto el email queda en pending_review. Si el modo automático está activado, la Gmail API lo envía directamente desde el email corporativo del cliente.
Trazabilidad
Se guardan messageId, gmailThreadId, asunto, contenido, adjuntos, modelo de IA, estado y fecha. Esto permite auditoría, respuestas en hilo y estadísticas reales.
Respuestas
El sistema lee Gmail, guarda las respuestas, las clasifica con IA y permite contestar manteniendo In-Reply-To, References y el threadId.
Modelo de datos
PostgreSQL conserva el estado, las decisiones y la reputación
La base de datos no solo almacena clientes: también guarda configuración, jobs, envíos, respuestas, estados de workflow, dominios, reputación y la auditoría de cada llamada a la IA.
clientCliente sincronizado desde Twenty CRM: estado operativo, vínculo de pareja, plan y email corporativo asignado.
client_send_settingsConfiguración de envío 1:1 por cliente: activación, parámetros de warmup, modo preview y criterios de matching en JSONB.
send_jobTrabajo diario por cliente generado por el scheduler; el worker lo consume respetando la ventana horaria.
email_sendCada email reservado o enviado a una oferta. Sus constraints únicos impiden contactar dos veces la misma oferta o destinatario.
email_responseRespuesta recibida, con los datos de threading RFC 5322 y la clasificación de la IA con su nivel de confianza.
client_workflow_stateEstado PENDING/OK/ERROR de cada workflow (WKF_1 … WKF_1_4) por cliente; es lo que alimenta el Kanban.
dominioDominio de envío con prioridad y capacidad. n8n elige uno por sorteo ponderado antes de crear una cuenta corporativa.
ai_usage_log · email_reputationAuditoría de cada llamada a OpenAI (operación, modelo, tokens y coste) y lista de rebotes/inválidos para excluir destinatarios con mala reputación.
Google Workspace
Cuentas corporativas, dominios y reputación
La cuenta de correo no se crea como un dato suelto. Forma parte de un ciclo de vida: asignación, uso, seguimiento, periodo de gracia y limpieza.
Creación
- →n8n genera un alias normalizado y una contraseña aleatoria.
- →Consulta los dominios activos y su capacidad disponible.
- →Crea el usuario mediante la Admin Directory API de Google Workspace.
- →Actualiza Twenty CRM y PostgreSQL con email, contraseña y fecha.
- →Si es pareja, hereda o propaga la misma cuenta para no duplicar la identidad.
Mantenimiento
- →La página de correos corporativos lista las cuentas activas, las pendientes de borrado y el uso por dominio.
- →Un cron horario marca cuentas por cierre, inactividad o exceso de rebotes.
- →Hay 48 horas de gracia antes del borrado automático.
- →El operador puede cancelar la eliminación o borrar manualmente.
- →La sincronización con Workspace limpia emails que no existen o no pertenecen a dominios gestionados.
Configuración
Control fino de los envíos
El sistema no envía a ciegas. Cada cliente tiene su propia configuración y, además, existe una configuración global para regular horarios y delays.
Por cliente
- →active: pausa o activa el envío del cliente.
- →previewEnabled: decide si todo pasa por aprobación manual.
- →currentDailyLimit: volumen real del día.
- →targetDailyLimit: objetivo final del warmup.
- →warmupDailyIncrement: subida diaria controlada.
- →matchingCriteria: países, ciudades, puesto, modo AND/OR y filtros activos.
Global
- →startHour y endHour definen la ventana de envío.
- →minDelayMinutes y maxDelayMinutes generan pausas aleatorias.
- →enabled permite desactivar restricciones en situaciones controladas.
- →El worker interpreta la ventana en la zona Atlantic/Canary.
- →El monitor permite ver jobs done, failed, running, queued o sin job.
Respuestas
El envío no termina cuando sale el email
La parte más valiosa está después: leer las respuestas, entenderlas y poder contestar bien sin romper el hilo.
Lectura de Gmail
El sistema busca las réplicas por remitente, excluye los mensajes propios, deduplica por gmailMessageId y conserva el threadId.
Clasificación con IA
Cada respuesta se clasifica como negativa, automática, entrevista, más información, contratado o sin clasificar, con confianza y razonamiento.
Respuesta en hilo
La respuesta se envía con los headers In-Reply-To y References, además del threadId de Gmail, para mantener la conversación ordenada.
Riesgos
Qué podía salir mal y cómo lo controlé
El valor de esta pieza está en prevenir fallos operativos caros: reputación de dominio, duplicados, documentos incorrectos y pérdida de contexto.
Riesgo
Quemar dominios por volumen o cadencia incorrecta
Control
Warmup progresivo, límites diarios por cliente, ventana global de envío, delays aleatorios y capacidad por dominio antes de crear cuentas nuevas.
Riesgo
Duplicar candidaturas o contactar dos veces a la misma empresa
Control
Constraints únicos y filtros cruzados sobre cliente, pareja, oferta, destinatario y estado previo de email_sends.
Riesgo
Enviar documentos equivocados o incompletos
Control
El worker solo toma PDF de la carpeta DEFINITIVA y conserva la metadata del archivo usado en cada envío.
Riesgo
Perder el contexto cuando llega una respuesta
Control
Se guardan gmailThreadId, messageId, headers y clasificación de IA para contestar dentro del hilo correcto.
Seguridad y robustez
Decisiones que evitan daños reales
Cuando un sistema envía emails desde cuentas de clientes, una equivocación no es estética: puede quemar dominios, duplicar contactos o mezclar datos sensibles.
API key global en los endpoints internos y rate limiting con Throttler (100 peticiones / 60 s).
Domain-Wide Delegation para impersonar las cuentas de cliente sin guardar sesiones de Gmail.
Validación de los dominios gestionados para no tratar emails personales como corporativos.
Constraints únicos para no enviar dos veces la misma oferta ni el mismo destinatario a un cliente.
Webhooks de n8n mapeados por workflowId y, como fallback, por tipo de evento.
Los clientes en estado Closed quedan fuera del scheduler, el worker, el Kanban y los webhooks operativos.
Periodo de gracia de 48 horas antes de borrar cuentas corporativas de forma automática.
Fallbacks: si falla la IA se usa una plantilla; si falla Drive, el sistema puede seguir sin adjuntos.
Lo que demuestra
Este proyecto cuenta mucho más que una lista de tecnologías
Aquí hay producto, backend, frontend, automatización, datos, integraciones, IA, operaciones y criterio. El valor no está en haber conectado Gmail o n8n, sino en haber diseñado un sistema donde cada cliente tiene un camino claro, cada correo tiene trazabilidad y cada parte del negocio puede operar sin depender de tareas manuales repetitivas.
Este sistema convierte una operación compleja en una consola accionable: sabes quién está listo, quién está bloqueado, qué se ha enviado, quién ha respondido, qué cuenta está en riesgo y qué workflow necesita atención.
Aprendizaje
Lo que me dejó construir un sistema interno de verdad
La mayor complejidad no estuvo en una API concreta, sino en hacer que todos los estados fueran recuperables, visibles y suficientemente seguros para operar a diario.
La automatización valiosa no es la que elimina personas, sino la que les muestra dónde intervenir antes de que haya daño.
Un sistema de emails se parece más a una infraestructura de riesgo que a una campaña de marketing: mandan la reputación, la identidad y la trazabilidad.
Separar UI, backend y n8n evita que la interfaz cargue con trabajo sensible y permite recuperar procesos fallidos con estados claros.
Las parejas, los planes y los estados cerrados obligan a diseñar reglas de negocio explícitas, no simples filtros visuales.