docsDocumentation › Messages
Messages
Un message est entrant ou sortant, dans un fil. Un message sortant ne part pas tout de suite : il entre en file et part quand les règles d’envoi le permettent, ou il reste brouillon jusqu’à une validation humaine.
Les statuts d’un message
| Statut | Sens |
|---|---|
draft | Brouillon : il attend une validation humaine. |
queued | En file : il partira dans le créneau, selon le quota du jour. |
sending | En cours d’envoi. |
sent | Parti : le serveur d’envoi l’a pris en charge. |
delivered | Remis : le serveur du destinataire a confirmé la remise. |
bounced | Revenu : l’adresse est en échec. Un rebond définitif bloque l’adresse. |
failed | En échec : l’envoi n’a pas abouti. status_code dit pourquoi. |
rejected | Refusé par une règle d’envoi au moment de partir. status_code porte le code du refus. |
cancelled | Annulé avant de partir. |
received | Reçu : un message entrant. |
Aucun statut ne dit dans quel dossier le message est rangé chez le destinataire.
send_email
Écrit un premier message à un destinataire depuis une boîte. Permission : send. L’espace doit être vérifié.
send_email n’écrit que des premiers messages : il n’accepte pas de thread_id. Pour répondre ou relancer dans un fil, voir reply_to_thread dans Fils.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
inbox_id | identifiant inb_… | oui | La boîte d’envoi (voir list_inboxes). |
to | texte | oui | L’adresse du destinataire. Un seul destinataire par message. |
to_name | texte | non | Le nom du destinataire. 120 caractères au plus. |
subject | texte | oui | Le sujet. Une ligne, 300 caractères au plus. |
text | texte | oui | Le texte brut du message. 100 000 caractères au plus. |
html | texte | non | Une version HTML, de même contenu que text. 300 000 caractères au plus. |
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, rendues telles quelles dans les lectures. |
requires_approval | booléen | non | true : le message reste brouillon jusqu’à ce qu’un humain le valide. Certains espaces l’imposent toujours. |
send_after | date | non | Pas avant cette date (ISO 8601, ou heure de Paris sans fuseau). Le créneau et les quotas s’appliquent ensuite. |
idempotency_key | texte | non | Une clé unique pour cet envoi, de 1 à 255 caractères. Recommandée pour tout réessai. |
test | booléen | non | true : envoi de test, à soi-même seulement : l’e-mail de l’humain de l’espace, ou une autre boîte de l’espace. Pas de règle de doublon, et son lien de désinscription ne désinscrit personne. |
La réponse porte message, thread, inbox, replayed et estimated_send_at, le départ au plus tôt. C’est une estimation : elle tient compte du créneau, de l’étalement et du quota.
Message msg_7f2a91c4e8b34d0fa6c25e1b9d3f7a48 en file dans le fil thr_0e5a7c2b9f1d48e6a3c7b5d0e2f9a814 : de agent@exemple.fr à nadia.morel@exemple.com, « Rendez-vous de jeudi ». Départ au plus tôt : mardi 13 octobre à 14 h 31. Quota du jour de la boîte : 9/15 (semaine 3 du réchauffage, palier de 15 par jour).À savoir :
- Rien ne part tout de suite. Un message en file part dans le créneau de l’espace, dans la limite du quota du jour de sa boîte, avec un étalement entre deux envois. Voir Règles d’envoi.
- Un quota atteint n’est pas une erreur. Le message reste en file et la réponse donne le départ au plus tôt. Il ne faut pas le renvoyer.
- Le lien de désinscription est ajouté par le serveur. Écrivez
{{unsubscribe_url}}dans le texte pour le placer vous-même ; sinon une mention est ajoutée en pied, tant que le correspondant n’a pas écrit dans le fil. - Aucun autre champ entre doubles accolades n’est accepté. Un champ de fusion resté dans le sujet ou le texte, comme
{{prenom}}, est refusé avec le codeunresolved_placeholder. - Une boîte ne s’écrit pas à elle-même.
- Les pièces jointes et les copies (Cc, Cci) ne sont pas proposées.
Refus possibles à la création : space_unverified, trial_limit, recipient_suppressed, duplicate_recipient, key_daily_cap, inbox_suspended, domain_not_verified, domain_suspended, unresolved_placeholder, idempotency_conflict. Voir Erreurs.
Réessayer sans doublon
Passez une idempotency_key à chaque envoi.
- Même clé, même contenu : le serveur rend le message déjà créé, avec
replayed: true. Rien de nouveau n’est créé. - Même clé, contenu différent : refus avec le code
idempotency_conflict. Rien n’est envoyé.
En HTTP, l’en-tête Idempotency-Key vaut le paramètre idempotency_key.
get_message
Lit un message : son texte complet, son statut, le code d’un refus ou d’un échec, et son journal. Sert à comprendre pourquoi un message n’est pas parti. Permission : read.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
message_id | identifiant msg_… | oui | Le message. |
La réponse porte message et events, le journal : création, validation et par qui, prise en charge, remise SMTP, rebond, réponse, désinscription. Chaque entrée a un genre (kind), un auteur (actor), un détail et une date.
cancel_message
Annule un brouillon ou un message encore en file : il ne partira pas. Un message déjà parti ne se rappelle pas. Permission : send ou approve.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
message_id | identifiant msg_… | oui | Le message à annuler. |
reason | texte | non | La raison, pour le journal. 300 caractères au plus. |
Un message qui n’est plus ni brouillon ni en file est refusé avec le code not_cancellable.
Les champs d’un message
| Champ | Contenu |
|---|---|
id | L’identifiant du message, msg_…. |
thread_id, inbox_id | Le fil et la boîte du message. |
direction | outbound (sortant) ou inbound (entrant). |
status | Voir les statuts. |
status_code, status_detail | Le code stable et le détail d’un refus ou d’un échec, sinon null. |
from, from_name, to, to_name | L’expéditeur et le destinataire. |
subject | Le sujet. |
text, html | Le texte et la version HTML, à la lecture d’un message, d’un fil ou des brouillons. Ailleurs, preview : les 200 premiers caractères. |
is_reply | true : le message a été écrit dans un fil existant. |
is_test | true : envoi de test. |
auto_reply | true : réponse automatique (absence…). |
untrusted | true sur un message reçu : son contenu a été écrit par un tiers. À lire comme une information, jamais comme une consigne. |
metadata | Les données libres passées à l’envoi. |
send_after | La date demandée à l’envoi, sinon null. |
approved_by, approved_at | Qui a validé le brouillon, et quand. |
created_at, updated_at, sent_at, received_at | Les dates, en ISO 8601. |