E-mail

Deux canaux de messagerie électronique en fonction de la manière dont vous souhaitez recevoir les messages entrants.

Qui peut parler à l’agent

Les expéditeurs entrants sont filtrés par rapport au peer set résolu pour l’agent lié, issu de la configuration peer_groups à laquelle l’agent appartient. La correspondance supprime le @ initial et est insensible à la casse par rapport à l’identifiant d’expéditeur natif du canal. Un ensemble vide refuse tout le monde ; un ensemble contenant "*" accepte n’importe qui ; sinon, seuls les pairs externes listés (et les agents pairs) sont acceptés. Ceci est distinct de l’appairage de la passerelle (gateway.require_pairing), qui authentifie les clients HTTP/WebSocket, et non les expéditeurs des canaux de discussion.

Un groupe de pairs pour l’e-mail définit channel à email, liste les expéditeurs autorisés dans external_peers (pour l’e-mail, l’adresse e-mail de l’expéditeur ; ["*"] accepte tout le monde), nomme éventuellement des agents pairs pour la répartition inter-agents, une liste de blocage ignore, et une output_modality (mirror, voice ou text). Consultez Peer Groups pour la référence des champs.

Où définir ce paramètre :

IMAP + SMTP (email_channel)

Le canal de messagerie polyvalent. Interroge IMAP pour les nouveaux messages et envoie via SMTP. Fonctionne avec Gmail, Outlook, Fastmail, Postfix auto-hébergé et tout autre service compatible 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 (et smtp_password si vous utilisez un relais distinct) sont des secrets :

channels.email.<alias>.password est un secret. Stocké chiffré, jamais en clair dans config.toml. Définissez-le via l’une de ces méthodes, qui chiffrent à l’écriture :

zeroclaw config set channels.email.<alias>.password    # demande une saisie masquée, stocke de manière chiffrée

Pièges courants avec Gmail

• Les mots de passe d’application sont requis si l’authentification à deux facteurs (2FA) est activée. Le mot de passe du compte régulier est refusé.
• « L’accès des applications moins sécurisées » a disparu : le mot de passe d’application est la seule solution.
• Envisagez le canal Gmail Push ci-dessous pour une livraison en temps réel plutôt qu’une interrogation périodique.

Outlook / Office 365

password (et smtp_password) sont des secrets :

channels.email.<alias>.password est un secret. Stocké chiffré, jamais en clair dans config.toml. Définissez-le via l’une de ces méthodes, qui chiffrent à l’écriture :

zeroclaw config set channels.email.<alias>.password    # demande une saisie masquée, stocke de manière chiffrée

Gmail Push (gmail_push)

Diffusion en temps réel via Google Cloud Pub/Sub, sans interrogation continue.

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 et webhook_secret sont des secrets :

channels.gmail_push.<alias>.oauth_token est un secret. Stocké chiffré, jamais en clair dans config.toml. Définissez-le via l’une de ces méthodes, qui chiffrent à l’écriture :

zeroclaw config set channels.gmail_push.<alias>.oauth_token    # demande une saisie masquée, stocke de manière chiffrée

Configuration

1. Créez un projet Google Cloud, activez l’API Gmail et l’API Pub/Sub.
2. Créez un sujet Pub/Sub sur lequel le service Gmail peut publier, définissez-le comme topic
3. Autorisez l’accès Gmail de l’agent et stockez le jeton résultant via le chemin de secret ci-dessus
4. L’agent surveille les notifications de nouveaux courriels et les achemine vers l’agent lié

Les envois sortants passent toujours par SMTP : configurez un bloc [channels.email.<alias>] IMAP+SMTP.

Réponses en fil de discussion

Les deux canaux de messagerie électronique regroupent les réponses en utilisant les en-têtes In-Reply-To et References, afin que les conversations restent groupées dans le client que l’expéditeur utilise.

Format du corps sortant

Les réponses de l’agent sont envoyées en multipart/alternative avec à la fois une partie texte brut et une partie HTML par défaut. La partie HTML est le corps rendu en Markdown ; la partie texte brut est le texte brut du corps. Les clients de messagerie qui préfèrent le texte brut sélectionneront automatiquement l’alternative en texte brut.

Pour envoyer uniquement du texte brut (sans partie HTML, pour les clients ou configurations qui le préfèrent), définissez le champ html_body du canal sur false.

Lorsque des pièces jointes sont présentes, les alternatives du corps sont encapsulées dans un multipart/mixed externe.

Gestion des pièces jointes

Les pièces jointes entrantes sont stockées sous <workspace>/attachments/<conversation>/. L’agent reçoit les chemins des fichiers dans son contexte et peut les lire via l’outil file_read. Les noms de fichiers sont d’abord extraits de l’en-tête Content-Disposition, puis, à défaut, du paramètre name de Content-Type.

Les pièces jointes sortantes sont envoyées à partir des octets fournis avec chaque pièce jointe. Le canal Email traite le nom de fichier de la pièce jointe comme des métadonnées d’affichage, et non comme un chemin local. Les intégrations qui envoient intentionnellement un fichier local doivent valider ou restreindre le chemin, puis le charger explicitement avec MediaAttachment::from_file avant l’envoi.

Limites de taux et de volume

L’e-mail n’est pas optimisé pour la latence conversationnelle. Attendez-vous à :

• Latence de l’interrogation IMAP : poll_interval_secs (par défaut 60 s). Réduisez cette valeur au détriment de la charge du serveur ; certains fournisseurs limitent le nombre d’interrogations agressives.
• Envoi SMTP : soumis au quota quotidien d’envois de votre fournisseur (Gmail : 500/jour pour les comptes gratuits, 2000/jour pour Workspace).

Sécurité

L’e-mail n’a aucune authentification au niveau du protocole au-delà de l’enveloppe SMTP ; n’importe qui peut prétendre être n’importe qui. Filtrez les expéditeurs entrants avec un groupe de pairs (ci-dessus) avant d’exposer l’agent à une boîte de réception qui reçoit du courrier public.