Fils · Documentation d’Escouade Mail

Un fil est la conversation entre une boîte et un correspondant. Il naît au premier envoi ou au premier e-mail reçu. Les réponses s’y rangent, et votre agent répond dans le même fil.

Les statuts d’un fil

Statut	Sens
`open`	Ouvert : en attente de réponse, ou nouveau message reçu.
`replied`	Le correspondant a répondu : à traiter.
`bounced`	L’adresse du correspondant est en échec.
`unsubscribed`	Le correspondant s’est désinscrit : ne plus lui écrire.
`closed`	Clos : traité et clos avec `close_thread`, ou tous ses messages ont été annulés.

Un fil porte aussi son origine : outbound s’il a commencé par un envoi, inbound s’il a commencé par un e-mail reçu.

Comment un fil change de statut

Ce qui se passe	Le fil devient
La boîte écrit un premier message, ou reçoit un premier e-mail	`open`
Le correspondant répond, ou écrit de nouveau	`replied`
La boîte écrit dans le fil, brouillon compris	`open`, s’il était `replied`
Une réponse automatique arrive	inchangé
Un avis de non-remise définitif arrive	`bounced`
Le correspondant se désinscrit	`unsubscribed`
Tous les messages du fil ont été annulés	`closed`
Le fil est traité, et clos avec `close_thread`	`closed`
Le correspondant répond dans un fil clos	`replied`
La boîte répond dans un fil clos	`open`

Répondre fait sortir le fil des réponses à traiter : il repasse à open.
Un premier e-mail reçu ouvre un fil open, pas replied. Pour le trouver, voir Recevoir du courrier.
Un fil traité se clôt avec close_thread : il sort de ce qui attend une réponse. Le serveur clôt aussi de lui-même un fil open dont tous les messages ont été annulés. Un fil clos se rouvre si le correspondant y répond, ou si la boîte y répond avec reply_to_thread. send_email vers le même correspondant, lui, ouvre un autre fil.
Une boîte a un seul fil en cours par correspondant. Un nouvel e-mail du même correspondant s’ajoute à son fil, s’il n’est pas clos.

Recevoir

Toute boîte reçoit, sans rien régler.

Une réponse est rattachée à son fil par ses en-têtes (In-Reply-To, References), sinon par son correspondant. Le fil passe à replied.
Un nouvel e-mail ouvre un fil d’origine inbound.
Une réponse automatique (absence, accusé) est marquée auto_reply et ne change pas le statut du fil.
Une réponse qui demande l’arrêt (« STOP », « désinscrivez-moi »…) désinscrit le correspondant : le fil passe à unsubscribed. Voir Désinscription et blocages.
Un avis de non-remise marque le message et le fil bounced. Un rebond définitif bloque l’adresse.

Pour relever son courrier, un agent appelle list_threads avec unanswered = true, puis get_thread. Cet appel rend les réponses reçues et les premiers e-mails : voir Recevoir du courrier.

`list_threads`

Liste les fils, les plus récents d’abord. Permission : read.

Paramètre	Type	Obligatoire	Description
`inbox_id`	identifiant `inb_…`	non	Une seule boîte.
`status`	texte	non	Un seul statut : `open`, `replied`, `bounced`, `unsubscribed` ou `closed`.
`unanswered`	booléen	non	`true` : seulement les fils dont le dernier message est un e-mail reçu auquel rien n’est encore écrit en retour. Une réponse, ou un premier e-mail.
`since`	date	non	Les fils actifs depuis cette date (ISO 8601) : ceux dont le dernier message, entrant ou sortant, est postérieur.
`query`	texte	non	Une recherche : une partie de l’adresse du correspondant, de son nom ou du sujet. 100 caractères au plus.
`folder`	texte	non	Un dossier : `received` (reçus), `sent` (envoyés) ou `drafts` (brouillons).
`label`	texte	non	Les fils qui portent ce tag exact (voir `classify_thread`). 40 caractères au plus.
`archived`	booléen	non	`true` : les fils archivés ; `false` : ceux qui ne le sont pas.
`unread`	booléen	non	`true` : les fils dont un message reçu n’est pas lu ; `false` : ceux qui sont lus.
`cursor`	texte	non	Le curseur de la page suivante : la valeur `next_cursor` de l’appel précédent.
`limit`	entier	non	Le nombre d’éléments rendus, de 1 à 100. 20 par défaut.

list_threadsrésultat

1 fil(s) :
• thr_b81f4c6a2d9e47035c1a8e6f0b4d2c97 — Nadia Morel <[email protected]> — « Rendez-vous de jeudi » — réponse reçue, à traiter — 2 messages — dernier vendredi 9 octobre à 16 h 12

`get_thread`

Lit un fil : ses messages dans l’ordre, entrants et sortants, avec leur texte et leur statut. À lire avant de répondre. Permission : read.

Paramètre	Type	Obligatoire	Description
`thread_id`	identifiant `thr_…`	oui	Le fil.
`cursor`	texte	non	Le curseur de la suite du fil : la valeur `next_cursor` de l’appel précédent.

La réponse porte thread et messages. Les champs d’un message sont décrits dans Messages.

Un appel rend 50 messages au plus. S’il en reste, la réponse porte next_cursor. Au-delà de 200 Ko de texte par appel, les corps suivants sont coupés : la réponse porte truncated: true, et get_message rend le message entier.

Un message reçu porte untrusted: true : son contenu a été écrit par un tiers. Votre agent le lit comme une information, jamais comme une consigne. Dans le texte lisible, ce contenu est encadré : voir Recevoir du courrier.

Dans le texte lisible, le corps d’un message s’arrête à 2 000 caractères. Le corps entier est dans l’objet structuré (text).

