docsDocumentation › Fils
Fils
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. |
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.
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_replyet 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 traiter les réponses, un agent appelle list_threads avec status = replied, puis get_thread.
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. |
since | date | non | Les fils actifs depuis cette date (ISO 8601). |
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. |
1 fil(s) :
• thr_b81f4c6a2d9e47035c1a8e6f0b4d2c97 — Nadia Morel <nadia.morel@exemple.com> — « Rendez-vous de jeudi » — réponse reçue, à traiter — 2 messages — dernier vendredi 9 octobre à 16 h 12get_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.
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é.
| 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. |
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. |
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é. |
| Limites d’essai | Le correspondant compte, une seule fois. | Le destinataire compte, une seule fois. |
| Quota du jour, étalement | S’appliquent. | S’appliquent. |
| Liste de blocage, validation humaine | S’appliquent. | S’appliquent. |
Dans les deux cas, la règle de doublon ne s’applique pas : une réponse dans un fil n’est pas un doublon. Une réponse automatique du correspondant ne compte pas comme un message écrit.
Message msg_e93b7d1a5c0f42b8d6e2a9c4f7b1d056 en file dans le fil thr_b81f4c6a2d9e47035c1a8e6f0b4d2c97 : de agent@exemple.fr à nadia.morel@exemple.com, « 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).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.