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#

Entrante: sondeo IMAP#

Un worker en segundo plano se conecta al servidor IMAP de cada canal EMAIL activo (TLS) y, en cada ciclo:

1. Obtiene el correo que aún no ha procesado, leído o no leído, de las últimas 24 horas (el periodo de búsqueda del canal, ver más abajo).
2. Descarga el texto, el HTML y los adjuntos hasta los límites de tamaño (no el mensaje completo; ver Adjuntos más abajo) y los analiza.
3. Elimina duplicados por message-id + vista previa (para que el mismo correo no se ingiera dos veces).
4. Crea una conversación asociada a la dirección de correo del remitente (o, para un correo de formulario de contacto enviado desde tu propia dirección, al cliente que menciona; ver más abajo).
5. Sube los adjuntos al almacenamiento.
6. Marca el correo como procesado.

Cómo se registra lo "procesado"

El sondeador marca cada correo ingerido con una palabra clave IMAP personalizada $HelpStackProcessed y busca el correo que no la tiene. La ingesta nunca toca el indicador \Seen (leído), así que:

• el correo sigue sin leer en Outlook, Gmail o Apple Mail hasta que alguien lo lee allí (o en HelpStack, con la sincronización de lectura activada), y
• un correo que alguien abre en su cliente antes de la siguiente comprobación de HelpStack se recoge igualmente.

Gmail, Google Workspace, Microsoft 365 y la mayoría de los servidores IMAP actuales admiten palabras clave personalizadas. Si un servidor no las admite, el sondeador recurre al indicador \Seen: solo recoge el correo no leído y lo marca como leído una vez ingerido.

En un servidor sin soporte de palabras clave, usa un buzón dedicado para el canal. HelpStack depende entonces de \Seen para no volver a ingerir correo, de modo que una persona que lea el buzón puede provocar correos perdidos, y la sincronización de lectura no está disponible.

Periodo de búsqueda

Cada comprobación busca en las últimas 24 horas por defecto. Un administrador puede cambiarlo por canal (de 1 a 168 horas) en Sincronización del buzón, dentro de la configuración de conexión del canal. El periodo nunca va más atrás del momento en que se conectó el buzón, así que conectar un buzón no importa su historial. Import Recent Mail retrasa ese punto de inicio y suspende el periodo de búsqueda durante una hora para que la importación pueda terminar. Si HelpStack no pudo comprobar el buzón durante más tiempo que el periodo de búsqueda (una caída), la siguiente comprobación llega hasta un día antes de la última comprobación correcta, con un máximo de 7 días, para que no se pierda el correo de ese intervalo.

El correo que HelpStack ya ha ingerido nunca se ingiere dos veces: la comprobación por message-id lo omite, incluso cuando un buzón pasa del recurso a \Seen al seguimiento por palabra clave. Cuando un canal existente hace ese cambio, el correo que ya estaba leído en el buzón antes del cambio no se importa (probablemente tu equipo ya lo atendió allí); el correo no leído se importa como siempre.

Sincronización de leído y no leído

Desactivada por defecto. Cuando un administrador activa Sincronizar leído y no leído (Sincronización del buzón, por canal):

• De HelpStack al buzón: al leer una conversación en HelpStack, sus correos se marcan como leídos en el buzón; Marcar como no leída los vuelve a marcar como no leídos. Esto se ejecuta en segundo plano unos segundos después.
• Del buzón a HelpStack: HelpStack sigue los cambios hechos en el buzón. Cuando alguien lee allí un correo y todos los correos de la conversación del último periodo de búsqueda quedan leídos, la conversación se marca como leída en HelpStack. Si alguien marca uno de esos correos como no leído en el buzón, la conversación se marca como no leída. Sin un cambio en el buzón no cambia nada, así que una conversación que marcaste como no leída en HelpStack sigue sin leer, y un correo no leído recién llegado no cambia nada por sí solo.

Solo se siguen los correos que HelpStack ingirió con el seguimiento por palabra clave activo. La sincronización de lectura no está disponible en servidores sin soporte de palabras clave.

Seguir el buzón (respuestas enviadas desde tu programa de correo)

Para equipos que, además de HelpStack, también trabajan en Outlook, Gmail u otro programa de correo. Desactivado por defecto; un administrador activa Seguir lo que pasa en el buzón (Sincronización del buzón, por canal). A partir de ahí, HelpStack comprueba cada pocos minutos:

• Las respuestas enviadas desde tu programa de correo. HelpStack busca correo nuevo en la carpeta de enviados del buzón (la encuentra por su marca estándar, se llame como se llame, por ejemplo "Elementos enviados" o "[Gmail]/Enviados"). Una respuesta a un correo de una conversación aparece en esa conversación, marcada como Enviado desde el correo, sin los mensajes anteriores citados. Los adjuntos de esa respuesta no se descargan. Si la respuesta es más reciente que el último mensaje del cliente, la conversación se marca como leída y el borrador de IA pendiente se aparta, marcado como Borrador no enviado, para que nadie responda dos veces. Un borrador apartado no cuenta como rechazado en el rendimiento de la IA.
• Los correos movidos fuera de la bandeja de entrada. Cuando todos los correos de una conversación se han movido fuera de la bandeja de entrada (a una carpeta, al archivo o a la papelera), la conversación se marca como leída. Archivar así un correo también cuenta como atenderlo: un borrador de IA pendiente se aparta (muestra Borrador no enviado) y la conversación sale de Recibidos en la vista de buzón, hasta que el cliente vuelva a escribir.

