Brancher Mailchimp sur votre logiciel métier, votre CRM ou votre boutique

Deux API sous un même nom : Marketing ou Transactional ?

Avant de parler connecteur, il faut savoir quelle API Mailchimp on vise. L'API Marketing gère la relation avec vos listes : audiences, contacts, segments, campagnes, parcours, rapports. Mailchimp Transactional, anciennement Mandrill, envoie les messages que votre application déclenche un par un : confirmation de commande, réinitialisation de mot de passe, avis d'expédition.

Selon sa référence, l'API Marketing répond à l'adresse https://api.mailchimp.com/3.0/, suit en général les conventions REST, avec quelques écarts,, renvoie du JSON et décrit chaque point d'accès en OpenAPI ; les actions qui ne correspondent pas à une méthode HTTP passent par un sous-chemin actions/.

Clé d'API ou OAuth 2 : à qui appartient l'accès ?

Pour relier votre logiciel à votre compte Mailchimp, la documentation désigne la clé d'API comme l'identifiant adapté à une application qui travaille sur vos propres données. Trois de ses caractéristiques imposent des précautions :

• elle ouvre tout le compte : il n'existe ni clé en lecture seule, ni clé limitée à certains points d'accès ;
• elle n'expire pas et reste valide jusqu'à sa suppression, ou jusqu'à celle de l'utilisateur qui l'a créée ;
• elle ne quitte jamais le serveur : Mailchimp refuse les appels de navigateur (CORS) vers l'API Marketing, et une clé intégrée à une application mobile peut en être extraite.

OAuth 2 sert quand votre application accède aux comptes Mailchimp d'autres entreprises, par exemple un logiciel édité pour plusieurs clients. Le code d'autorisation s'échange contre un jeton côté serveur, pour protéger le secret client. Ces jetons n'expirent pas et n'ont pas de jeton de rafraîchissement : un jeton refusé impose de relancer l'autorisation. OAuth 2 est aussi exigé pour publier une intégration sur la Mailchimp Marketplace.

En pratique, nous créons la clé sous un utilisateur dédié à l'intégration, et non sous le compte d'un salarié dont le départ supprimerait l'accès.

Dix connexions, 120 secondes : construire autour des limites

L'API Marketing accepte 10 connexions simultanées par utilisateur, quelle que soit la clé, et renvoie une erreur 429 au-delà ; tout appel est coupé après 120 secondes. Mailchimp précise qu'il ne relève pas ces plafonds au cas par cas et qu'un dépassement peut entraîner la désactivation de l'accès.

Une PME les rencontre surtout lors de la reprise initiale de sa base ou d'une resynchronisation complète. La réponse prévue par Mailchimp est le point d'accès Batch :

1. le connecteur envoie un lot d'opérations (méthode, chemin, corps, identifiant operation_id) ;
2. Mailchimp l'exécute en arrière-plan, sans ordre garanti, avec un statut (pending, preprocessing, started, finalizing, finished) et le compte des opérations réussies ou en erreur ;
3. un webhook de lot (20 au plus par compte) prévient le connecteur, qui télécharge l'archive des résultats ; le lien expire au bout de dix minutes, les résultats restent sept jours ;
4. chaque résultat est rapproché de la fiche d'origine par son operation_id, et les erreurs sont rejouées.

Au-delà de 500 lots en attente, Mailchimp refuse les nouveaux. La documentation consultée ne décrit pas de bac à sable pour l'API Marketing : nous travaillons sur une audience de test avant de toucher la liste réelle.

Que remontent les webhooks d'audience, et comment les vérifier ?

Les webhooks Mailchimp se paramètrent audience par audience, dans l'interface ou par l'API, en cochant les types d'événements voulus : inscriptions, désinscriptions, changements d'adresse, envoi de campagnes. Le corps arrive encodé comme un formulaire, avec un type, une date (fired_at) et les données du contact.

• Signature : un HMAC-SHA256 calculé sur l'horodatage et le corps brut arrive dans l'en-tête X-Mailchimp-Signature. Le connecteur le recalcule, compare en temps constant et rejette tout message de plus de 5 minutes.
• Secret de signature : affiché une seule fois ; perdu, il oblige à supprimer et recréer le webhook. Il rejoint donc le coffre de secrets dès sa création.
• Délai : une adresse muette pendant 10 secondes voit la requête annulée, puis relancée à intervalles croissants pendant 75 minutes ; Mailchimp peut ensuite désactiver le webhook.

