API d'emails transactionnels pour agents IA : guide Mailpro™ v2

Si vous avez lu notre guide sur les agents IA et les API Mailpro™, vous connaissez le principe : le modèle décide, votre code envoie. Cet article se concentre sur une seule API, l'Email API v2 de Mailpro™, et détaille une configuration opérationnelle pour les emails transactionnels et les campagnes pilotés par Claude, GPT ou tout LLM compatible avec le tool calling, avec les endpoints et les paramètres exacts.

En bref

• URL de base https://api.mailpro.com/v2, réponses en JSON, jeton bearer OAuth 2.0 (ou l'ancien couple IdClient + ApiKey).
• Un email à une personne : POST /send/sendmail.json. Un modèle enregistré à toute une liste : POST /send/campaign.json.
• Suivez chaque email transactionnel avec GET /send/{IdSingleSend}/status.json ou les webhooks email.delivered / email.bounced.
• Importez des contacts en masse depuis un agent avec POST /import/upload.json (CSV ou XLSX, jusqu'à 50 Mo).

Emails pilotés par l'IA : quels cas d'usage en valent la peine ?

Des confirmations de commande intelligentes

Une confirmation standard, c'est un modèle. Un agent peut y ajouter un mot personnel ("Merci d'avoir choisi le Blue XL, le préféré de nos clients") et des recommandations pertinentes, puis l'envoyer via l'API. Vous gardez la fiabilité d'un modèle structuré avec la chaleur d'un mot écrit à la main.

Le tri automatique du support

Quand un ticket arrive, l'agent le classe, rédige une réponse et, s'il est suffisamment sûr de lui et que le sujet figure sur une liste approuvée, l'envoie. Tout le reste passe à un humain, brouillon en pièce jointe.

Des synthèses plutôt qu'un déluge

L'agent lit les événements de la journée (factures, inscriptions, alertes) et envoie un seul récapitulatif à 18 h : "Aujourd'hui : 12 payées, 3 en retard, 2 à vérifier." Un seul email, aucun bruit. L'API s'occupe de la livraison ; le modèle, de la synthèse.

Comment configurer l'Email API v2 en 5 minutes ?

1. Obtenez vos identifiants

Dans votre compte Mailpro™, allez dans Settings → API access. Pour un agent, créez un client OAuth et ne demandez que les scopes dont il a besoin, en général email:send et email:read. Les anciens identifiants IdClient (numérique) et ApiKey (GUID) fonctionnent aussi, mais ils ne sont pas limités par scope : réservez-les à vos propres scripts back-end.

2. Vérifiez la connexion

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://api.mailpro.com/v2/account/credits.json

Vous devez obtenir vos crédits email restants au format JSON. Un 401 signifie que le jeton ou la clé est erroné ; un 403 insufficient_scope signifie que le jeton ne dispose pas de account:read.

3. Trouvez votre ID d'expéditeur

Les emails partent d'une adresse d'expéditeur validée. GET /senderEmail/list.json renvoie ces adresses avec leurs ID ; c'est cet ID que vous passerez dans IDEmailExp.

Pas à pas : faire envoyer un email transactionnel par Claude

L'exemple utilise Claude d'Anthropic, mais le même principe fonctionne avec le function calling d'OpenAI ou le tool use de Gemini : le SDK change, l'architecture reste la même.

1. Définissez l'outil

tools = [{
  "name": "send_transactional_email",
  "description": "Envoie un email à un client via Mailpro.",
  "input_schema": {
    "type": "object",
    "properties": {
      "to":      {"type": "string"},
      "subject": {"type": "string"},
      "html":    {"type": "string", "description": "Corps HTML complet"}
    },
    "required": ["to", "subject", "html"]
  }
}]

2. Rédigez le prompt système

Tu aides les conseillers du service client à rédiger et envoyer des emails de suivi.
N'appelle send_transactional_email qu'après la confirmation de l'humain.
Sois concis et chaleureux, et inclus toujours un lien avec un appel à l'action clair.

3. Exécutez l'appel vers /send/sendmail

import requests

def send_transactional_email(args, token, sender_id):
    r = requests.post(
        "https://api.mailpro.com/v2/send/sendmail.json",
        headers={"Authorization": f"Bearer {token}"},
        data={
            "IDEmailExp": sender_id,       # issu de /senderEmail/list
            "EmailData":  args["to"],      # email,champ1,champ2...
            "Subject":    args["subject"],
            "BodyHTML":   args["html"],
            "ActivateStatistics": "true",  # suivi des ouvertures et des clics
        },
    )
    r.raise_for_status()
    return r.json()   # {"SingleSend": {"IdSingleSend": 8001, ...}}

Champs optionnels utiles : DatePlanned (ISO 8601) pour programmer l'envoi au lieu d'envoyer tout de suite, ReplyTo, BodyText pour une version texte brut, et attachments. Renvoyez le JSON au modèle comme résultat de l'outil pour qu'il puisse annoncer à l'utilisateur que l'email est en route.

Vous branchez des envois transactionnels ? Les emails automatiques de Mailpro partent instantanément à chaque déclencheur — reçus, confirmations, alertes — avec une délivrabilité sur laquelle vous pouvez compter.

4. Confirmez la livraison

GET /send/8001/status.json renvoie delivered, bounced (avec BounceType et le DiagCode du serveur), deferred, sent, scheduled ou queued. Comptez environ cinq minutes après la remise au serveur pour obtenir delivered. Pour un retour en temps réel, abonnez-vous aux webhooks email.delivered et email.bounced plutôt que d'interroger l'API en boucle.

Campagnes : l'agent prépare, un humain appuie sur Envoyer

Pour un envoi à toute une liste, l'agent travaille avec un modèle enregistré plutôt qu'avec du HTML brut :

curl -X POST https://api.mailpro.com/v2/send/campaign.json \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d "IDMessage=55" \
  -d "IDEmailExp=201" \
  -d "ListId=101" \
  -d "Campaign=1" \
  -d "TitleCampaign=April newsletter" \
  -d "DatePlanned=2026-05-01T09:00:00"

DatePlanned est facultatif : sans lui, la campagne part immédiatement. Une bonne pratique consiste à laisser l'agent choisir la liste, le modèle et une heure d'envoi selon le fuseau horaire de l'audience, puis à soumettre ce plan à un humain qui l'approuve. Les campagnes programmées peuvent encore être déplacées avec PATCH /send/{IdSend}/reschedule.json ou annulées avec POST /send/{IdSend}/cancel.json.

La personnalisation avec des champs

Dans /send/sendmail, EmailData reçoit l'adresse suivie de 25 valeurs au maximum ([email protected],Alice,Dupont,Paris) qui remplissent les champs de personnalisation du modèle. Dans les campagnes, les champs proviennent des données de chaque contact de la liste. L'agent n'a qu'à placer le champ dans son HTML ; l'API le remplit pour chaque destinataire.

Importer des contacts en masse à partir d'un fichier envoyé par un agent

Quand la première étape d'un workflow est "ajoute ces 500 nouveaux leads", ne faites pas 500 appels API. Envoyez un seul fichier :

curl -X POST https://api.mailpro.com/v2/import/upload.json \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -F "ListId=42" \
  -F "[email protected]" \
  -F "WebhookUrl=https://example.com/hooks/import-done"

Le fichier doit être en UTF-8, avec une ligne d'en-tête qui contient Email ; les autres colonnes sont associées aux champs personnalisés de la liste. L'endpoint renvoie immédiatement un ImportJobId, traite le fichier en arrière-plan et appelle votre WebhookUrl avec le nombre de lignes importées, ignorées et invalides.

Pièges à éviter et conseils

• Les adresses désabonnées sont refusées. L'API répond "Email address unsubscribed." avec un code 400. Indiquez à l'agent que c'est définitif, et non une erreur à retenter.
• Surveillez vos crédits. "Not enough credit available." revient avec un code 403. Abonnez-vous au webhook credits.low pour qu'un humain recharge le compte avant que l'agent ne se heurte au mur.
• Tenez compte du quota de requêtes. Les appels API sont décomptés d'un quota mensuel partagé par les API Email, CRM et SMS (GET /account/limits.json). Plafonnez le nombre d'appels d'outils par conversation et espacez les tentatives en cas de 429.
• Restez sur JSON. Le XML est pris en charge avec le suffixe .xml, mais le JSON est plus simple pour la sortie des outils d'un LLM.
• Authentifiez votre domaine. Même personnalisés et rédigés par l'IA, les emails ont toujours besoin de SPF, DKIM et DMARC pour atteindre la boîte de réception ; consultez notre guide de dépannage de la délivrabilité.

Étude de cas (fictive) : "NovaFit", un réseau de salles de sport aux rappels de cours rédigés par l'IA

NovaFit gère 40 salles de sport et envoie un rappel 24 heures avant chaque cours réservé. Auparavant, les rappels se résumaient à un seul modèle ("Bonjour Anna, votre cours de yoga a lieu demain à 7 h"). L'équipe a placé Claude derrière le système de réservation : pour chaque rappel, l'agent lit l'assiduité récente de l'adhérent et le type de cours, rédige une phrase personnelle ("La semaine dernière, vous avez tenu la posture du guerrier une minute entière, prête pour le niveau suivant ?") et envoie l'email avec /send/sendmail. Les rebonds remontent via le webhook email.bounced et sont signalés à l'accueil. Le taux d'ouverture des rappels est passé de 46 % à 63 % et la fréquentation a progressé de 8 points, sans aucune hausse du volume d'emails.

Prochaines étapes

L'Email API v2 se charge de l'envoi. Si votre agent doit aussi gérer des contacts, des tags, des segments et des champs personnalisés, lisez notre guide de la CRM API v3 pour l'IA. Pour les SMS, consultez l'envoi de SMS avec un agent IA. Vous hésitez entre une plateforme gérée et un simple service d'envoi ? Consultez notre guide des meilleures alternatives à Amazon SES. Référence complète : la documentation de l'Email API v2.