Automatiser son CRM avec l'IA : le guide de l'API Contact Mailpro™ v3

La plupart des données CRM sont saisies deux fois : une fois dans un formulaire, une fois dans votre tête quand vous oubliez de mettre à jour le formulaire. Les agents IA comblent ce trou. Donnez à Claude, GPT ou Gemini une API de gestion de contacts et une consigne claire, et ils sauront créer ou mettre à jour des contacts, appliquer des tags, construire des segments, nettoyer des données sans qu'un humain touche une interface. Ce guide montre exactement comment le faire avec l'API Contact Mailpro v3.

En résumé

• v3 est full JSON (snake_case), authentifiée par JWT Bearer token.
• On récupère un token via POST /v3/token — valide 365 jours.
• Les contacts sont identifiés par UUID ; les listes, tags et champs par entiers.
• Chaque endpoint est documenté dans plus de 20 langages sur notre portail développeurs.

Pourquoi exposer son CRM à un agent IA ?

Les agents comme nouvelle couche de saisie

La saisie CRM par formulaire est un problème résolu — et résolu mal depuis 20 ans. Les agents permettent de sauter le formulaire. Un utilisateur tape « nouveau lead : Alice de ShopCorp, elle est intéressée par notre offre enterprise, à rappeler la semaine prochaine ». L'agent parse, appelle POST /v3/Contact avec des données structurées, tague « intérêt-enterprise » et programme un rappel. Zéro frappe dans un formulaire.

Trois scénarios concrets

• Enrichissement de leads. Un webhook part d'un formulaire ; l'agent enrichit avec des sources publiques, upsert le contact dans Mailpro v3, puis le tague avec un score de lead.
• Hygiène des listes. Cron hebdomadaire ; l'agent interroge les listes pour détecter doublons, données obsolètes, contacts non classés, puis réorganise les tags en conséquence.
• Segmentation dynamique. « Déplace tous les contacts ayant ouvert la dernière campagne Soldes dans le segment warm-leads » — l'agent lit les stats depuis v2 puis appelle v3 pour re-taguer les contacts.

Authentifier un agent IA avec JWT

POST /v3/token avec le grant password

La voie la plus simple :

curl -X POST "https://api.mailpro.com/v3/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "[email protected]" \
  -d "password=YOUR_API_KEY"

Réponse :

{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "expires_in": 31535999,
  "refresh_token": "eyJhbGciOi..."
}

Stockez l'access_token en lieu sûr (variable d'environnement serveur, coffre) et passez-le en Authorization: Bearer <token> sur tous les appels v3 suivants.

Dur\u00e9e de vie du token : 365 jours

Les tokens Mailpro sont conçus pour durer — les agents IA tournent en continu, vous ne voulez pas de tempête de refresh. Si vous avez besoin de rotation, utilisez le refresh token ou émettez simplement un nouveau token périodiquement.

Les grants tiers

Si vous construisez une intégration Zapier, Make ou Microsoft Flow, utilisez les types de grant dédiés (zapier, microsoft-flow, etc.). Ils émettent un JWT avec un rôle ThirdParty. La plupart des intégrations d'agent peuvent rester sur le grant password.

Pas à pas : « Claude, ajoute ce contact, tague VIP, mets-le en liste 42 »

C'est ici que la conception v3 brille : un prompt, trois appels API, zéro interface.

1. Les schémas d'outils

Donnez à votre agent trois outils étroits, pas un gros. Les outils étroits sont plus faciles à choisir correctement pour le modèle.

tools = [
    {
        "name": "upsert_contact",
        "description": "Crée ou met à jour un contact Mailpro à partir de son email.",
        "input_schema": {
            "type": "object",
            "properties": {
                "email":      {"type": "string", "format": "email"},
                "first_name": {"type": "string"},
                "last_name":  {"type": "string"},
                "fields":     {"type": "object", "description": "Valeurs de champs personnalisés"}
            },
            "required": ["email"]
        }
    },
    {
        "name": "tag_contact",
        "description": "Applique un tag à un contact par UUID.",
        "input_schema": {
            "type": "object",
            "properties": {
                "contact_id": {"type": "string"},
                "tag_name":   {"type": "string"}
            },
            "required": ["contact_id", "tag_name"]
        }
    },
    {
        "name": "add_to_list",
        "description": "Ajoute un contact à une liste Mailpro par ID de liste.",
        "input_schema": {
            "type": "object",
            "properties": {
                "contact_id": {"type": "string"},
                "list_id":    {"type": "integer"}
            },
            "required": ["contact_id", "list_id"]
        }
    }
]