Avec 75 minutes de relance, une maintenance de serveur un peu longue suffit à perdre des désinscriptions. Une relecture quotidienne des statuts par l'API ferme ce risque.

Quatre synchronisations Mailchimp rencontrées en PME

1. Du CRM vers l'audience. Un commercial crée un client et coche la case de consentement. Le connecteur crée le membre, remplit les champs de fusion (prénom, société, ville) et pose des tags (« client », « distributeur », région). Une fiche modifiée met à jour le membre au lieu d'en créer un second.
2. De l'audience vers le CRM. Un contact se désinscrit d'une newsletter ; le webhook signé arrive et la fiche du CRM passe à « ne plus solliciter par e-mail », ce qui prévient le commercial qui préparait une relance.
3. La première campagne d'un négociant. Une entreprise de négoce veut écrire à 15 000 clients issus de son ERP. Le connecteur écarte les adresses sans consentement, envoie le reste par lots, contrôle chaque résultat, puis seulement la campagne part.
4. Les e-mails de commande. Le logiciel de commandes déclenche les confirmations par Mailchimp Transactional ; les webhooks d'activité signalent ouvertures et clics, utiles pour savoir si un avis d'expédition a été vu.

Ces flux s'inscrivent dans une démarche plus large pour éliminer les doubles saisies entre logiciels.

Consentement et Transactional : deux points qui changent le projet

Le consentement voyage avec le contact. La CNIL rappelle que la prospection par e-mail vers des particuliers suppose leur accord préalable par une action positive, sauf pour des clients sollicités sur des produits analogues, et que chaque message permet de se désinscrire simplement ; vers des professionnels, information et droit d'opposition suffisent si le message concerne leur métier.

Mailchimp teste des points d'accès « Audiences » (bêta) qui séparent le contact de ses canaux e-mail et SMS et ajoutent un champ marketing_consent (denied, unknown, consented, confirmed) ; confirmed sert à importer des contacts dont l'accord a déjà été vérifié ailleurs. Mailchimp réserve cette bêta à l'évaluation : en production, nous restons sur la ressource Lists et conservons la preuve du consentement dans votre logiciel.

Côté envois transactionnels, la page de tarifs de Mailchimp indique que Transactional est un module des plans Standard et Premium, pas du plan Essentials, facturé par blocs de 25 000 e-mails : 20 dollars le bloc jusqu'à 20 blocs par mois, dégressif au-delà, sans report des e-mails non utilisés (tarif public relevé en octobre 2026). Les nouveaux utilisateurs peuvent envoyer 500 e-mails gratuits vers leur domaine vérifié. Si vos campagnes ne justifient pas un plan Standard, un service comme Brevo mérite la comparaison.

Intégration native, automatisation ou connecteur dédié ?

Première vérification : votre CRM ou votre boutique propose peut-être déjà une intégration Mailchimp, parfois référencée sur la Mailchimp Marketplace. Si elle couvre le besoin, aucun développement n'est utile.

Le sur-mesure se justifie aussi quand la segmentation vient de l'ERP (famille d'articles achetée, encours, commercial attitré) et change souvent.

La méthode et les livrables de YMHB Web

Le cadrage fixe d'abord la carte des données : base qui fait foi pour l'adresse e-mail, gestion du consentement, audiences et tags. Le chiffrage suit. Le connecteur est développé sur une audience de test, la recette rejoue les cas difficiles (adresse modifiée des deux côtés, désinscription pendant une reprise, webhook en retard), puis il passe sur l'audience réelle.

• un utilisateur d'intégration et sa clé d'API dans votre compte Mailchimp, jamais dans un compte à nous ;
• le code du connecteur, documenté et déposé dans votre dépôt, en technologies standard comme Node.js et PostgreSQL ;
• un journal de chaque appel et de chaque webhook reçu, avec le résultat de la vérification de signature ;
• une alerte quand un lot revient en erreur ou quand les webhooks se taisent anormalement.

Le cadre général de ces projets figure sur notre page API et intégrations.