EN
Copied
Modules

Délivrabilité inbox

Délivrabilité inbox

Teste où un message envoyé depuis un domaine donné atterrit réellement. Le module n'envoie rien à la place de l'appelant — le vrai message est envoyé à quinze boîtes seed, et le module remonte où chacune l'a classé : inbox principale, onglet secondaire (Promotions, Social) ou spam.

Le résultat est un instantané de la façon dont une boîte destinataire a traité ce message précis, depuis ce domaine précis, à ce moment précis. Ce n'est ni une simulation, ni un lookup de réputation, ni une inspection d'en-têtes. Le module répond à une seule question : si ce message est envoyé depuis ce domaine maintenant, où va-t-il ?

Inputs

Un job de test prend deux valeurs.

Champ Requis Description
domain oui Le domaine d'envoi à tester, en minuscules, sans @ (par exemple acme.fr). Doit contenir un point et faire 3 à 120 caractères.
subject_filter non Sous-chaîne optionnelle comparée aux sujets dans les boîtes seed. Utile pour désambiguïser quand plusieurs tests tournent en parallèle depuis le même domaine. Jusqu'à 120 caractères.

Le module ne prend pas de liste de destinataires. La délivrabilité inbox est un job standalone — il ne fait pas partie d'un pipeline et ne peut pas consommer la sortie d'un autre job.

Outputs

Le job écrit une ligne par boîte seed dans results_delivery.csv. Quinze boîtes seed sont interrogées ; chaque ligne décrit ce que cette boîte a observé.

Colonne Description
seed_email Adresse de la boîte de test concernée par la ligne.
seed_kind Famille de fournisseur de la seed (sert à grouper les résultats par type de boîte).
status received si le message a été trouvé, sinon un état vide ou en attente.
placement Où le message a atterri : Inbox principal, Inbox · <tab> (par exemple Promotions, Social), Spam, ou vide si non reçu.
subject Sujet tel qu'observé dans la boîte seed.
received_relative Délai lisible entre envoi et observation (par exemple 2 min).

L'endpoint de rapport structuré agrège ces lignes en un résumé.

Champ Description
received Nombre de seeds ayant observé le message.
total Total de boîtes seed interrogées (15).
missing total - received.
primary Seeds dont le placement est Inbox principal.
primary_pct Taux d'inbox principale en pourcentage de received.
inbox_secondary Seeds dont le placement est un onglet inbox non-principal.
promotions Seeds dont le placement correspond à Promotions ou Social.
spam Seeds dont le placement est Spam.
spam_pct Taux de spam en pourcentage de received.
verdict Verdict contextuel — voir ci-dessous.
seeds Tableau par seed décrit dans la table précédente.

L'objet verdict porte un jugement en une ligne et une note actionnable.

verdict.label Quand
EXCELLENT primary_pct ≥ 90.
TRÈS BON primary_pct ≥ 70.
MOYEN primary_pct ≥ 50.
MAUVAIS spam_pct ≥ 50.
INSUFFISANT La plupart des messages ont atterri dans des onglets secondaires.
EN ATTENTE Rien reçu pour l'instant.

Cycle de vie

États de job standard — voir Cycle de vie des jobs. Le déroulé d'exécution : créer le job, récupérer les seeds via GET /api/delivery-check/seeds, envoyer le vrai message aux quinze depuis le domaine testé, attendre que le worker poll jusqu'à ce que toutes les seeds remontent received ou qu'un timeout déclenche, puis lire le rapport agrégé.

Le module ne se chaîne pas. Sa sortie n'est pas réutilisable en entrée d'un autre job — la délivrabilité inbox est listée dans le set de jobs non-chaînables aux côtés de viewport_test.

Pipeline

La délivrabilité inbox est standalone_only.

Si une campagne doit réagir à un résultat de placement, le rapport est consommé via l'API et branché dans une orchestration externe — le module ne nourrira pas directement un autre nœud.

Endpoints

Méthode Chemin Rôle
POST /api/jobs/delivery-check Créer un job delivery-check. Body : { "domain": "...", "subject_filter": "..." }. Retourne l'objet job public.
GET /api/delivery-check/seeds Lister les quinze adresses seed auxquelles envoyer le message de test.
GET /api/jobs/{job_id}/delivery-result Rapport agrégé avec résumé, verdict et lignes par seed.
GET /api/jobs/{job_id} Statut de job standard (queued, running, done, failed).

Tous les endpoints requièrent un utilisateur authentifié et actif. Lire le job d'un autre utilisateur retourne 403.

Le budget par job est fixé à quinze observations seed ; pas de slider, pas d'override. La délivrabilité inbox ne consomme pas de crédits scraping (ef_per_item: 0), même si le quota par utilisateur s'applique encore. Une exécution complète atterrit typiquement entre deux et huit minutes après l'envoi du message seed. Le domaine doit contenir un point et est mis en minuscules en interne. Pour les caps globaux, voir Limites.

Erreurs

Statut Raison
400 Domaine d'envoi invalide — le domaine est vide ou ne contient pas de point.
400 Quota dépassé — MAX_EF_PER_JOB atteint. La délivrabilité inbox est gratuite en soi, mais le check quota s'applique quand même.
400 Pas un job de test de délivrabilité — /delivery-result appelé sur un job dont le type n'est pas delivery_check.
403 Le job appartient à un autre utilisateur.
404 L'ID de job n'existe pas.
410 Le CSV du job a expiré et a été supprimé.

Si le rapport retourne received: 0 après l'exécution du worker, le message seed n'est jamais arrivé — soit il n'a pas été envoyé, soit il a été bloqué entièrement, soit le domaine est sur une blocklist complète. Renvoyer aux seeds et re-poller avant de conclure.

Pour aller plus loin