Envois ponctuels

Un envoi ponctuel (broadcast), c'est l'e-mail que tu écris une fois et que tu envoies à une audience, maintenant ou à une date : une promo, une annonce, une newsletter. À la différence d'une séquence, il ne dépend pas de la date d'inscription de chacun : tout le monde le reçoit au même moment, une seule fois.

Concept

Un envoi ponctuel a un contenu (objet, pré-en-tête, corps HTML, texte brut facultatif, nom d'expéditeur et adresse de réponse facultatifs) et une audience :

• un segment — une audience décrite par des conditions qui se tiennent à jour seules (« a cliqué ces 30 jours », « pays = MA »…), voir Segments ;
• ou des listes entières — tous les abonnés consentants des listes choisies, sans condition.

Il passe par cinq états :

Les règles qui te protègent

1. Consentement d'abord. Seuls les abonnés subscribed d'une liste active et non supprimée, absents de la suppression, reçoivent. Jamais pending_confirm, unsubscribed, bounced ni complained. La règle est appliquée deux fois : quand l'audience est constituée, puis de nouveau juste avant chaque e-mail (un abonné qui se désinscrit entre les deux ne reçoit rien).
2. Une adresse, un e-mail. Une adresse inscrite sur plusieurs listes ciblées ne reçoit qu'un exemplaire. La ligne retenue est celle de la liste au plus petit identifiant : son lien de désinscription et son serveur SMTP sont ceux de cette liste.
3. Jamais deux fois. Même si deux instances de Trackily tournent en même temps (déploiement progressif), l'audience n'est constituée qu'une fois.
4. L'audience est figée au lancement. Le segment est évalué une seule fois, au moment où l'envoi passe en_cours. Quelqu'un qui s'inscrit après n'est pas ajouté. Le nombre figé est noté (total_destinataires).
5. L'audience annoncée est celle qui part. Dès qu'un envoi est programmé, son audience (segment ou listes) ne change plus (409 audience_verrouillee : déprogramme-le d'abord), et le segment qu'il utilise ne se modifie ni ne se supprime (409 segment_utilise, qui nomme l'envoi) tant qu'il est programmé ou en cours. Reprogrammer refait toutes les vérifications.
6. Le contenu est verrouillé dès le lancement. Une fois en_cours, termine ou annule, l'envoi ne se modifie plus (refus 409 envoi_verrouille) : tout le monde reçoit le même e-mail. Pour corriger ou renvoyer, duplique-le.
7. Les confirmations et les séquences passent d'abord. À chaque passage, le moteur prend d'abord les e-mails de confirmation et de séquence dus, puis complète avec les envois ponctuels : une newsletter de 10 000 contacts ne retarde jamais une confirmation ni un e-mail de bienvenue.
8. Pas de commande dans un envoi ponctuel. Les variables de commande ({{order_table}}, {{order_total}}…) restent vides.
9. Les mêmes garde-fous que les séquences. Plafonds horaire et journalier du serveur SMTP, serveur désactivé = envoi retenu 24 h puis échec smtp_indisponible, suivi des ouvertures et des clics selon les réglages de la liste, pied de désinscription et en-têtes List-Unsubscribe toujours présents.

Écrire et programmer un envoi

Dans l'admin : Email Marketing → Envois ponctuels, puis « Nouvel envoi ».

1. Donne-lui un nom (interne) et choisis l'audience : « Un segment » ou « Des listes entières ».
2. Écris l'objet, le pré-en-tête (le texte que les messageries affichent après l'objet) et le corps HTML. Les variables sont les mêmes que dans les séquences : {{first_name}}, {{name}}, {{email}}, {{custom.X}}, {{list_name}}, {{unsubscribe_url}}…
3. Envoie un essai à ton adresse : un exemplaire réel, objet préfixé [ESSAI], variables rendues avec un abonné fictif « Prénom ». Il ne compte dans aucune statistique.
4. Programme : maintenant ou à une date. Avant de confirmer, Trackily te dit le nombre exact de destinataires. Un envoi déjà programmé se reprogramme de la même façon : seule la date change.

Tu peux enregistrer ton brouillon à tout moment, même sans audience ni contenu : les vérifications ont lieu quand tu programmes. La programmation est refusée si :

Les autres refus que tu peux croiser : audience_verrouillee (409, changer l'audience d'un envoi programmé : déprogramme-le d'abord), envoi_en_cours (409, suppression d'un envoi en cours : annule-le d'abord), essai_echoue (502, le serveur SMTP a refusé l'e-mail d'essai — le message dit pourquoi), requete_invalide (400, une valeur mal formée), introuvable (404). Tous les refus de cette page sont des 400 sauf mention contraire.

Suivre un envoi

Chaque envoi affiche un verdict calculé par le serveur :

La progression compte les envoyés, en file, échecs (échecs définitifs et rebonds), ignorés (désinscrits entre-temps, annulés). Les statistiques d'un envoi : ouvertures uniques, clics uniques, désinscriptions, rebonds, taux d'ouverture et de clic sur les envoyés (« — » tant que rien n'est parti).

Dans l'API, les taux sont des parts de 0 à 1 (arrondies à 4 décimales : 0.2481 = 24,81 %), null si 0 envoyé ; l'écran les affiche en pourcentage. audience_estimee (détail d'un brouillon ou d'un programmé) est le nombre entier de contacts qui recevraient maintenant ; null une fois lancé (le chiffre figé est alors total_destinataires).

Une désinscription est imputée à l'envoi quand elle suit sa réception sans qu'un autre e-mail soit parti à cette personne entre les deux (le lien de désinscription est celui de l'abonné, pas de l'envoi).

Dans le journal des envois (Sends Log) et la chronologie d'un abonné, un envoi ponctuel se nomme « Envoi ponctuel : » : chaque ligne porte broadcast_id et broadcast_name (null hors envoi ponctuel). Le journal se filtre par ?broadcast_id=.

Si un envoi en cours attend faute de serveur SMTP actif, la page affiche une alerte qui le nomme (le plus ancien s'il y en a plusieurs).

Déprogrammer ou annuler

Le même geste (« Annuler », POST …/annuler, outil cancel_email_broadcast) fait deux choses selon l'état :

• Programmé → déprogrammé : rien n'est parti, l'envoi redevient un brouillon (sa date est effacée, son audience redevient modifiable). Réponse : { ok: true, status: 'brouillon', retires: 0 }.
• En cours → annulé : les e-mails encore en file passent skipped (motif envoi_annule). Ce qui est parti est parti. Réponse : { ok: true, status: 'annule', retires: N }.

Test A/B

Écris deux (ou trois) versions d'un envoi, envoie-les à un échantillon, et Trackily envoie automatiquement la gagnante au reste de l'audience.

• Les variantes. La variante A, c'est l'envoi lui-même. B (et C, facultative) peuvent changer l'objet, le pré-en-tête et/ou le corps ; un champ laissé vide reprend celui de A. Une variante sans aucun champ différent de A est refusée (ab_invalide) dès son enregistrement (test actif), et de nouveau à la programmation si A est devenu pareil entre-temps : un test entre deux e-mails pareils ne mesure que du bruit. Une variante qui a son propre corps HTML et pas de texte brut part avec un texte brut dérivé de son HTML (jamais celui de A).
• Les réglages. La part de test (de 10 à 50 % de l'audience, défaut 20 %), répartie à parts exactement égales entre les variantes ; la durée du test (de 1 à 72 h, défaut 4 h) ; le critère : taux d'ouverture ou taux de clic uniques, rapportés aux envoyés (défaut : ouvertures).
• Au lancement, toute l'audience est figée comme d'habitude. Le tirage est déterministe (un hachage de l'adresse et de l'envoi, pas du hasard) : la part de test reçoit sa variante tout de suite, le reste attend la décision (statut attente_ab dans le journal, progression.attente_ab — la ligne « en attente du test » — ni « en file », ni un échec). Il faut au moins 20 destinataires par variante : sinon la programmation est refusée (ab_audience_trop_petite, qui dit le minimum d'audience). La répartition annoncée avant de programmer (« 2 × 120 maintenant, puis la gagnante aux 960 autres ») est exactement celle qui part.
• La décision, une seule fois, à l'échéance (lancement + durée) : le meilleur taux sur le critère gagne ; égalité → la variante la plus ancienne (A, puis B). On ne décide pas sur un test inachevé : tant qu'un e-mail du test est encore en file (serveur SMTP retenu, plafond atteint…) ou qu'une variante a moins de 20 envoyés (ou moins que toute sa part, si elle est plus petite), la décision est reportée de 30 minutes, au plus 48 h après l'échéance ; passé ce délai, elle tranche sur ce qui est parti (rien de parti → A) et la phrase le dit : « Gagnante : B — décision sur un test incomplet (…) ». Une décision qui échoue (erreur inattendue) est retentée 10 minutes plus tard, sans bloquer les autres. Le reste reçoit la gagnante dès ce passage du moteur. « Choisir maintenant » fait la même chose avant l'échéance, avec la variante que tu choisis ou la meilleure du moment — sans lettre, il faut au moins un envoyé par variante (sinon 409 ab_rien_a_comparer : choisis une variante précise) ; un test déjà décidé refuse (409 ab_deja_decide).
• L'audience a fondu au lancement (désinscriptions depuis la programmation) au point de donner moins de 20 destinataires par variante : l'envoi part sans A/B, la variante A à tous, et la phrase le dit (« Test A/B abandonné : … »). Dans l'API : ab.statut = 'aucun', ab.decision = 'abandonne'.
• Test désactivé = rien à valider : un envoi dont le test est décoché n'est jamais refusé pour ses réglages ou ses variantes ; tout est revérifié quand tu le réactives.
• Verrouillé au lancement, comme le contenu : variantes et réglages ne changent plus. Annuler pendant le test retire aussi le reste qui attend. Un envoi A/B n'est terminé qu'une fois décidé et sans e-mail en attente. Dupliquer copie les réglages et les variantes (la copie n'est pas décidée).
• Les résultats par variante sont ceux du test : envoyés, ouvertures et clics uniques, taux (parts de 0 à 1), et la gagnante marquée. Le verdict dit « Test A/B en cours — décision à venir » pendant le test (« … en attente de la fin du test » une fois l'échéance passée) — le serveur ne met jamais d'heure dans ses phrases : l'instant de la décision, decision_at_prevue, s'affiche dans ton heure locale. Puis la phrase du test dit « Gagnante : B (+4,2 pts d'ouverture) ».
• Pendant le test, le détail dit la variante en tête (meneuse, null tant que rien n'est parti) et combien de destinataires recevront la gagnante (recevront).
• L'essai d'une variante : « Envoyer un essai » de la variante affichée ({ to, lettre }), objet préfixé [ESSAI B] ; sans lettre, l'essai envoie A.

Dans l'API : ab: { actif, part_test, duree_heures, critere, variantes: [{ lettre, subject, preheader, body_html, body_text }] } sur POST/PUT (refus 400 ab_invalide, qui nomme le champ dans champ : part_test, duree_heures, critere, variantes, variantes[0].subject… ; variantes donné remplace l'ensemble des variantes) ; GET …/:id rend ab (réglages, statut aucun | test_en_cours | decide, gagnante, decide_at, decision auto | manuelle, decision_at_prevue, variantes, resultats, meneuse, recevront, repartition_prevue: { variantes, test_par_variante, reste }, libelle) ; chaque ligne de GET /email/broadcasts?detail=1 porte ab: { actif, statut, libelle, decision_at_prevue } (null sur une base sans v145) et progression.attente_ab ; POST …/:id/ab/choisir { lettre? } → { ok, gagnante, mis_en_file }.

Éditeur visuel

Plutôt que d'écrire le HTML, clique « Éditeur visuel » à côté de la zone HTML (onglets A, B et C compris) : des blocs à glisser, des modèles de départ, et un HTML compatible avec les messageries. Le projet de l'éditeur est gardé (body_design) pour rouvrir l'e-mail ; modifier le HTML à la main ensuite le détache. Tout est expliqué dans Éditeur visuel.

Via MCP

// 1er appel : l'aperçu, rien n'est programmé
{ "name": "schedule_email_broadcast", "arguments": { "id": 12 } }
// → { "pending": true, "preview": { "destinataires": 4980, "moment": "maintenant", … }, "confirm_token": "cfm_…" }

// 2e appel : mêmes arguments + le jeton
{ "name": "schedule_email_broadcast", "arguments": { "id": 12, "confirm_token": "cfm_…" } }
// → { "ok": true, "total_estime": 4980, "scheduled_at": "…" }

Un refus (audience_vide, sans_serveur, envoi_verrouille…) revient en résultat lisible, avec son code et une phrase française.

API (admin)

Toutes sous /admin/api, lecture landings:read, écriture landings:write :

GET /email/broadcasts (le tableau des envois ; ?detail=1 rend { envois, sante: { programmes, en_cours, envoyes_30j, taux_ouverture_30j }, alerte: null | { etat: 'retenu', libelle, envoi_id } } — c'est ce que lit l'écran) · GET /email/broadcasts/:id · POST /email/broadcasts · PUT /email/broadcasts/:id · DELETE /email/broadcasts/:id · POST /email/broadcasts/:id/test { to, lettre? } · POST /email/broadcasts/:id/programmer { scheduled_at? } (brouillon ou programmé) · POST /email/broadcasts/:id/annuler · POST /email/broadcasts/:id/dupliquer (rend la copie entière, avec son id) · POST /email/broadcasts/:id/ab/choisir { lettre? }.

Limites connues

• Le débit est celui de chaque serveur SMTP (v151, Débit d'envoi) : 60 e-mails par minute par défaut, réglable jusqu'à 2 000, dans la limite des plafonds de chaque serveur, les confirmations et les séquences servies d'abord. Un envoi de 5 000 contacts prend environ une heure et vingt-cinq minutes à 60 par minute, moins de dix minutes à 600 par minute (sur une base sans la v151 : 50 par minute, une heure et quarante minutes).
• Si un lancement échoue (une erreur inattendue), l'envoi reste programmé et il est retenté 10 minutes plus tard ; les autres envois ne sont pas bloqués.
• Avant un retour arrière du serveur sous la version qui a introduit les envois ponctuels (v140), annule les envois en cours : voir OPERATIONS.md.
• Pas encore d'heure d'envoi optimisée par contact pour les envois ponctuels ; le test A/B ne porte pas encore sur les séquences.
• Avant un retour arrière sous la v145, décide ou annule les tests A/B en cours : voir OPERATIONS.md.
• Les rebonds différés et les plaintes ne remontent pas : seuls les refus immédiats du serveur SMTP sont captés (voir Suppression).

Voir aussi

• Segments — décrire une audience par des conditions
• Éditeur visuel — composer un e-mail sans écrire de HTML
• Sequences — les envois automatiques, par abonné
• SMTP — plafonds, serveur retenu, « Peut envoyer ? »
• Suppression — qui n'est jamais contacté