Correo electrónico

Dos canales de correo electrónico dependiendo de cómo quieras que se entreguen los mensajes entrantes.

Quién puede hablar con el agente

Los remitentes entrantes se filtran contra el conjunto de pares resuelto para el agente vinculado, obtenido de la configuración peer_groups a la que pertenece el agente. La coincidencia elimina el @ inicial y no distingue mayúsculas de minúsculas frente al identificador nativo de remitente del canal. Un conjunto vacío deniega a todos; un conjunto que contiene "*" acepta a cualquiera; en caso contrario, solo se aceptan los pares externos listados (y los agentes pares). Esto es independiente del emparejamiento de la puerta de enlace (gateway.require_pairing), que autentica clientes HTTP/WebSocket, no remitentes de canales de chat.

Un grupo de pares para email establece channel en email, lista los remitentes permitidos en external_peers (para email, la dirección de correo electrónico del remitente; ["*"] acepta a cualquiera), opcionalmente nombra agents pares para el despacho entre agentes, una lista de bloqueo ignore y un output_modality (mirror, voice o text). Consulta Peer Groups para la referencia de campos.

Dónde configurar esto:

IMAP + SMTP (email_channel)

El canal de correo electrónico de propósito general. Analiza IMAP en busca de nuevos mensajes y envía a través de SMTP. Funciona con Gmail, Outlook, Fastmail, Postfix autoalojado y cualquier otro servicio que utilice IMAP/SMTP.

zeroclaw config set channels.email.<alias>.default_subject <value>

export ZEROCLAW_channels__email__<alias>__default_subject=

zeroclaw config set channels.email.<alias>.excluded_tools <value>

export ZEROCLAW_channels__email__<alias>__excluded_tools=

zeroclaw config set channels.email.<alias>.from_address <value>

export ZEROCLAW_channels__email__<alias>__from_address=

zeroclaw config set channels.email.<alias>.html_body <value>

export ZEROCLAW_channels__email__<alias>__html_body=

zeroclaw config set channels.email.<alias>.idle_timeout_secs <value>

export ZEROCLAW_channels__email__<alias>__idle_timeout_secs=

zeroclaw config set channels.email.<alias>.imap_folder <value>

export ZEROCLAW_channels__email__<alias>__imap_folder=

zeroclaw config set channels.email.<alias>.imap_host <value>

export ZEROCLAW_channels__email__<alias>__imap_host=

zeroclaw config set channels.email.<alias>.imap_port <value>

export ZEROCLAW_channels__email__<alias>__imap_port=

zeroclaw config set channels.email.<alias>.max_attachment_bytes <value>

export ZEROCLAW_channels__email__<alias>__max_attachment_bytes=

zeroclaw config set channels.email.<alias>.oauth2 <value>

export ZEROCLAW_channels__email__<alias>__oauth2=

zeroclaw config set channels.email.<alias>.observer_mode <value>

export ZEROCLAW_channels__email__<alias>__observer_mode=

zeroclaw config set channels.email.<alias>.password <value>

export ZEROCLAW_channels__email__<alias>__password=

zeroclaw config set channels.email.<alias>.poll_interval_secs <value>

export ZEROCLAW_channels__email__<alias>__poll_interval_secs=

zeroclaw config set channels.email.<alias>.smtp_host <value>

export ZEROCLAW_channels__email__<alias>__smtp_host=

zeroclaw config set channels.email.<alias>.smtp_password <value>

export ZEROCLAW_channels__email__<alias>__smtp_password=

zeroclaw config set channels.email.<alias>.smtp_port <value>

export ZEROCLAW_channels__email__<alias>__smtp_port=

zeroclaw config set channels.email.<alias>.smtp_tls <value>

export ZEROCLAW_channels__email__<alias>__smtp_tls=

zeroclaw config set channels.email.<alias>.smtp_username <value>

export ZEROCLAW_channels__email__<alias>__smtp_username=

zeroclaw config set channels.email.<alias>.username <value>

export ZEROCLAW_channels__email__<alias>__username=

password (y smtp_password si usas un relay independiente) son secretos:

channels.email.<alias>.password es un secreto. Se almacena cifrado, nunca en texto plano en config.toml. Configúralo mediante una de estas opciones, que cifran al escribir:

zeroclaw config set channels.email.<alias>.password    # solicita entrada enmascarada, almacena cifrado

Trucos de Gmail

• Se requieren contraseñas de aplicación si la autenticación de dos factores (2FA) está activada. La contraseña regular de la cuenta será rechazada.
• “El acceso de aplicaciones menos seguras” ya no existe: la contraseña de aplicación es la única opción.
• Considera el canal de Gmail Push para la entrega en tiempo real en lugar de la consulta periódica.

