Recevoir des emails par API : récupérer les messages en JSON

L’email est l’une des dernières interfaces “human-first” que la plupart des équipes logicielles doivent encore automatiser. Si vous développez des flux de vérification d’inscription, des tests QA, ou des agents LLM qui doivent accomplir des tâches du monde réel, vous devez éventuellement recevoir des emails par API, de manière fiable, et dans un format qui ne nécessite pas de scraping HTML fragile.

Une API de boîte de réception programmable résout cela en transformant les emails entrants en JSON structuré, puis en les livrant à votre code via des webhooks (push) et/ou du polling (pull). Cet article explique la conception de base, à quoi devrait ressembler un contrat JSON pratique, et comment l’intégrer dans une automation qui est déterministe et sécurisée.

Si vous intégrez spécifiquement avec Mailhook, la référence d’intégration machine-readable canonique est le fichier llms.txt du projet : Contrat API Mailhook (llms.txt).

Ce que signifie réellement “recevoir des emails par API” (et pourquoi le JSON est essentiel)

Quand les développeurs disent “recevoir des emails”, ils veulent souvent dire l’une de ces choses :

• Récupérer un message depuis une boîte mail (IMAP/POP), puis analyser RFC 5322 et MIME soi-même.
• Recevoir un événement de message (webhook), puis le stocker et l’analyser.
• Interroger une boîte de réception par un ID, obtenir des champs normalisés et du contenu pour l’automation.

Pour l’automation et les agents, les parties difficiles sont rarement la livraison SMTP elle-même. La douleur, c’est tout ce qui vient après la livraison :

• MIME est multi-partie, imbriqué, et plein de cas limites d’encodage.
• Les en-têtes peuvent être pliés, dupliqués, et contrôlés par l’attaquant.
• Les corps peuvent être lourds en HTML, remplis de tracking, ou manquer de text/plain.
• Le timing est non-déterministe, vous ne pouvez pas “dormir 5 secondes” et espérer de la fiabilité.

Une bonne API de boîte de réception transforme l’email brut (défini par RFC 5322 plus MIME, voir RFC 2045) en une représentation JSON stable, pour que votre automation puisse faire des assertions sur des champs, pas sur un rendu fragile.

Le modèle adapté à l’automation : boîtes de réception et messages, pas de comptes à long terme

Le changement clé est de traiter une boîte de réception comme une ressource à courte durée de vie, plus proche d’une file de messages que d’une boîte mail personnelle :

• Vous créez une boîte de réception programmatiquement.
• Vous obtenez une adresse email routable pour cette boîte de réception.
• Votre système envoie un email à cette adresse.
• Vous récupérez les messages en JSON (webhook ou polling).
• Vous faites optionnellement tourner ou expirez la boîte de réception pour maintenir l’isolation stricte.

Cette approche “inbox-first” est ce qui rend prévisibles les exécutions CI parallèles, les chaînes d’outils multi-agents, et les flux de vérification avec beaucoup de tentatives.

À quoi devrait ressembler le JSON ? Un contrat pratique pour QA et agents LLM

Différents fournisseurs exposent différents schémas, mais l’automation robuste tend à avoir besoin des mêmes pièces conceptuelles :

Concept email	Pourquoi vous en avez besoin	Exemples de champs JSON (illustratifs)
Identifiant de message stable	Déduplication, idempotence	message_id, provider_id, rfc822_message_id
Horodatage d’arrivée	Budgets temporels, débogage	received_at
Adresses d’enveloppe	Routage et assertions	from, to, cc, reply_to
Sujet	Correspondance et corrélation	subject
En-têtes (normalisés)	Débogage, corrélation, signaux d’auth	headers (map ou liste, normalisé)
Contenu texte (préférer text/plain)	Analyse sécurisée pour les agents	text, text_plain, body_text
Contenu HTML (optionnel, traiter avec précaution)	Débogage humain, fallbacks	html, body_html
Métadonnées des pièces jointes	Sécurité, extraction d’artefacts	attachments[] avec filename, content_type, size
Source brute (optionnelle mais précieuse)	Forensique quand les parseurs ne sont pas d’accord	raw ou source

Deux recommandations pratiques pour les environnements d’agent et de test :

1. Préférez text/plain pour les assertions et l’extraction. Le HTML est utile pour les humains, mais c’est une surface large et favorable aux attaquants pour l’automation.
2. Gardez une source brute disponible pour le débogage. Quand quelque chose casse en CI, pouvoir inspecter le contenu exact livré peut sauver des heures.

