API d'Email Entrant : Comment Recevoir des Emails Programmatiquement pour les Agents IA

Une API d'email entrant permet a votre application de recevoir des emails programmatiquement. Au lieu d'interroger une boite aux lettres ou de scanner une boite de reception, les messages entrants sont delivres a votre code en temps reel via des webhooks. Pour les agents IA qui doivent lire, comprendre et repondre aux emails, une API d'email entrant est le bloc fondamental qui rend possibles les flux de travail email autonomes.

Ce guide explique comment fonctionnent les APIs d'email entrant, comment en configurer une avec AgentSend, et pourquoi le modele de webhook par boite est mieux adapte aux agents IA que les approches traditionnelles comme l'interrogation IMAP ou l'analyse d'entree au niveau du domaine.

Qu'est-ce qu'une API d'Email Entrant ?

Une API d'email entrant est un service qui accepte les emails entrants en votre nom et les delivre a votre application sous forme de donnees structurees. Le flux typique fonctionne ainsi : les enregistrements MX dirigent le courrier entrant vers les serveurs du fournisseur d'API, le fournisseur analyse l'email brut en un payload structure (expediteur, sujet, corps, pieces jointes, en-tetes), puis delivre ce payload a une URL de webhook que vous configurez.

L'avantage cle par rapport a la reception d'email traditionnelle est que votre application ne gere jamais de serveur de messagerie. Il n'y a pas de connexion IMAP a maintenir, pas d'intervalle d'interrogation POP3 a ajuster, et pas d'analyse MIME brute a implementer. Vous recevez un payload JSON propre via HTTP POST, le traitez et repondez avec un code de statut 200. C'est toute l'integration.

Pour les agents IA, cela compte car les agents doivent reagir aux emails entrants en temps reel. Un agent de support client ne peut pas attendre cinq minutes la prochaine interrogation IMAP pour decouvrir un nouveau ticket. Une API webhook d'email delivre le message au moment ou il arrive, permettant a votre agent de commencer le traitement immediatement.

Comment Fonctionne l'Email Entrant dans AgentSend

L'API de reception d'email d'AgentSend est construite autour de webhooks par boite. Lorsque vous creez une boite, vous pouvez configurer une URL de webhook qui recoit chaque message entrant pour cette boite specifique. Chaque boite est isolee : il n'y a pas de couche de routage partagee ou vous devez inspecter les adresses des destinataires et dispatcher vers le bon gestionnaire.

Chaque livraison de webhook inclut une signature HMAC dans l'en-tete X-AgentSend-Signature. Votre application verifie cette signature a l'aide du secret webhook de votre boite pour confirmer que le payload a ete envoye par AgentSend et n'a pas ete altere en transit. Si votre endpoint est temporairement indisponible, AgentSend retente la livraison avec un delai exponentiel pendant 24 heures maximum.

Configuration de l'Email Entrant

Demarrer avec l'API de boite email d'AgentSend necessite deux etapes : creer une boite avec une URL de webhook, puis gerer les payloads entrants.

Etape 1 : Creer une Boite avec un Webhook

Avec cURL :

curl -X POST https://api.agentsend.io/v1/inboxes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-agent",
    "webhook_url": "https://yourapp.com/webhooks/inbound-email",
    "webhook_secret": "whsec_your_secret_here"
  }'

Avec Python :

import requests

resp = requests.post(
    "https://api.agentsend.io/v1/inboxes",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "support-agent",
        "webhook_url": "https://yourapp.com/webhooks/inbound-email",
        "webhook_secret": "whsec_your_secret_here",
    },
)
inbox = resp.json()
print(inbox["email"])  # support-agent@yourteam.agentsend.io

Etape 2 : Gerer le Payload du Webhook

Lorsqu'un email arrive, AgentSend envoie un payload JSON a votre URL de webhook. Voici un gestionnaire minimal en Python avec Flask :

import hmac, hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_secret_here"

@app.route("/webhooks/inbound-email", methods=["POST"])
def handle_inbound():
    # Verify HMAC signature
    signature = request.headers.get("X-AgentSend-Signature")
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return jsonify({"error": "invalid signature"}), 401

    payload = request.json
    sender = payload["from"]
    subject = payload["subject"]
    body = payload["body_text"]
    thread_id = payload["thread_id"]

    # Pass to your AI agent for processing
    process_with_agent(sender, subject, body, thread_id)

    return jsonify({"status": "ok"}), 200

API d'Email Entrant vs Approches Traditionnelles

Il existe plusieurs facons de recevoir des emails programmatiquement. Voici comment les approches les plus courantes se comparent pour les cas d'utilisation d'agents IA.

La difference critique est l'isolation. Mailgun et SendGrid operent au niveau du domaine : vous pointez les enregistrements MX de votre domaine vers leurs serveurs, et tout le courrier entrant pour ce domaine arrive sur un seul endpoint webhook. Vous etes responsable d'inspecter l'adresse du destinataire dans chaque payload et de le router vers le bon agent. Avec AgentSend, chaque boite a son propre webhook, son propre secret de signature et son propre historique de fils. Il n'y a pas de logique de routage a construire ou a maintenir.

API de Boite Email : Creer des Boites Programmatiquement

L'un des aspects les plus puissants d'une API de boite email est la capacite de creer des boites a la volee. Lorsque votre plateforme integre un nouveau client, provisionne un nouvel agent IA ou lance un nouveau flux de travail, vous pouvez creer une boite dediee avec un seul appel API. Chaque boite obtient automatiquement sa propre adresse email : pas de configuration DNS, pas de configuration manuelle, pas d'attente de propagation.

C'est particulierement utile pour les architectures multi-agents. Un systeme de support client pourrait creer des boites separees pour les questions de facturation, le support technique et la gestion des comptes. Chaque boite est routee vers un agent specialise avec son propre endpoint webhook et son propre historique de conversation. Passer d'un agent a cinquante est une boucle d'appels API, pas un projet de migration DNS.

Cas d'Utilisation des APIs d'Email Entrant

Une API d'email entrant ouvre une gamme de flux de travail d'agents autonomes qui sont difficiles ou impossibles a construire avec une infrastructure email traditionnelle.

• Agents de support client — Recoivent les tickets de support par email, classifient l'intention, resolvent les questions courantes automatiquement et escaladent les problemes complexes aux agents humains avec le contexte complet du fil.
• Agents de recherche — S'abonnent aux newsletters, recoivent des rapports et traitent les flux d'informations entrants. L'agent lit chaque email, extrait les donnees pertinentes et met a jour une base de connaissances sans intervention humaine.
• Agents de planification — Recoivent les demandes de reunion et les reponses de disponibilite par email. L'agent analyse le contenu, verifie les calendriers et envoie des reponses de confirmation, le tout via sa propre adresse email dediee.
• Agents sortants avec gestion des reponses — Les agents qui envoient des emails de prospection, des sequences de suivi ou des notifications peuvent recevoir et traiter les reponses via la meme boite, en maintenant le contexte complet de la conversation.

Dans chaque cas, l'API d'email entrant elimine la charge d'infrastructure. Votre code d'agent se concentre sur la comprehension et la reponse aux messages, et non sur le maintien de connexions IMAP, l'analyse MIME ou le routage des emails vers le bon gestionnaire.