Outlook / Office 365

password (y smtp_password) son secretos:

channels.email.<alias>.password es un secreto. Se almacena cifrado, nunca en texto plano en config.toml. Configúralo mediante una de estas opciones, que cifran al escribir:

zeroclaw config set channels.email.<alias>.password    # solicita entrada enmascarada, almacena cifrado

Gmail Push (gmail_push)

Entrega en tiempo real mediante Google Cloud Pub/Sub, sin sondeo.

zeroclaw config set channels.gmail_push.<alias>.excluded_tools <value>

export ZEROCLAW_channels__gmail_push__<alias>__excluded_tools=

zeroclaw config set channels.gmail_push.<alias>.label_filter <value>

export ZEROCLAW_channels__gmail_push__<alias>__label_filter=

zeroclaw config set channels.gmail_push.<alias>.oauth_token <value>

export ZEROCLAW_channels__gmail_push__<alias>__oauth_token=

zeroclaw config set channels.gmail_push.<alias>.topic <value>

export ZEROCLAW_channels__gmail_push__<alias>__topic=

zeroclaw config set channels.gmail_push.<alias>.webhook_secret <value>

export ZEROCLAW_channels__gmail_push__<alias>__webhook_secret=

zeroclaw config set channels.gmail_push.<alias>.webhook_url <value>

export ZEROCLAW_channels__gmail_push__<alias>__webhook_url=

oauth_token y webhook_secret son secretos:

channels.gmail_push.<alias>.oauth_token es un secreto. Se almacena cifrado, nunca en texto plano en config.toml. Configúralo mediante una de estas opciones, que cifran al escribir:

zeroclaw config set channels.gmail_push.<alias>.oauth_token    # solicita entrada enmascarada, almacena cifrado

Configuración

1. Crea un proyecto de Google Cloud, habilita la API de Gmail y la API de Pub/Sub
2. Crea un tema de Pub/Sub en el que el servicio de Gmail pueda publicar, configúralo como topic
3. Autorice el acceso del agente a Gmail y almacene el token resultante mediante la ruta del secreto indicada arriba
4. El agente supervisa las notificaciones de correo nuevo y las enruta al agente vinculado

Los envíos salientes siguen realizándose vía SMTP: configure un bloque IMAP+SMTP [channels.email.<alias>].

Hilo de respuestas

Ambos canales de correo electrónico agrupan las respuestas mediante los encabezados In-Reply-To y References, de modo que las conversaciones permanezcan agrupadas en el cliente que utilice el remitente.

Formato del cuerpo de salida

Las respuestas del agente se envían como multipart/alternative con una parte de texto plano y una parte HTML de forma predeterminada. La parte HTML es el cuerpo renderizado desde Markdown; la parte de texto plano es el texto sin procesar del cuerpo. Los clientes de correo que prefieren texto plano seleccionarán automáticamente la alternativa de texto plano.

Para enviar solo texto sin formato (sin parte HTML, para clientes o configuraciones que lo prefieran), establece el campo html_body del canal en false.

Cuando hay archivos adjuntos presentes, las alternativas del cuerpo se incluyen dentro de un multipart/mixed externo.

Manejo de archivos adjuntos

Los archivos adjuntos entrantes se almacenan en <workspace>/attachments/<conversation>/. El agente recibe las rutas de los archivos en su contexto y puede leerlos mediante la herramienta file_read. Los nombres de archivo se obtienen primero del encabezado Content-Disposition y, si no está disponible, del parámetro name de Content-Type.

Los archivos adjuntos salientes se envían a partir de los bytes proporcionados con cada archivo adjunto. El canal Email trata el nombre de archivo del archivo adjunto como metadatos de visualización, no como una ruta local. Las integraciones que envían intencionadamente un archivo local deben validar o restringir la ruta y cargarlo explícitamente con MediaAttachment::from_file antes de enviarlo.

Límites de tasa y volumen

El correo electrónico no está optimizado para la latencia conversacional. Espera:

• Latencia de la encuesta IMAP: poll_interval_secs (predeterminado 60 s). Reduzca a costa de la carga del servidor; algunos proveedores limitan las encuestas agresivas.
• Envío SMTP: sujeto a la cuota diaria de envíos de tu proveedor (Gmail: 500/día para cuentas gratuitas, 2000/día para Workspace).

Seguridad

El correo electrónico no tiene autenticación a nivel de protocolo más allá del sobre de SMTP; cualquiera puede afirmar ser cualquier persona. Restrinja los remitentes entrantes con un grupo de pares (arriba) antes de exponer el agente a una bandeja de entrada que recibe correo público.