Nodemailer для JavaScript (Node.js): полное руководство с примерами

Что такое Nodemailer и зачем он нужен?

Nodemailer — это модуль для Node.js, который позволяет отправлять электронные письма из вашего JavaScript-приложения. Это одна из самых популярных и стабильных библиотек в экосистеме Node.js для работы с email. Она предоставляет простой, но мощный API для создания и отправки сообщений через различные транспорты (SMTP, Sendmail, Amazon SES и другие).

Зачем нужен Nodemailer?

• Автоматизация уведомлений: Отправка писем о регистрации, сбросе пароля, подтверждении заказа и других событиях.
• Массовые рассылки: Создание новостных писем, маркетинговых кампаний (с осторожностью, чтобы не попасть в спам).
• Обратная связь: Отправка сообщений из контактных форм на сайте.
• Мониторинг и логи: Уведомление администратора о критических ошибках в приложении.
• Гибкость: Поддержка HTML-шаблонов, вложений, встроенных изображений и различных кодировок.

Nodemailer абстрагирует сложность работы с протоколами email (SMTP, POP3, IMAP) и предоставляет единый, понятный интерфейс.

Установка Nodemailer

Установка Nodemailer осуществляется через менеджер пакетов npm (Node Package Manager). Убедитесь, что у вас установлен Node.js (версия 12 или выше).

Откройте терминал в корневой папке вашего проекта и выполните команду:

npm install nodemailer

После завершения установки вы можете импортировать библиотеку в свой код:

const nodemailer = require('nodemailer');

Для проектов, использующих ES-модули (с "type": "module" в package.json), используйте импорт:

import nodemailer from 'nodemailer';

Быстрый старт: отправка первого письма

Самый простой способ отправить письмо — использовать SMTP-сервер. В этом примере мы будем использовать сервис Gmail. Важно: Для работы с Gmail вам потребуется создать "пароль приложения" (App Password) или использовать OAuth2. Обычный пароль от аккаунта не подойдет из-за настроек безопасности Google.

const nodemailer = require('nodemailer');

// 1. Создаем транспорт (способ отправки)
const transporter = nodemailer.createTransport({
    service: 'gmail',
    auth: {
        user: 'your-email@gmail.com', // Ваш email
        pass: 'your-app-password'     // Пароль приложения
    }
});

// 2. Настраиваем письмо
const mailOptions = {
    from: 'your-email@gmail.com',
    to: 'recipient@example.com',
    subject: 'Привет из Nodemailer!',
    text: 'Это тестовое письмо, отправленное с помощью Nodemailer.'
};

// 3. Отправляем письмо
transporter.sendMail(mailOptions, (error, info) => {
    if (error) {
        return console.log('Ошибка:', error);
    }
    console.log('Письмо отправлено:', info.messageId);
    console.log('URL для просмотра:', nodemailer.getTestMessageUrl(info));
});

Этот код создает транспорт для Gmail, формирует простое текстовое письмо и отправляет его. В случае успеха вы увидите ID сообщения в консоли.

Основные методы и функции Nodemailer

Рассмотрим подробно ключевые методы, которые предоставляет библиотека.

1. nodemailer.createTransport(options)

Что делает: Создает объект транспорта — это основная конфигурация, которая определяет, как именно будет отправлено письмо (через какой сервер и с какими учетными данными).

Параметры:

• options (Object): Объект конфигурации. Основные свойства:
  • host (String): Адрес SMTP-сервера (например, 'smtp.gmail.com').
  • port (Number): Порт сервера (обычно 465 для SSL, 587 для TLS).
  • secure (Boolean): true для порта 465, false для остальных.
  • auth (Object): Объект с учетными данными (user и pass).
  • service (String): Имя популярного сервиса ('gmail', 'yandex', 'mail.ru' и т.д.). При его указании host и port можно не задавать.

Пример:

const transporter = nodemailer.createTransport({
    host: 'smtp.yandex.ru',
    port: 465,
    secure: true,
    auth: {
        user: 'my@yandex.ru',
        pass: 'my_password'
    }
});

2. transporter.sendMail(mailOptions, callback)

Что делает: Основной метод для отправки письма. Принимает объект с настройками письма и функцию обратного вызова.

Параметры:

• mailOptions (Object): Объект, описывающий письмо. Ключевые свойства:
  • from (String): Отправитель (email или "Имя ").
  • to (String | Array): Получатель(и).
  • cc (String | Array): Копия.
  • bcc (String | Array): Скрытая копия.
  • subject (String): Тема письма.
  • text (String): Текстовая версия письма.
  • html (String): HTML-версия письма.
  • attachments (Array): Массив объектов вложений.