Le positionnement produit de Mailhook est explicitement centré sur ceci : créer des boîtes de réception jetables via API et recevoir des emails comme JSON structuré, conçu pour les agents LLM et l’automation QA. Pour les noms de champs exacts et formats de payload, utilisez la référence canonique : mailhook.co/llms.txt.

Récupérer les messages : webhook d’abord, polling en fallback

Il y a deux façons communes de “recevoir des emails par API”, et la plupart des configurations de production utilisent les deux.

Webhooks (push)

Avec un webhook, le fournisseur de boîte de réception appelle votre endpoint quand un nouveau message arrive. C’est idéal quand vous voulez des workflows rapides, pilotés par les événements.

Points forts :

• Faible latence, pas de boucles de polling
• Modèle de flux d’événements naturel
• Passe bien à l’échelle quand beaucoup de boîtes de réception sont actives

Exigences opérationnelles :

• Vous devez implémenter les tentatives et l’idempotence
• Vous devez vérifier l’authenticité (signatures)
• Vous avez besoin d’un endpoint accessible depuis l’internet public (ou un tunnel sécurisé)

Mailhook supporte les notifications webhook en temps réel et les payloads signés pour la sécurité (vérifiez les signatures avant de faire confiance au contenu).

Polling (pull)

Avec le polling, votre code demande au fournisseur les messages dans une boîte de réception jusqu’à ce qu’une correspondance arrive ou qu’un timeout soit atteint.

Points forts :

• Simple à raisonner dans les test runners
• Fonctionne même si votre endpoint webhook est en panne
• Bon chemin de fallback pour la fiabilité

Coûts :

• Latence plus élevée (selon l’intervalle)
• Plus d’appels API

Mailhook inclut une API de polling pour les emails, qui est un complément pratique aux webhooks.

Comparaison rapide

Mécanisme	Meilleur pour	Piège de fiabilité	Conseil par défaut
Webhook	Automation temps réel, haute concurrence	Livraisons dupliquées, risque de replay	Vérifiez les signatures, dédupliquez par ID message
Polling	Tests CI, chemins de fallback	Les sleeps fixes causent des flakes	Pollez avec un timeout et backoff, matcher étroitement

Récupération déterministe : matcher le bon message, pas “le dernier email”

La plupart des instabilités viennent d’un matching ambigu. Si vous faites seulement “récupérer le dernier message”, alors les tentatives, les exécutions parallèles, et la livraison retardée vous brûleront.

Une stratégie déterministe inclut généralement :

• Isolation de boîte de réception : une boîte de réception par exécution, par tentative, ou par session d’agent.
• Token de corrélation : inclure un run_id ou nonce dans un endroit que vous pouvez matcher.
• Matchers étroits : filtrer par expéditeur attendu, préfixe de sujet attendu, ou token unique.
• Budget de temps explicite : une fonction unique qui attend jusqu’à une deadline.

Pour la corrélation, l’option la plus robuste est d’ajouter votre propre en-tête comme X-Correlation-Id (quand vous contrôlez l’expéditeur). Si vous ne pouvez pas, utilisez un token de sujet ou un paramètre de lien unique.

Une interface minimale “attendre un email” (adaptée aux agents)

Que vous construisiez un harness de test ou un outil LLM, l’abstraction la plus propre est une surface API petite et déterministe :

• create_inbox() → retourne { inbox_id, address }
• wait_for_message(inbox_id, matcher, timeout_ms) → retourne un unique message JSON
• extract_verification_artifact(message) → retourne { otp } ou { url }

Cela évite au LLM ou test runner de gérer la sémantique de recherche de boîte mail. Cela réduit aussi le risque d’injection de prompt parce que l’agent n’a pas besoin de “tout l’historique de boîte de réception”, seulement un artefact minimal.

Exemple : récupérer un OTP depuis JSON (pseudocode)

Le code ci-dessous est intentionnellement agnostique du fournisseur. Il illustre le flux de contrôle et les vérifications de sécurité sans supposer des endpoints Mailhook exacts ou noms de champs.

Récupération basée sur le polling

import re
import time

