Mailchimp: setup API key per integrazioni
La Mailchimp API permette di automatizzare gestione contatti, campagne, segmenti, automation da codice esterno. La API key e la chiave di accesso. Vediamo come crearla, conservarla e usarla in sicurezza.
Cosa puoi fare con l'API
Aggiungere/aggiornare contatti programmaticamente. Creare e inviare campagne. Sincronizzare audience con il tuo CRM. Estrarre report e statistiche. Gestire tag, segmenti, gruppi. Triggerare automation. Integrare con e-commerce, CMS, app mobile. La API REST e ben documentata e supporta tutti i piani Mailchimp.
Generare la API key
Accedi a Mailchimp, vai su Account & billing > Extras > API keys > Create A Key. Assegna un nome descrittivo (es. backend-shop-prod) per identificarla. Mailchimp mostra la key una sola volta: salvala subito in un password manager o vault aziendale.
Procedura passo-passo
- Genera API key dedicata per ogni integrazione (granular access).
- Salva la key in variabile ambiente (mai in repository).
- Identifica il data center: lo trovi nella URL Mailchimp (es. us21.admin.mailchimp.com > us21).
- Base URL API: https://[dc].api.mailchimp.com/3.0/.
- Autenticazione: header Authorization: apikey [API_KEY].
- Testa con una chiamata GET /ping (deve restituire {"health_status":"Everything's Chimpy!"}).
- Implementa rate limiting client side (Mailchimp limita a 10 chiamate parallele).
- Gestisci 429 Too Many Requests con backoff esponenziale.
- Logga ogni chiamata e ogni errore.
- Ruota la key periodicamente (ogni 6-12 mesi).
Esempi endpoint utili
POST /lists/{list_id}/members per aggiungere contatto. PATCH /lists/{list_id}/members/{hash} per aggiornare. POST /campaigns per creare campagna. GET /reports/{campaign_id} per statistiche. PUT /lists/{list_id}/members/{hash}/tags per aggiungere tag.
Security best practice
Mai committare la key in Git (usa .env + .gitignore). Non incollarla in chat o Slack: usa secret manager (HashiCorp Vault, AWS Secrets Manager, GitHub Actions Secrets). Usa key separate per dev/staging/prod. Se compromessa, rigenera subito e disattiva la vecchia. Per accesso utenti multipli, usa OAuth (Mailchimp lo supporta) anziche key condivise.
Errori comuni e come risolverli
- API key in repository pubblico: revoca subito e investiga uso non autorizzato.
- Data center sbagliato: ogni key e legata a un dc, non usare key di account A su URL di account B.
- Rate limit ignorato: implementa retry con backoff.
- Niente versioning: usa sempre /3.0/ esplicito (futuro proof).
- SHA dell'email errato: Mailchimp identifica contatto con MD5 lowercase dell'email.
Domande frequenti
D: La API key e gratis?
R: Si, inclusa in tutti i piani Mailchimp.
D: Esistono SDK ufficiali?
R: Si: Node, PHP, Python, Ruby, .NET, Java.
D: Posso limitare i permessi della key?
R: Solo con OAuth scope (per app pubblicate). La standard API key e full access.
Hai bisogno di aiuto?
Se vuoi delegare l'email marketing al team di G Tech Group, scrivici tramite il modulo di contatto. Ti aiutiamo con configurazione SMTP, migrazioni, automation e reportistica.