Para esto el buzón solo se lee: HelpStack nunca marca, mueve ni borra nada en él por esta opción. (Escribir el estado de leído y no leído de vuelta es la opción aparte Sincronizar leído y no leído de arriba.) Sigue las conversaciones activas en los últimos 30 días.

Al activarla se inicia una sincronización única de esos 30 días, para que las conversaciones ya respondidas o archivadas dejen de aparecer como no leídas. Puedes repetirla con Sincronizar ahora; la línea junto al botón muestra el resultado de la última. La lectura del correo nuevo nunca se retrasa por ello y, como cualquier otra comprobación del buzón, se pausa mientras Gmail limita el buzón.

Mover un correo a una carpeta

En los canales de correo que leen su buzón por IMAP (también Gmail), un agente puede mover el correo del cliente desde HelpStack fuera de la bandeja de entrada a una carpeta del buzón: Mover a carpeta en el menú ⋮ de una conversación, o en la barra de selección de la vista de buzón para varias conversaciones de un mismo canal a la vez (hasta 100). El selector muestra las carpetas propias del buzón (nunca la bandeja de entrada), con la última carpeta usada en ese canal arriba y ya elegida, y un buscador para listas largas. Solo ocurre cuando alguien hace clic; nada se mueve automáticamente.

El correo se mueve, nunca se borra, y también lo ves en la nueva carpeta en Outlook o Gmail. Después la conversación cuenta como archivada: se marca como leída, un borrador de IA pendiente se aparta (Borrador no enviado), sale de Recibidos en la vista de buzón y muestra Gestionado en el correo, hasta que el cliente vuelva a escribir. Una conversación cuyo correo ya no está en la bandeja de entrada (movido antes, o correo antiguo) se indica como omitida. Cuando el servidor de correo limita el buzón o no responde, HelpStack lo dice y no cambia nada.

Gestionado en el correo aparece en cada conversación abierta que, después del último mensaje del cliente, se respondió desde tu programa de correo o se archivó fuera de la bandeja de entrada: en la lista de conversaciones, en la vista de buzón y en la cabecera de la conversación. Pasa el ratón por encima para ver qué y cuándo. La conversación sigue abierta; la etiqueta desaparece sola cuando el cliente vuelve a escribir.

Adjuntos: límites de tamaño, almacenamiento y obtención desde el buzón

HelpStack descarga de cada correo solo lo que necesita: el texto, el HTML y los adjuntos de hasta 10 MB cada uno y 25 MB por correo. Un adjunto más grande sigue apareciendo en la conversación, con su nombre, su tamaño y un botón Obtener del buzón; al pulsarlo se descarga ese archivo desde tu buzón y después se muestra como siempre.

Los archivos adjuntos se guardan en el almacenamiento de HelpStack durante 60 días. Después, el archivo se elimina del almacenamiento de HelpStack, el adjunto sigue en la lista y Obtener del buzón lo recupera de tu buzón (una copia obtenida se guarda 7 días más). Si mientras tanto el correo se ha eliminado del buzón, el adjunto muestra Ya no está disponible en el buzón. Un correo que archivaste en Gmail se sigue encontrando. Si HelpStack no puede acceder al buzón en ese momento (por ejemplo, tras un cambio de contraseña), verás un aviso y podrás intentarlo más tarde; el adjunto no se marca como no disponible.

Cuando Gmail limita el buzón

Gmail limita cuánto puede descargar un buzón por IMAP cada día. Cuando indica que un buzón ha superado ese límite, HelpStack pausa la consulta de ese buzón (30 minutos al principio, más si vuelve a ocurrir, como máximo 6 horas) en lugar de reintentar cada minuto, lo que mantendría el bloqueo. La pestaña Conexión del canal muestra entonces Gmail ha limitado temporalmente este buzón; se reintentará a las HH:MM. No se pierde ningún correo: cuando se reanuda la consulta, HelpStack recoge todo lo que llegó durante la pausa. Hasta entonces tampoco se pueden obtener adjuntos de ese buzón. Otros proveedores de correo que indiquen el mismo tipo de límite se tratan igual.

Formularios de contacto enviados desde tu propia dirección

Los formularios de contacto de los sitios web suelen enviar su correo desde la dirección de tu propio buzón y ponen al visitante en Reply-To o en el cuerpo del mensaje. Cuando la dirección From de un correo entrante es la propia dirección del canal, HelpStack lo trata como reenviado y usa, por orden:

1. la primera dirección de Reply-To que no sea la tuya, o
2. una línea Email: en el cuerpo del mensaje.

La conversación, y cada respuesta, van entonces a ese cliente. Su nombre sale de una línea Name: (o Ime in priimek:) en el cuerpo, si no del nombre visible de Reply-To, y si no de la dirección. Si no se encuentra nada, el correo se ingiere como antes.

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:

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#

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:

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.

Relacionado#

• Referencia de la API
• Webhooks
• Guía de canales
• Glosario