File d’attente des e-mails retenus

Aucun e-mail n’est jamais perdu en silence. Quand Frontmail ne peut pas envoyer un message tout de suite – parce que votre organisation n’a plus de crédits, ou parce que votre service d’envoi a refusé ses identifiants – le message est accepté, conservé en lieu sûr dans la file d’attente des e-mails retenus (E-mails retenus dans le tableau de bord) et envoyé automatiquement dès que le problème est résolu.

Quand les messages sont-ils retenus ?

Motif	Statut	Déclenché par
Plus de crédits	held	Aucune attribution n’a de crédits restants (quota, packs et découvert épuisés) et l’organisation utilise le mode `hold`
Erreur du service	held_service_error	Le fournisseur a refusé les identifiants (erreur d’authentification) et le modèle n’a pas de service de secours opérationnel

Pour une rétention faute de crédits, l’API répond immédiatement :

HTTP/1.1 202 Accepted

{ "message_id": "msg_01J9Z3K7Q2", "status": "held", "status_token": "…" }

Les SDK renvoient status: 'held' – c’est un succès, pas une erreur. Affichez une confirmation normale à votre visiteur ; l’e-mail partira dès que des crédits seront disponibles.

Les rétentions pour erreur du service surviennent plus tard, dans l’expéditeur : le message a été accepté en queued, le fournisseur a refusé les identifiants, le crédit a été remboursé et le message est passé en held_service_error.

Durée de rétention

Forfait	Durée de rétention
Free	3 jours
Starter, Pro, Business	14 jours

La durée court à partir du moment où le message a été retenu, selon le forfait en vigueur à ce moment-là. Lorsque des messages retenus vont expirer dans les 24 heures, le propriétaire, les administrateurs et les membres Facturation reçoivent un e-mail « des e-mails retenus expirent bientôt » (au plus une fois par jour). Les messages qui atteignent la fin de la durée de rétention sont supprimés (statut discarded), et les mêmes personnes reçoivent un e-mail qui les liste, avec un lien pour télécharger la liste complète au format CSV. Un message retenu n’est jamais supprimé sans que personne n’en soit informé.

Limite de la file d’attente

Une organisation peut avoir au maximum 10 % du quota mensuel de son forfait en attente – au moins 1 000 et au plus 10 000 messages (Free, Starter, Pro : 1 000 ; Business 50k : 5 000 ; Business 100k et 200k : 10 000). Quand la file est pleine, les nouvelles requêtes sans crédit sont refusées avec 402 insufficient_credits et details.reason: "hold_queue_full" au lieu d’être retenues. Quelqu’un qui aurait copié votre clé publique ne peut donc pas remplir la file de messages indésirables qui – libérés du plus ancien au plus récent – consommeraient chaque nouveau crédit avant vos vrais messages. Libérez ou supprimez des messages retenus, ou achetez des crédits, pour faire de la place.

Libération automatique

Frontmail libère automatiquement la file dès que des crédits apparaissent :

un pack de crédits est acheté,
une recharge automatique réussit,
vous passez à un forfait supérieur,
une nouvelle période de facturation commence (renouvellement de l’abonnement ; Free : nouveau mois civil),
le support Frontmail ajoute des crédits bonus.

… et, pour les messages en held_service_error, lorsque le service fonctionne de nouveau (identifiants mis à jour, OAuth reconnecté ou vérification d’état réussie).

La libération traite les messages retenus du plus ancien au plus récent. Pour chaque message, elle réserve un crédit, le repasse en queued et le transmet à l’expéditeur. Elle s’arrête au premier message pour lequel il n’y a plus de crédit – les autres restent retenus, toujours dans l’ordre. La libération peut s’exécuter en parallèle sans risque ; un message n’est jamais envoyé deux fois.

