Inviare email con Nodemailer

La libreria standard di Node.js non include un client SMTP integrato. Nodemailer colma questa lacuna gestendo la negoziazione TLS, il connection pooling, la codifica MIME e gli allegati per la posta in uscita.

Come si installa e configura Nodemailer?

Installalo da npm:

npm install nodemailer

Un trasporto contiene i dettagli della connessione SMTP. Lo punti a un host e una porta, poi passi le credenziali sotto auth:

import nodemailer from "nodemailer";

const transporter = nodemailer.createTransport({
  host: "smtp.example.com",
  port: 587,
  secure: false, // true for port 465, false for 587 (STARTTLS)
  auth: {
    user: process.env.SMTP_USER,
    pass: process.env.SMTP_PASS,
  },
});

La porta 587 con secure: false usa STARTTLS, che aggiorna la connessione a TLS dopo l'handshake. La porta 465 richiede secure: true. Tieni username e password in variabili d'ambiente, mai nel codice sorgente.

Come si invia un messaggio?

Chiama sendMail con l'envelope e il contenuto. Restituisce una promise, quindi racchiudilo in async/await con un try/catch così un invio fallito non blocca il processo:

async function main() {
  try {
    const info = await transporter.sendMail({
      from: '"Your App" <you@yourdomain.com>',
      to: "recipient@example.org",
      subject: "Your receipt",
      text: "Thanks for your order. This is the plain-text version.",
      html: "<p>Thanks for your order.</p>",
    });
    console.log("Sent:", info.messageId);
  } catch (err) {
    console.error("Send failed:", err);
  }
}

main();

Invia sempre sia text che html. Alcuni client mostrano la parte in testo semplice, e un messaggio senza alternativa testuale tende a ottenere un punteggio peggiore dai filtri antispam.

Come si aggiungono gli allegati?

Passa un array attachments. Ogni elemento può leggere da un percorso, un buffer o uno stream:

await transporter.sendMail({
  from: "you@yourdomain.com",
  to: "recipient@example.org",
  subject: "Your invoice",
  text: "Invoice attached.",
  attachments: [
    {
      filename: "invoice.pdf",
      path: "./invoices/invoice-1042.pdf",
    },
    {
      filename: "note.txt",
      content: "Generated at runtime, no file needed.",
    },
  ],
});

Come si testa senza inviare email reali?

Nodemailer include Ethereal, un servizio SMTP fittizio che cattura i messaggi invece di consegnarli. Ottieni un URL di anteprima per ogni invio, ideale per lo sviluppo locale:

const testAccount = await nodemailer.createTestAccount();

const transporter = nodemailer.createTransport({
  host: "smtp.ethereal.email",
  port: 587,
  secure: false,
  auth: {
    user: testAccount.user,
    pass: testAccount.pass,
  },
});

const info = await transporter.sendMail({
  from: "you@yourdomain.com",
  to: "test@example.org",
  subject: "Preview only",
  text: "This never leaves Ethereal.",
});

console.log("Preview:", nodemailer.getTestMessageUrl(info));

Ethereal serve a ispezionare ciò che hai costruito. Non ti dice nulla sul fatto che una casella di posta reale accetterebbe il messaggio.

Invialo con Bird

SMTP funziona, ma usarlo in produzione significa gestire un mail server (o affittarne uno), scaldare gli IP e controllare la reputazione da soli. Un HTTP API si occupa di tutto questo. Non c'è nessun socket SMTP da tenere aperto e il provider gestisce l'infrastruttura di deliverability. Con l'Bird email API lo stesso invio è una singola chiamata:

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

const { data, error } = await bird.email
  .send({
    from: "onboarding@messagebird.dev",
    to: ["delivered@messagebird.dev"],
    subject: "Hello from Node",
    html: "<p>It works.</p>",
  })
  .safe();

Il mittente onboarding@messagebird.dev e l'indirizzo sandbox delivered@messagebird.dev ti permettono di verificare il collegamento prima di puntare a un destinatario reale. I runtime serverless come le funzioni Vercel e altri ambienti server JavaScript usano questa strada HTTPS quando non possono mantenere aperte connessioni SMTP.

FAQ

Nodemailer funziona nel browser?

No. Nodemailer è una libreria server-side e dipende dai moduli di rete di Node. I browser non possono aprire connessioni SMTP e inserire le credenziali nel codice client le esporrebbe. Invia da un backend.

Perché inviare sia testo che HTML?

Un messaggio multipart permette a ogni client di scegliere la parte che può renderizzare, e l'alternativa in testo semplice migliora la lettura del messaggio da parte dei filtri antispam. Omettere text è una causa frequente di email che finiscono nello spam.

Meglio usare SMTP o un HTTP API?

SMTP va bene per volumi bassi e strumenti interni. Per l'invio in produzione su larga scala, un HTTP API elimina il server che altrimenti dovresti gestire e integra la gestione della deliverability. Molti team usano Nodemailer in sviluppo e un API in produzione.

Nodemailer è un'ottima scelta per parlare SMTP da Node. Quando preferisci non gestire il mail server dietro di esso, leggi la guida all'invio di email per vedere l'alternativa API dall'inizio alla fine.