def wait_for_message(fetch_messages, inbox_id, timeout_s=60, poll_interval_s=1.5):
    deadline = time.time() + timeout_s
    seen_ids = set()

    while time.time() < deadline:
        messages = fetch_messages(inbox_id)  # retourne une liste d'objets JSON de message

        for msg in messages:
            msg_id = msg.get("message_id") or msg.get("id")
            if msg_id and msg_id in seen_ids:
                continue
            if msg_id:
                seen_ids.add(msg_id)

            subject = (msg.get("subject") or "").lower()
            sender = (msg.get("from") or "").lower()

            # Exemple de matcher étroit
            if "verify" in subject and "no-reply" in sender:
                return msg

        time.sleep(poll_interval_s)

    raise TimeoutError("Aucun email correspondant n'est arrivé avant le timeout")


def extract_otp(message_json):
    text = message_json.get("text") or message_json.get("text_plain") or ""
    m = re.search(r"\b(\d{6})\b", text)
    if not m:
        raise ValueError("OTP non trouvé dans le corps texte")
    return m.group(1)

Récupération basée sur webhook (haut niveau)

En mode webhook, vous inversez le flux :

• Votre endpoint webhook reçoit le JSON du message.
• Vous vérifiez la signature.
• Vous écrivez le message dans le stockage indexé par inbox_id.
• Votre test runner ou agent attend sur ce stockage (ou une file interne) pour un événement correspondant.

Mailhook supporte les payloads signés, donc la vérification devrait être une étape de première classe. Pour le schéma de signature exact et les en-têtes, consultez : Mailhook llms.txt.

Sécurité et sûreté : traiter l’email comme une entrée non fiable (surtout avec les LLM)

Si un agent LLM lit des emails, vous devez supposer que le contenu peut être hostile. Même les emails de vérification peuvent contenir du contenu inattendu, des fils transférés, ou des liens malveillants si un attaquant peut déclencher des messages vers votre boîte de réception.

Garde-fous pratiques :

• Vérifiez les signatures webhook et rejetez les payloads non signés ou invalides.
• Ne rendez pas le HTML dans les pipelines d’agents. Préférez text/plain plus extraction stricte.
• Mettez en liste blanche ce que vous extrayez. Pour les liens magiques, validez le hostname et le path contre des patterns attendus avant de les suivre.
• Minimisez la rétention et les logs. Les emails contiennent souvent des secrets, tokens, ou PII.
• Contraignez la sortie de l’outil. Donnez à l’agent seulement l’OTP ou une URL validée, pas l’email brut complet.

Ces contrôles ne sont pas seulement de l’hygiène de sécurité, ils améliorent la fiabilité parce que votre pipeline devient déterministe et moins sensible à la dérive de template.

Où Mailhook s’intègre : boîtes de réception jetables + sortie JSON + webhooks

Si vous implémentez “recevoir des emails par API” pour des agents ou CI, Mailhook est conçu autour des primitives que vous finissez typiquement par construire vous-même :

• Création de boîte de réception jetable via API
• Emails livrés comme JSON structuré
• Webhooks temps réel (avec payloads signés)
• API de polling comme chemin de fallback
• Domaines partagés pour démarrages rapides et support de domaine personnalisé pour un contrôle plus strict
• Traitement d’emails en lot pour des workflows à plus haut débit

Si vous voulez les formats exact de requête/réponse (et vous construisez des outils pour les LLM), commencez par la référence canonique : https://mailhook.co/llms.txt, puis connectez-le à votre harness de test ou outils d’agents.

Une checklist de fiabilité avant de livrer

Avant de vous fier à la récupération d’emails dans l’automation, assurez-vous de pouvoir répondre “oui” à ceci :

• Vous créez une boîte de réception fraîche par exécution, tentative, ou session.
• Votre logique d’attente est basée sur une deadline, pas de sleeps fixes.
• Vous dédupliquez par ID de message (ou un identifiant stable équivalent).
• Vos règles de matching sont étroites et adaptées à la corrélation.
• Vous vérifiez les signatures webhook (si vous utilisez des webhooks).
• Vous extrayez des artefacts minimaux (OTP, URL validée) plutôt que de nourrir des emails entiers dans un agent.

Si vous implémentez ceci, “recevoir des emails par API” devient un bloc de construction prévisible au lieu de l’étape la plus instable de votre pipeline.

Pour explorer les boîtes de réception programmables de Mailhook et la récupération d’emails JSON, voir Mailhook et gardez le contrat d’intégration à portée de main : Mailhook llms.txt.