• callback (Function): Функция, вызываемая после отправки. Принимает два аргумента: error и info.

Пример:

transporter.sendMail({
    from: '"Node.js Server" ',
    to: ['user1@example.com', 'user2@example.com'],
    subject: 'Важное уведомление',
    html: '<h1>Привет!</h1><p>Это HTML-письмо.</p>'
}, (err, info) => {
    if (err) console.error(err);
    else console.log('Успешно:', info.messageId);
});

3. transporter.sendMail(mailOptions) (Promise)

Что делает: Тот же метод sendMail, но возвращает Promise, что позволяет использовать async/await.

Параметры: Те же, что и в callback-версии.

Пример:

async function sendEmail() {
    try {
        let info = await transporter.sendMail({
            from: 'sender@example.com',
            to: 'recipient@example.com',
            subject: 'Тест с async/await',
            text: 'Это письмо отправлено асинхронно.'
        });
        console.log('Отправлено:', info.messageId);
    } catch (error) {
        console.error('Ошибка:', error);
    }
}
sendEmail();

4. transporter.verify()

Что делает: Проверяет, может ли транспорт успешно соединиться с SMTP-сервером и аутентифицироваться. Полезно для тестирования конфигурации при запуске приложения.

Параметры: Нет.

Пример:

transporter.verify()
    .then(() => console.log('Соединение с сервером установлено'))
    .catch(err => console.error('Ошибка соединения:', err));

5. nodemailer.createTestAccount()

Что делает: Создает временный тестовый аккаунт на сервисе Ethereal Email. Это идеальный способ тестировать отправку писем без риска заспамить реальных пользователей. Письма не уходят в реальный мир, а доступны для просмотра в веб-интерфейсе Ethereal.

Параметры: Нет.

Пример:

async function testSend() {
    let testAccount = await nodemailer.createTestAccount();
    
    let transporter = nodemailer.createTransport({
        host: 'smtp.ethereal.email',
        port: 587,
        secure: false,
        auth: {
            user: testAccount.user,
            pass: testAccount.pass
        }
    });

    let info = await transporter.sendMail({
        from: '"Тестер" ',
        to: 'anyone@example.com',
        subject: 'Тестовое письмо',
        text: 'Это письмо никуда не уйдет.'
    });

    console.log('URL для просмотра письма:', nodemailer.getTestMessageUrl(info));
}
testSend();

6. nodemailer.getTestMessageUrl(info)

Что делает: Принимает объект info, возвращенный методом sendMail при использовании тестового аккаунта Ethereal, и возвращает URL, по которому можно просмотреть отправленное письмо в веб-интерфейсе.

Параметры:

• info (Object): Объект, возвращенный sendMail.

Пример: Смотрите пример выше (nodemailer.createTestAccount).

7. transporter.close()

Что делает: Закрывает соединение с SMTP-сервером. Рекомендуется вызывать, когда транспорт больше не нужен, чтобы освободить ресурсы.

Параметры: Нет.

Пример:

// После отправки всех писем
transporter.close();
console.log('Соединение закрыто');

8. transporter.use(step, plugin)

Что делает: Позволяет подключать плагины (middleware) к определенным этапам обработки письма. Например, можно использовать плагин для шифрования PGP или для добавления подписи DKIM.

Параметры:

• step (String): Этап, на котором будет вызван плагин. Возможные значения: 'compile' (перед сборкой письма), 'stream' (перед отправкой потока).
• plugin (Function): Функция-плагин.

Пример (упрощенный):

transporter.use('compile', (mail, callback) => {
    // Модифицируем объект mail перед отправкой
    mail.message.html = mail.message.html + '<br><small>Добавлено плагином</small>';
    callback();
});

9. Работа с вложениями (attachments)

Что делает: Позволяет прикреплять к письму файлы. Вложения задаются в свойстве attachments объекта mailOptions.

Параметры (для каждого вложения):

• filename (String): Имя файла, которое увидит получатель.
• content (String | Buffer | Stream): Содержимое файла.
• path (String): Путь к файлу на диске (альтернатива content

  Также в библиотеке

  Kotlin Multiplatform для Kotlin: полное руководство с примерами JSON обработка в Swift: Codable, JSONSerialization и практические примеры Valibot для TypeScript: полное руководство с примерами Authlib – аутентификация OAuth и OpenID Работа с Excel в C# (.NET): библиотеки EPPlus, ClosedXML и NPOI