Node.JS: inviare e-mail con Nodemailer

Il runtime JavaScript Node.JS permette di inviare messaggi di posta elettronica tramite il modulo Nodemailer. Quest'ultimo è disponibile grazie ad un progetto che ormai ha quasi raggiunto i 15 anni di vita e rappresenta da tempo la prima scelta per gli sviluppatori. Grazie ad esso possiamo spedire messaggi tramite applicazioni Web partendo da caselle di posta fornite da piattaforme di terze parti, come per esempio GMail, così come da account legati ad un server SMTP personalizzato. Prima di passare al codice analizziamo brevemente le caratteristiche principali di Nodemailer.

Le funzionalità di Nodemailer

Nodemailer è innanzitutto una libreria standalone, questo significa che per il suo utilizzo non è necessaria alcuna dipendenza. Tutto ciò che serve è un ambiente di sviluppo basato su Node.JS.

Uno dei suoi principali vantaggi riguarda il fatto che essa garantisce il supporto per Unicode, lo standard di codifica dei caratteri che fornisce un sistema unificato per rappresentare testo e simboli in quasi tutte le lingue scritte del mondo. Si può quindi utilizzare qualsiasi carattere nei messaggi e persino gli emoji. Il contenuto delle e-mail può essere inoltre sia in testo semplice che in HTML, senza limiti di formato.

È possibile includere degli allegati nei messaggi così come inserire delle immagini all'interno dei contenuti HTML e non manca nemmeno il supporto per l'uso in ambiente Windows dopo l'installazione via npm:

npm install nodemailer

Chiaramente lo stesso comando può essere lanciato da una distribuzione Linux o dalla propria versione di macOS.

Per quanto riguarda la sicurezza e la deliverability, Nodemailer permette di utilizzare i protocolli crittografici TLS/STARTTLS, si possono firmare i messaggi tramite chiavi DKIM ed è possibile sfruttare OAuth2 per autorizzare le applicazioni a memorizzare i token di autenticazione al posto delle credenziali di login.

Il modulo supporta diversi metodi di trasporto. Quello di default è SMTP ma sono disponibili nativamente anche sendmail, SES (il Simple Email Service di AWS) e stream (solo per i messaggi di ritorno). Si può poi effettuare l'integrazione via API con Mailtrap o Mailgun.

Gli sviluppatori possono estendere le funzionalità di base tramite plugin ed è possibile utilizzare dei proxy per la connessione ai server SMTP. Il supporto per i proxy HTTP è stato implementato nativamente, quello ai SOCKS (Socket Secure) proxy può essere abilitato tramite il modulo socks di Node.JS.

L'unico requisito minimo previsto per l'utilizzo della libreria è Node.JS in versione 6 o release successiva. Se però si vuole utilizzare la sintassi async/await per lavorare con le promise si deve disporre come minino di Node.JS 8.

Inviare e-mail con Node.JS e Nodemailer

Per spedire un messaggio di posta elettronica con Nodemailer è necessario disporre di un "trasportatore". Dove con questo termine viene identificato un oggetto che è in grado di inviare una e-mail. Tipicamente un trasportatore è associato ad un meccanismo di trasporto, come SMTP, ed opera il delivery tramite il metodo sendMail().

I parametri per l'invio

Passando al codice, la prima fase per la costruzione di un'applicazione completa richiede la definizione di due costanti. Con la prima si effettua la chiamata alla libreria, con la seconda viene introdotto il trasportatore tramite il metodo createTransport():

const nodemailer = require("nodemailer");
const transporter = nodemailer.createTransport({
  host: "smtp.lamiaemail.cloud",
  port: 587,
  secure: false,
  auth: {
    user: "clancy.winchester@lamiaemail.name",
    pass: "R4lFuCCi089",
  },
});

Il metodo permette il passaggio dei parametri che consentono di autenticarsi al servizio di posta in uscita. Sono in pratica gli stessi che vengono utilizzati per la configurazione di un client di posta, quindi: server SMTP, porta SMTP, tipologia di connessione e credenziali di autenticazione (username e password). Per quanto riguarda la porta, il valore di riferimento è 587 se l'opzione secure è impostata su false, mentre è 465 se secure è impostata su true. Con true verrà utilizzato TLS durante la connessione al server. Con false TLS viene utilizzato se il server supporta STARTTLS. Nella maggior parte dei casi si deve impostare secure su true se ci si connette alla porta 465. Per le porte 587 o 25 si deve invece mantenere secure su false.

Invio del messaggio

La fase successiva è quella dell'invio del messaggio tramite il trasportatore e il suo metodo di trasporto. Anche in questo caso tutto si basa sulla definizione di una costante.

async function main() {
  const info = await transporter.sendMail({
    from: '"Clancy Winchester" ',
    to: "montgomery.burns@lamiaemail.biz, waylon.smithers@lamiaemail.gift",
    subject: "Buongiorno",
    text: "Dove sono Lou ed Eddie?",
    html: "<strong>Dove sono Lou ed Eddie?</strong>",
  });
  console.log("Posta inviata: %s", info.messageId);
}
main().catch(console.error);

In questa parte del codice main() è presentata come async e utilizza await per attendere il completamento dell'invio dell'e-mail prima di continuare l'esecuzione del codice. Si ha quindi un wrapper che introduce una costante con cui il metodo sendMail(), quello deputato appunto all'invio del messaggio, accetta i parametri relativi all'e-mail e al suo contenuto. Nel caso specifico del nostro esempio vengono specificati quelli relativi al mittente (from), ai destinatari (to) che se sono più di uno devono essere separati con la virgola, all'oggetto (subject), al contenuto in formato testuale e al suo corrispondente in HTML.

L'esito dell'invio viene infine registrato tramite console.log() che usato in questo modo permette di verificare il flusso di esecuzione del codice, mentre console.error() evidenzierà eventuali messaggi di errore. main() è infatti incapsulata in un blocco try/catch per gestire le eccezioni che potrebbero verificarsi durante l'invio del messaggio.

Gestione degli allegati

Questa breve trattazione non sarebbe completa se non introducessimo anche il discorso riguardante l'invio di allegati con Nodemailer. In ogni caso parliamo di un'operazione abbastanza semplice, se per esempio volessimo aggiungere un allegato al codice proposto in precedenza dovremmo procedere in questo modo:

...
html: "<strong>Dove sono Lou ed Eddie?</strong>",
attachments: [
        {
            filename: 'foto_Lou_Eddie.jpg',
            path: '../immagini/foto_Lou_Eddie.jpg'
        }
    ]
...

In pratica tutto è stato risolto con l'introduzione di un nuovo parametro, attachments, contenente sia il nome (filename) del file da allegare che il suo percorso (path) all'interno del sistema, cioè quello della directory che lo contiene. L'utente non dovrà fare altro che sostituire i riferimenti utilizzati nell'esempio con il nome del file che desidera utilizzare e il suo percorso.

Conclusioni

Nodemailer è un modulo di Node.JS che consente di inviare e-mail direttamente da una Web application. Gli esempi presentati mostrano come sia semplice spedire un messaggio dal proprio account di posta elettronica, anche in formato HTML e a più destinatari, e allegare ad esso un file.