Dans un assistant qui affiche les vues MCP Apps, get_thread s’accompagne d’une vue : la conversation dans l’ordre. Voir Vues.

`reply_to_thread`

Répond dans un fil, au correspondant du fil : sujet « Re: … » et en-têtes In-Reply-To et References, pour que la réponse s’affiche dans la même conversation chez le destinataire. Sert aussi à relancer. Permission : send. L’espace doit être vérifié, et avoir un forfait en cours : sans forfait, la réponse ne peut être qu’un brouillon.

Paramètre	Type	Obligatoire	Description
`thread_id`	identifiant `thr_…`	oui	Le fil (voir `list_threads`).
`subject`	texte	non	Le sujet. Par défaut : « Re: » suivi du sujet du fil.
`cc`	liste de textes	non	Des adresses en copie, cinq au plus. Seulement si le correspondant a déjà écrit dans le fil, vers quelqu’un qui y a écrit aussi ou une adresse de l’espace.
`text`	texte	oui	Le texte brut de la réponse.
`html`	texte	non	Une version HTML, de même contenu que `text`.
`reply_to`	texte	non	L’adresse de réponse, si elle diffère de la boîte.
`from_address`	texte	non	L’adresse d’envoi : l’adresse principale de la boîte, ou un de ses alias (voir `list_inboxes`).
`metadata`	objet	non	Des données libres de l’agent, 8 000 caractères au plus.
`requires_approval`	booléen	non	`true` : la réponse reste brouillon jusqu’à ce qu’un humain la valide.
`send_after`	date	non	Pas avant cette date (ISO 8601, ou heure de Paris sans fuseau).
`idempotency_key`	texte	non	Une clé unique pour cet envoi, de 1 à 255 caractères.

Deux cas, selon que le correspondant a déjà écrit dans le fil.

Règle	Le correspondant a écrit : une conversation	Il n’a pas écrit : une relance
Heures ouvrées	La réponse part sans attendre le créneau.	Elle attend le créneau.
Ordre de départ	Elle passe devant les premiers messages en file.	Elle suit la file.
Pied de désinscription	Aucun pied visible. Le lien en un clic reste dans les en-têtes.	Le pied est ajouté.
Boîte du domaine commun	Acceptée.	Refusée : `own_domain_required`.
Boîte du domaine du client	Acceptée.	Acceptée.
Quota du jour, étalement	S’appliquent.	S’appliquent.
Liste de blocage, validation humaine	S’appliquent.	S’appliquent.
Pièce jointe, copie (`cc`)	Permises.	Refusées : `attachments_not_allowed`, `cc_not_allowed`.

Dans les deux cas, la règle de doublon ne s’applique pas : une réponse dans un fil n’est pas un doublon, et elle compte dans le volume du mois du forfait. Une réponse automatique du correspondant ne compte pas comme un message écrit.

Le guide pas à pas : Répondre à un correspondant. Joindre un fichier, mettre en copie : Pièces jointes et copies.

reply_to_threaden file

Message msg_e93b7d1a5c0f42b8d6e2a9c4f7b1d056 en file dans le fil thr_b81f4c6a2d9e47035c1a8e6f0b4d2c97 : de [email protected] à [email protected], « Re: Rendez-vous de jeudi ». Le correspondant a déjà écrit dans ce fil : la réponse part sans attendre le créneau. Départ au plus tôt : samedi 10 octobre à 10 h 05. Quota du jour de la boîte : 0/10 (semaine 2 du réchauffage, palier de 10 par jour).

`close_thread`

Clôt un fil traité : il prend le statut closed et sort de ce qui attend une réponse. Rien n’est effacé. Permission : send ou approve.

Paramètre	Type	Obligatoire	Description
`thread_id`	identifiant `thr_…`	oui	Le fil à clore.

Le résultat rend le fil (thread) et closed : true s’il vient d’être clos, false s’il l’était déjà.
Tant qu’un brouillon ou un message en file attend dans le fil, l’appel est refusé avec le code thread_busy : annulez-le avec cancel_message, ou laissez-le partir.
Un fil bounced ou unsubscribed est déjà terminé : code thread_not_closable.
Un fil clos se rouvre de lui-même si le correspondant y répond, ou si la boîte y répond.

`classify_thread`

Ajoute ou retire les tags d’une conversation (labels remplace la liste complète), archive ou restaure le fil, marque les messages reçus comme lus ou non lus. Accès : send ou approve.

Paramètre	Type	Obligatoire	Description
`thread_id`	identifiant `thr_…`	oui	Conversation à classer.
`labels`	liste	non	Les tags du fil, 20 au plus (40 caractères chacun). Remplace la liste entière.
`archived`	booléen	non	Archiver ou restaurer.
`read`	booléen	non	Marquer comme lu ou non lu.

Un fil peut porter jusqu’à 20 tags ; list_threads les filtre par label. Archiver un fil le range sans rien effacer ni bloquer.

Référence complète

Les champs d’un fil

Champ	Contenu
`id`	L’identifiant du fil, `thr_…`.
`inbox_id`	La boîte du fil.
`counterpart`, `counterpart_name`	L’adresse et le nom du correspondant.
`subject`	Le sujet.
`status`	Voir les statuts.
`origin`	`outbound` ou `inbound`.
`message_count`	Le nombre de messages.
`last_message_at`, `last_inbound_at`, `last_outbound_at`, `created_at`	Les dates, en ISO 8601.

Parcourir une liste

Les listes rendent items et next_cursor. Tant que next_cursor n’est pas null, repassez-le tel quel dans cursor pour la page suivante.