Wysyłanie e-maili za pomocą Nodemailera

Biblioteka standardowa Node.js nie zawiera wbudowanego klienta SMTP. Nodemailer uzupełnia tę lukę: obsługuje negocjację TLS, pulę połączeń, kodowanie MIME i załączniki w poczcie wychodzącej.

Jak zainstalować i skonfigurować Nodemailera?

Zainstaluj go z npm:

npm install nodemailer

Transport przechowuje dane połączenia SMTP. Wskazujesz hosta i port, a potem przekazujesz dane uwierzytelniające w 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,
  },
});

Port 587 z secure: false używa STARTTLS, który po uzgodnieniu połączenia przełącza je na TLS. Port 465 wymaga secure: true. Przechowuj nazwę użytkownika i hasło w zmiennych środowiskowych, nigdy w kodzie źródłowym.

Jak wysłać wiadomość?

Wywołaj sendMail z kopertą i treścią. Zwraca promise, więc opakuj wywołanie w async/await z blokiem try/catch, żeby nieudane wysłanie nie zawiesiło procesu:

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();

Zawsze wysyłaj zarówno text, jak i html. Niektóre klienty renderują wersję tekstową, a wiadomość bez alternatywy tekstowej jest gorzej oceniana przez filtry antyspamowe.

Jak dodać załączniki?

Przekaż tablicę attachments. Każdy wpis może czytać ze ścieżki, bufora lub strumienia:

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.",
    },
  ],
});

Jak testować bez wysyłania prawdziwych wiadomości?

Nodemailer zawiera Ethereal, fikcyjną usługę SMTP, która przechwytuje wiadomości zamiast je dostarczać. Dla każdego wysłania dostajesz URL podglądu, co jest idealne przy lokalnym developmencie:

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 służy do sprawdzania tego, co zbudowałeś. Nie powie ci, czy prawdziwa skrzynka odbiorcza zaakceptowałaby tę wiadomość.

Wyślij za pomocą Bird

SMTP działa, ale uruchomienie go w produkcji oznacza obsługę serwera pocztowego (lub wynajęcie takiego), rozgrzewanie adresów IP i samodzielne pilnowanie reputacji. HTTP API przejmuje to za ciebie. Nie ma gniazda SMTP do utrzymywania, a dostawca zarządza infrastrukturą dostarczalności. Z Bird e-mail API ta sama wysyłka to jedno wywołanie:

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();

Nadawca onboarding@messagebird.dev i adres sandboxowy delivered@messagebird.dev pozwalają potwierdzić poprawność konfiguracji, zanim wyślesz wiadomość do prawdziwego odbiorcy. Środowiska serverless, takie jak funkcje Vercel i inne serwerowe środowiska JavaScript, korzystają z tej ścieżki HTTPS, gdy nie mogą utrzymywać otwartych połączeń SMTP.

FAQ

Czy Nodemailer działa w przeglądarce?

Nie. Nodemailer to biblioteka serwerowa i zależy od modułów sieciowych Node. Przeglądarki nie mogą otwierać połączeń SMTP, a umieszczenie danych uwierzytelniających w kodzie klienckim ujawniłoby je. Wysyłaj z backendu.

Dlaczego wysyłać zarówno tekst, jak i HTML?

Wiadomość multipart pozwala każdemu klientowi wybrać część, którą potrafi wyrenderować, a alternatywa tekstowa poprawia ocenę wiadomości przez filtry antyspamowe. Pominięcie text to częsta przyczyna trafiania e-maili do spamu.

Wybrać SMTP czy HTTP API?

SMTP sprawdza się przy małym wolumenie i narzędziach wewnętrznych. Do wysyłki produkcyjnej na dużą skalę HTTP API eliminuje serwer, który w przeciwnym razie musiałbyś obsługiwać, i zapewnia obsługę dostarczalności. Wiele zespołów używa Nodemailera w developmencie, a API w produkcji.

Nodemailer to solidny wybór do komunikacji SMTP z poziomu Node. Jeśli wolisz nie prowadzić serwera pocztowego za nim, przeczytaj przewodnik po wysyłaniu e-maili, żeby zobaczyć alternatywę API od początku do końca.