Les messages envoyés avec la clé publique ne sont libérés automatiquement qu’avec des crédits autres que le découvert, sauf si vous autorisez le trafic par clé publique à l’utiliser dans Facturation → Acheter des crédits → Dépenses liées au trafic par clé publique. S’il ne reste que le découvert, ces messages restent retenus pendant que les autres sont libérés. Une libération manuelle depuis le tableau de bord peut utiliser le découvert pour eux.

Les messages retenus sont rendus avec la version du modèle qui était en vigueur au moment où ils ont été acceptés.

Libération et suppression manuelles

La page E-mails retenus du tableau de bord liste chaque message retenu, du plus ancien au plus récent, avec les colonnes Retenu depuis, modèle (avec l’objet), destinataire, Motif et Expire. Les lignes qui expirent dans les 24 heures sont mises en évidence. Filtrez par motif avec Tous / Plus de crédits / Erreur du service. Les propriétaires, administrateurs et développeurs peuvent :

Libérer N – libérer les messages sélectionnés. Pratique après avoir réparé un service, ou pour envoyer d’abord les messages les plus importants quand il ne vous reste que quelques crédits. Les messages sont libérés du plus ancien au plus récent tant qu’il y a des crédits ; les autres restent retenus et le tableau de bord vous l’indique.
Tout libérer – libérer tous les messages retenus, du plus ancien au plus récent, dans la limite des crédits disponibles.
Supprimer N – supprimer les messages sélectionnés après confirmation. Ils ne sont jamais envoyés et ne consomment pas de crédits. Cette action est irréversible.

Les propriétaires et les membres Facturation voient aussi un bouton Acheter des crédits sur la page. Si votre organisation utilise le mode reject, la page indique que les nouvelles requêtes sont refusées au lieu d’être retenues.

La barre supérieure du tableau de bord affiche toujours le nombre de crédits restants (N requêtes restantes). Cliquez dessus pour voir la répartition par source (abonnement, packs de crédits, bonus, découvert) et la prochaine expiration. Quand des messages sont retenus, un badge rouge indiquant leur nombre apparaît à côté, avec un lien vers E-mails retenus.

Mode `hold` ou `reject`

Chaque organisation choisit ce qui se passe quand il n’y a plus de crédits, dans Sécurité → Quand vous n’avez plus de crédits (propriétaires et administrateurs) :

Mode	Réponse	À utiliser quand
Retenir les e-mails (`hold`, par défaut, recommandé)	`202` avec `status: "held"`, message conservé et envoyé plus tard	Mieux vaut livrer en retard que jamais – formulaires de contact, commandes, réservations
Refuser les requêtes (`reject`)	`402` `insufficient_credits`, rien n’est conservé	Une livraison tardive est pire que pas de livraison (codes à usage unique, alertes urgentes) et votre code gère l’erreur

En mode reject, les SDK lèvent une InsufficientCreditsError. Les rétentions pour erreur du service (held_service_error) se produisent dans les deux modes, car la requête a déjà été acceptée.

Notifications

E-mail	Quand	Destinataires
Des e-mails sont en attente – vous n’avez plus de crédits	La première fois qu’un message est retenu dans un mois civil	propriétaire, administrateurs, facturation
Des e-mails retenus expirent bientôt	Au plus une fois par jour tant que des messages retenus vont expirer dans les 24 heures	propriétaire, administrateurs, facturation
E-mails retenus supprimés	Après expiration, avec la liste des messages supprimés et un lien CSV	propriétaire, administrateurs, facturation
Le service ne fonctionne pas / fonctionne à nouveau	Quand un service échoue à l’authentification / se rétablit	propriétaire, administrateurs

Voir Notifications pour la liste de tous les e-mails.

Vérifier le statut depuis le code

const res = await send('svc_01J9…', 'tpl_order', params);
if (res.status === 'held') {
  // Accepté et en sécurité – il sera envoyé automatiquement.
}

// Plus tard (les clients à clé publique ont besoin du status token renvoyé par l’envoi) :
const status = await getStatus(res.messageId, { token: res.statusToken });
console.log(status.status); // "held" → "queued" → "sent" …