« MC_OPTIN_ERROR » n’est pas un message qu’un visiteur doit jamais voir affiché tel quel après avoir saisi son adresse e-mail. Pourtant, c’est exactement ce qui apparaissait sur un premier essai d’intégration Mailchimp, faute d’avoir géré correctement les codes de retour de l’API. Ce bloc, une fois stabilisé, a fini par remplacer une iframe d’inscription générique peu compatible avec la charte graphique du site.
Contrairement à une intégration via widget embarqué, un appel direct à l’API Mailchimp donne un contrôle total sur les messages affichés à l’utilisateur, y compris dans le cas particulier — fréquent — d’une adresse déjà inscrite ou d’un désabonnement à réactiver.
Comprendre le double opt-in côté API
Le double opt-in signifie que l’abonné doit confirmer son inscription en cliquant sur un lien reçu par e-mail avant que son adresse ne devienne réellement active dans la liste. Côté API Mailchimp, cela se traduit simplement par le statut pending transmis lors de la création du contact, plutôt que subscribed :
{
"email_address": "visiteur@exemple.fr",
"status": "pending"
}
Mailchimp se charge alors automatiquement d’envoyer l’e-mail de confirmation ; aucun code supplémentaire n’est nécessaire côté WordPress pour cette étape précise.
La route REST côté serveur
La clé API Mailchimp et l’identifiant du datacenter (suffixe après le tiret dans la clé, par exemple us21) sont stockés en constantes, jamais exposés côté navigateur :
define( 'MAILCHIMP_API_KEY', 'abc123...-us21' );
define( 'MAILCHIMP_LIST_ID', '4f5g6h7i8j' );
function wpmoderne_inscrire_mailchimp( WP_REST_Request $request ) {
$email = sanitize_email( $request->get_param( 'email' ) );
if ( ! is_email( $email ) ) {
return new WP_Error( 'email_invalide', 'Adresse e-mail invalide.', array( 'status' => 400 ) );
}
list( , $datacenter ) = explode( '-', MAILCHIMP_API_KEY );
$url = "https://{$datacenter}.api.mailchimp.com/3.0/lists/" . MAILCHIMP_LIST_ID . '/members';
$reponse = wp_remote_post( $url, array(
'headers' => array(
'Authorization' => 'apikey ' . MAILCHIMP_API_KEY,
'Content-Type' => 'application/json',
),
'body' => wp_json_encode( array(
'email_address' => $email,
'status' => 'pending',
) ),
) );
return wpmoderne_traiter_reponse_mailchimp( $reponse, $email );
}
Gérer les cas particuliers de réponse
L’API Mailchimp retourne une erreur explicite (code HTTP 400, titre Member Exists) si l’adresse est déjà abonnée. Un traitement naïf renverrait un message d’échec générique, alors qu’un message adapté sert bien mieux l’utilisateur :
function wpmoderne_traiter_reponse_mailchimp( $reponse, $email ) {
$code = wp_remote_retrieve_response_code( $reponse );
$corps = json_decode( wp_remote_retrieve_body( $reponse ), true );
if ( 200 === $code || 200 === (int) $corps['status'] ?? 0 ) {
return array( 'message' => 'Vérifiez votre boîte mail pour confirmer votre inscription.' );
}
if ( isset( $corps['title'] ) && 'Member Exists' === $corps['title'] ) {
return array( 'message' => 'Cette adresse est déjà inscrite à la liste.' );
}
return new WP_Error( 'mailchimp_erreur', 'Une erreur est survenue, réessayez plus tard.', array( 'status' => 502 ) );
}
Le formulaire côté bloc
Le bloc lui-même reste simple : un champ e-mail, un bouton, et une zone de message qui affiche la réponse retournée par la route REST, sans rechargement de page. La liste des messages possibles est centralisée côté PHP, ce qui facilite une traduction future avec wp_set_script_translations si le site devient multilingue.
- Validation du format e-mail côté client, avant tout appel réseau, pour un retour immédiat.
- Un nonce WordPress vérifié côté serveur avant tout appel à l’API Mailchimp.
- Un délai d’affichage minimal du message de confirmation, pour éviter un effet de clignotement si la réponse arrive très vite.
Ce que cet article ne couvre pas
La création et l’envoi de campagnes email, une fois les abonnés collectés, se fait entièrement dans l’interface Mailchimp et ne concerne plus le bloc. Les automatisations (séquences de bienvenue, segmentation comportementale) suivent la même logique : elles démarrent une fois le contact confirmé, indépendamment de la façon dont il a été inscrit.
En résumé
Un appel API direct donne un contrôle bien plus fin sur l’expérience d’inscription qu’une iframe standard, en particulier sur la gestion des cas d’erreur qui, sans traitement dédié, se traduisent presque toujours par un message technique incompréhensible pour le visiteur. Le double opt-in, lui, ne demande qu’un seul paramètre bien positionné dans l’appel API.