2. Le raisonnement de l'agent

Face au prompt « Ajoute Alice Zhang de ShopCorp ([email protected]), tague VIP, mets-la en liste 42 », Claude raisonne :

1. Appeler upsert_contact avec {email: "[email protected]", first_name: "Alice", last_name: "Zhang"}.
2. Lire le contact_id retourné.
3. Appeler tag_contact avec {contact_id, tag_name: "VIP"}.
4. Appeler add_to_list avec {contact_id, list_id: 42}.

Trois appels d'outil, une intention utilisateur. C'est ça, la boucle agentique.

3. Exécuter en séquence

def execute_tool(name, args, token):
    base = "https://api.mailpro.com/v3"
    headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

    if name == "upsert_contact":
        r = requests.post(f"{base}/Contact", headers=headers, json={
            "email": args["email"],
            "first_name": args.get("first_name"),
            "last_name": args.get("last_name"),
            "fields": args.get("fields", {})
        })
        return r.json()

    elif name == "tag_contact":
        r = requests.post(f"{base}/Tag/{args['tag_name']}/Contact",
                          headers=headers, json={"contact_id": args["contact_id"]})
        return r.json()

    elif name == "add_to_list":
        r = requests.post(f"{base}/List/{args['list_id']}/Contact",
                          headers=headers, json={"contact_id": args["contact_id"]})
        return r.json()

4. Gérer les règles métier (réponses 406)

v3 renvoie HTTP 406 pour les violations de règles métier, avec un body JSON :

{ "Message": "A contact already exist with the same Email" }

Motifs 406 courants :

Marre d’entretenir vos listes à la main ? Les offres Mailpro incluent l’API Contacts pour que votre agent IA garde vos listes propres et segmentées — automatiquement.

• Email cannot be empty
• Email has an invalid format
• A contact already exist with the same Email
• The email address was unsubscribed permanently
• One or more lists have reached the contact limit

Apprenez à votre agent à lire le champ Message et à rebondir avec élégance : sur un doublon, chercher le contact existant et le mettre à jour plutôt qu'abandonner. Sur un email invalide, demander une correction à l'utilisateur.

Champs personnalisés et segments

Créer un champ personnalisé (/v3/Field)

curl -X POST "https://api.mailpro.com/v3/Field" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "lead_score", "field_type": "Number"}'

Construire un segment avec règles (/v3/Segment)

Les segments sont dynamiques — ils se mettent à jour à mesure que les données contacts changent. Les agents adorent : créez un segment une fois, laissez les règles matcher les contacts à l'infini.

« Claude, déplace les ouvreurs de la dernière campagne dans le segment Hot Leads »

Exactement le genre de tâche multi-étapes où v3 brille. L'agent :

1. Interroge les stats v2 (/stats/open) pour trouver les ouvreurs de la dernière campagne.
2. Pour chaque ouvreur, appelle v3 pour l'ajouter au segment Hot Leads (via tag ou en modifiant un champ de scoring).

Les workflows cross-API comme celui-ci sont justement ce que les agents IA unifiés débloquent.

Importer des contacts en masse via agent

Quand votre agent se déclenche sur un événement « nouvelle liste de leads » (upload CSV, feuille partagée, export CRM), ne bouclez pas un-à-un. Utilisez l'endpoint d'import bulk :

curl -X POST "https://api.mailpro.com/v3/Import/Upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "id_list=42" \
  -F "[email protected]" \
  -F "webhook_url=https://example.com/hooks/import-done"

L'endpoint renvoie un import_job_id immédiatement. Quand le traitement se termine, Mailpro envoie un callback à votre webhook_url avec le bilan (importés / ignorés / invalides). Votre agent peut utiliser le webhook comme signal pour enchaîner les actions de suivi (« import terminé → lancer la campagne de bienvenue »).

Le workflow complet : enrichissement commercial

