Integraciones
Canal de email
Conecte un buzón de correo como canal de HelpStack: el correo entrante se sondea mediante IMAP y las respuestas se envían mediante SMTP.
Datos rápidos#
| Tipo de canal | EMAIL |
| Entrante | Worker de sondeo IMAP (npm run email:poll) |
| Saliente | SMTP mediante nodemailer (credenciales del canal) |
| Credenciales | Almacenadas cifradas (AES-256-GCM) por canal |
| Seguridad del transporte | IMAP sobre TLS |
| Intervalo de sondeo | ~10s (desarrollo) / ~60s (producción) |
Entrante: sondeo IMAP#
Un worker en segundo plano se conecta al servidor IMAP de cada canal EMAIL activo (TLS) y, en cada ciclo:
- Obtiene el correo reciente no procesado.
- Parsea texto, HTML y adjuntos.
- Deduplica por message-id + preview (para que el mismo correo no se ingiera dos veces).
- Crea una conversación identificada por la dirección de email del remitente.
- Sube los adjuntos al almacenamiento.
- Marca el correo como procesado.
Cómo se rastrea el estado "procesado"
El poller prefiere una palabra clave IMAP personalizada $HelpStackProcessed, que deja el indicador \Seen intacto (de modo que el mensaje sigue pareciendo no leído en otros clientes). Si el servidor no admite palabras clave personalizadas, recurre al indicador \Seen.
Recomendación: use un buzón dedicado para el canal. Si el servidor no admite palabras clave personalizadas, HelpStack depende de
\Seenpara evitar reingerir correo — compartir el buzón con un lector humano (que marca cosas como leídas/no leídas) puede causar ingestión omitida o duplicada.
Hilos de conversación
La información de hilos se almacena en los metadatos de la conversación para que las respuestas se encadenen correctamente:
| Campo de metadatos | Origen |
|---|---|
emailSubject | Asunto del correo entrante |
emailMessageId | Cabecera Message-ID |
emailReferences | Cadena References / In-Reply-To |
Ejecutar el poller
npm run email:poll
Ejecute este worker junto con la aplicación (y el worker de la cola de mensajes) para que el email entrante sea ingerido. En producción sondea aproximadamente cada 60s; en desarrollo aproximadamente cada 10s.
Variables de entorno ajustables#
| Variable | Por defecto | Propósito |
|---|---|---|
EMAIL_MAX_BODY_BYTES | ~100 KB | Tamaño máximo del cuerpo ingerido; los cuerpos más largos se truncan |
EMAIL_MIN_ATTACHMENT_BYTES | ~1 KB | Los adjuntos menores a esto se omiten (filtra píxeles de seguimiento) |
EMAIL_MAX_AGE_DAYS | 5 | Ignorar correo más antiguo que este número de días |
IMAP_ALLOW_SELF_SIGNED | — | Solo desarrollo — aceptar certificados TLS IMAP autofirmados |
Cifrado#
Las credenciales IMAP/SMTP de cada canal se almacenan cifradas con AES-256-GCM. El panel de control proporciona un botón Test que valida las credenciales configuradas (se conecta y autentifica) antes de que las guarde/utilice.
Campos de credenciales verificados para un canal de email (credentials):
host, port, username, password, from,
secure?, imapHost?, imapPort?, imapSecure?, imapAllowSelfSigned?
Saliente: SMTP mediante nodemailer#
Las respuestas se envían mediante SMTP usando nodemailer con las propias credenciales SMTP del canal: host, port, secure, user, pass y from. El envío saliente lo gestionan los senders de la cola de mensajes.
SMTP del canal vs. SMTP de notificaciones del sistema
Estas son dos rutas de correo separadas — no las confunda:
| SMTP del canal | SMTP de notificaciones del sistema | |
|---|---|---|
| Propósito | Respuestas a clientes en un canal EMAIL | Emails de notificación de la plataforma/sistema |
| Credenciales | Por canal, cifradas | Variables de entorno |
| Configurado mediante | Configuración del canal | SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_SECURE, SMTP_FROM |
| Remitente por defecto | El from del canal | noreply@helpstack.eu |
Los emails de notificación del sistema (p. ej. mensajes de cuenta/sistema) siempre usan el SMTP configurado mediante variables de entorno y el remitente por defecto noreply@helpstack.eu, independientemente de cualquier canal.