Documentation › 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é.
Un premier message part d’une boîte du domaine du client, avec un forfait en cours. Avant le paiement, seul un envoi de test (test) part, et un brouillon se prépare. Depuis la boîte du domaine commun, un premier message est refusé avec le code own_domain_required. Voir Prix et paiement.
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. |
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, 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. Il part même sans forfait, et ne compte pas dans le volume du mois. |
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 [email protected] à [email protected], « 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 volume du mois atteint n’est pas une erreur non plus. Le message reste en file et part à la période suivante.
billing_statusdonne le volume parti. - 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.
- Un premier message part sans pièce jointe ni copie. Elles ne vont que dans une conversation : voir Pièces jointes et copies. La copie cachée (Cci) n’est pas proposée.
Refus possibles à la création : space_unverified, payment_required, own_domain_required, recipient_suppressed, duplicate_recipient, key_daily_cap, inbox_suspended, domain_not_verified, domain_suspended, unresolved_placeholder, idempotency_conflict, test_recipient_not_allowed, queue_full. 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 (detail) et une date (at). Le journal d’un message est gardé douze mois.
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).
Pour un message en file, le texte de get_message dit pourquoi il attend, et quand il peut partir au plus tôt :
En file : le quota du jour de la boîte est atteint (15/15). Départ au plus tôt : mercredi 14 octobre à 9 h.Les raisons que donne cette ligne : l’espace n’est pas vérifié, la boîte est suspendue, le domaine n’est pas vérifié, l’envoi est différé (send_after), le quota du jour est atteint, le créneau d’envoi est fermé, ou le message attend son tour. Le volume du mois se lit dans billing_status.
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. |
cc | Sur un message envoyé : les adresses en copie. Sur un message reçu : ses autres destinataires. |
attachments | Les pièces jointes : id, filename, content_type, size, stored. Voir Pièces jointes et copies. |
subject | Le sujet. |
reply_to | L’adresse de réponse, si elle diffère de la boîte, sinon null. |
has_html | true : le message a une version HTML. |
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. |
revision | La version du message : elle change à chaque modification. À repasser à approve_message pour ne valider que ce qui a été lu. |
truncated | true, dans get_thread : le corps a été coupé (200 Ko au plus par appel). get_message rend le message entier. |
created_at, updated_at, sent_at, received_at | Les dates, en ISO 8601. |