Breve guida per implementare le API di Mailchimp in Node.js

Mailchimp è una nota piattaforma per la creazione e gestione semplificata di newsletter, ampiamente diffusa sia per la convenienza dei suoi piani di abbonamento che per la semplicità di utilizzo anche da parte di coloro che non possiedono avanzate competenze tecniche.

Oltre alla possibilità di interagire lato front con tale piattaforma esiste un’ampia documentazione API a disposizione dei developers per l’integrazione e la gestione delle sottoscrizioni da server.

Immaginiamo di volere gestire l’iscrizione alla newsletter in fase di registrazione di un utente. Con questa breve guida vedremo come connettere il nostro server ai servizi di Mailchimp e come aggiungere nuovi utenti ad una mailing list. Per farlo useremo:

1. node.js
2. express
3. axios per gestire le chiamate agli endpoints di Mailchimp

CREAZIONE DEL SERVER

Innanzitutto creiamo la nostra applicazione lanciando da terminale i comandi:

$ npm init // crea il package.json del nostro nuovo progetto
$ npm install --save express body-parser axios // installa i pacchetti necessari
$ touch server.js // crea un file vuoto nella root

Apriamo server.js e impostiamo il nostro server:

const express = require('express');
const bodyParser = require('body-parser');
const app = express();
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({extended: true}));
app.get('/', function (req, res) {
  res.send('Hello World!');
});
app.listen(3000, function () {
  console.log('Server up and listening on port 3000!');
});

Lanciamo da terminale il comando:

$ node server.js
Server up and listening on port 3000!

Digitando http://localhost:3000/ nella barra degli indirizzi del nostro browser avremo accesso al nostro primo, semplice, endpoint che ci restituirà il messaggio ‘Hello World!’.

CREAZIONE DELL’ENDPOINT PER LA REGISTRAZIONE UTENTE E INTEGRAZIONE DI MAILCHIMP

Aggiungiamo al nostro server un nuovo endpoint per la gestione della registrazione degli utenti:

app.post('/signup', function (req, res) {
  // all'interno della callback predisponiamo il salvataggio dei
  // dati utente nel nostro database
  res.send('Nuovo utente registrato!');
});

Per potere implementare la chiamata a Mailchimp avremo bisogno di alcuni dati identificativi, che potremo ottenere accedendo al nostro account:

1. API key: basterà cliccare sul proprio profilo (in alto a destra), selezionare Extras e API Keys. Se non vi sono chiavi disponibili sarà possibile crearne una nuova.

2. Server Instance: corrisponde agli ultimi caratteri dell’API Key, dopo us-.

3. Unique List Id: per ottenere l’id occorrerà cliccare su Audience nel Menu in alto, selezionare la lista alla quale aggiungere i nostri utenti (l’abbonamento gratuito consente la creazione di un’unica lista per un massimo di 2000 iscrizioni ad essa), cliccare Manage Audience e Settings, e prelevare l’id nel campo in fondo alla pagina “Unique id for list …”

Acquisite le informazioni necessarie, possiamo finalmente integrare Mailchimp nel nostro server. Creiamo un metodo che ci consenta di effettuare la chiamata all’endpoint di nostro interesse, preferibilmente in un file .js dedicato che richiameremo in un secondo momento come modulo all’interno del nostro server:

// newsletter.js
const axios = require('axios');
// dichiariamo qui, per comodità, le costanti necessarie alla 
// chiamata. 
// N.B.: è sempre consigliabile raccogliere i dati sensibili
// come variabili d'ambiente in un file .env
const mailchimpInstance = '8';
const listId = '<your list ID>';
const mailchimpApiKey = '<your API Key>';
const basePath = `https://us${mailchimpInstance}.api.mailchimp.com/3.0/lists`;
async function mailchimpListCall(listId, HTTP = 'GET', body = {}) {
  return new Promise(async function (resolve, reject) {
    try {
      const apiKey = new Buffer(`anystring:${mailchimpApiKey}`).toString('base64');
      let url = `${basePath}/${listId}/members/`;
      const config = {
        headers: {
          'Authorization': 'Basic ' + apiKey
        }
      };
      let response;
      if (HTTP == 'POST') {
        response = await axios.post(url, body, config);
      } else {
        response = await axios.get(url, config);
      }
      resolve(response.data);
    } catch (error) {
      resolve(console.log(error));
    }
  });
};

Il metodo appena creato ci consente al momento di effettuare due tipologie di chiamate: una GET, per richiedere al server tutti i membri iscritti alla nostra lista e una POST, per finalizzare una nuova sottoscrizione. Occupiamoci di quest’ultimo caso creando all’interno dello stesso file un nuovo metodo esportabile:

// newsletter.js
exports.mailchimpSignup = async function (user) {
  return new Promise(async function (resolve, reject) {
    try {
      const body = {
        email_address: user.email,
        'status': 'subscribed',
        merge_fields: {
          FNAME: user.firstName,
          LNAME: user.lastName
        }
      }
      const subscribe = await mailchimpListCall(listId, HTTP = 'POST', body);
      return resolve(console.log(`${user.email} iscritto alla newsletter!`));
    } catch (error) {
        reject(error);
    };
  });
};

Il nuovo metodo è pronto per essere richiamato nel nostro endpoint signup:

const mailchimp = require('./newsletter');
app.post('/signup', async function (req, res) {
  const newUser = {
    username: req.body.username,
    email: req.body.email,
    firstName: req.body.firstName,
    lastName: req.body.lastName
  };
  await mailchimp.mailchimpSignup(newUser);
  res.send('Nuovo utente registrato!');
});

Il file server.js aggiornato risulterà così:

const express = require('express');
const bodyParser = require('body-parser');
const mailchimp = require('./newsletter');
const app = express();
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: true }));
app.get('/', function (req, res) {
  res.send('Hello World!');
});
app.post('/signup', async function (req, res) {
  // all'interno della callback inseriamo il salvataggio dei dati  
  // utente nel nostro database
  const newUser = {
    username: req.body.username,
    email: req.body.email,
    firstName: req.body.firstName,
    lastName: req.body.lastName
  };
  await mailchimp.mailchimpSignup(newUser);
  res.send('Nuovo utente registrato!');
});
app.listen(3000, function () {
  console.log('Server up and listening on port 3000!');
});

Non ci resta che verificare che la nostra funzione svolga il suo compito!

Simuliamo con Postman una nuova registrazione utente:

E controlliamo l’avvenuta sottoscrizione sul nostro account Mailchimp:

Tutto è andato a buon fine!

Lo stesso metodo consente di gestire la cancellazione o la modifica delle sottoscrizioni alla mailing list, offrendo la possibilità ai nostri utenti di controllare l’iscrizione direttamente dal profilo, magari mediante un semplice flag (de)selezionabile, ma questa è un’altra storia…