Trigger : webhook Stripe sur nouveau client. Objectif : l'agent doit enrichir le client, l'ajouter au CRM et envoyer un email de bienvenue.

1. Enrichir. L'agent appelle une API externe (Clearbit, People Data Labs, scraper maison) pour obtenir nom d'entreprise, rôle, LinkedIn.
2. Upsert dans Mailpro v3. POST /v3/Contact avec email + champs enrichis.
3. Taguer et lister. L'agent tague stripe-customer et ajoute le contact à la liste Clients payants.
4. Email de bienvenue. L'agent appelle l'API v2 /send/sendmail.json avec un message personnalisé utilisant le nom enrichi.

Quatre appels d'outil, deux API, un onboarding fluide. Coût côté humain : zéro.

Astuces et pièges

snake_case vs PascalCase

v3 est en snake_case (first_name, list_id, contact_id). v2 est en PascalCase (FirstName, ListId). Si votre agent parle aux deux API, précisez-le dans le prompt système pour qu'il n'invente pas de noms de champs.

Les erreurs métier renvoient 406, pas 400

400 = données malformées. 406 = données valides mais en violation d'une règle métier. L'agent doit faire la différence : 400 est un bug de code ; 406 est une issue normale dont il doit se sortir.

50 000 requêtes mensuelles par défaut

v3 applique un plafond mensuel de requêtes par compte. Les agents qui bouclent agressivement le heurtent. Groupez avec /v3/Contact/Multiple quand c'est possible. Voir le plafond dans votre tableau de bord.

Cas d'usage (fictif) : « CoraAssur », courtier IA qui trie 2 000 leads / jour

CoraAssur est un agrégateur de courtiers en assurance. Chaque jour, 2 000 leads arrivent dans leur webhook depuis des comparateurs. Auparavant, deux data operators nettoyaient et routaient chaque lead à la main. Avec Claude branché sur Mailpro v3, le workflow est devenu :

1. Webhook se déclenche → Claude reçoit le JSON du lead.
2. Claude enrichit (valide l'email, normalise le téléphone en E.164, déduit le produit d'assurance depuis le texte libre).
3. Claude appelle upsert_contact, applique les tags (auto, habitation, vie), ajoute à la bonne liste.
4. Claude score le lead (0-100) et écrit le score dans le champ personnalisé lead_score.
5. Les leads à haut score déclenchent automatiquement un email de bienvenue v2.

Le temps de traitement d'un lead est passé de 6 minutes (humain) à 4 secondes (agent). La qualité des données s'est améliorée — Claude est plus strict sur la validation d'email que des humains fatigués. Les deux opérateurs ont été réaffectés à du vrai travail de courtage.

Et maintenant ?

Avec v3 qui gère votre CRM et v2 pour l'envoi, il ne reste plus que le SMS. Direction notre guide SMS pour donner à votre agent le dernier canal. Ou retournez au guide pilier pour la vue d'ensemble.

Documentation de référence : API CRM v3. Tarifs : prix Mailpro.

FAQ

Mailpro v3 supporte-t-il OAuth ou seulement le grant password ?

Les deux. password est le plus simple ; client_credentials fonctionne pour les flux machine-à-machine ; zapier, automateio et microsoft-flow sont des grants tiers dédiés qui émettent un JWT avec un rôle ThirdParty.

Puis-je migrer les contacts Mailpro v2 vers v3 ?

Oui — les deux API frappent la même base de données contacts en dessous. Un contact créé via v2 est visible et pilotable via v3, et réciproquement.

Comment les champs personnalisés fonctionnent-ils avec l'IA ?

Créez le champ une fois via POST /v3/Field avec un type (Text, Number, Date, Boolean). Ensuite, l'agent peut poser des valeurs sur les contacts via fields dans le payload. Les champs personnalisés servent aussi de variables de personnalisation dans les campagnes email.

Quelle est la différence entre une liste, un tag et un segment ?

Une liste est une collection statique où vous ajoutez explicitement des contacts. Un tag est une étiquette légère (un contact peut en avoir plusieurs). Un segment est une requête dynamique — « tous les contacts où tag='VIP' et country='CH' » — qui se met à jour seule quand les données contacts changent. Voir aussi notre article sur la délivrabilité email qui explique comment bien segmenter pour mieux délivrer.