Отправка электронной почты

Перед началом

Прежде чем продолжить, убедитесь, что у вас есть базовые знания JavaScript и что вы уже знакомы с основами Netuno, пройдя пошаговое руководство, доступное в Академии.

Демонстрация отправки электронных писем

С Netuno очень просто отправлять электронные письма, в том числе с вложениями или изображениями, встроенными в само содержимое (полезно, например, для подписей).

Приложение, поставляемое с Netuno под названием demo (демонстрационное приложение), содержит множество примеров возможных реализаций кода на разных языках, включая демонстрацию отправки электронной почты через сервис mail-send, который находится в:

/apps/demo/server/services/samples/groovy/mail-send.groovy

/apps/demo/server/services/samples/javascript/mail-send.js

/apps/demo/server/services/samples/kotlin/mail-send.kts

/apps/demo/server/services/samples/python/mail-send.py

/apps/demo/server/services/samples/ruby/mail-send.rb

Настройка

Первым шагом будет настройка учётной записи SMTP, которую Netuno будет использовать для отправки электронной почты.

Для этого в разрабатываемом приложении перейдите к файлу конфигурации окружения. В этом примере мы будем использовать файл окружения разработки, расположенный по пути:

config/_development.json

Проверьте, нет ли уже настроек для SMTP; если их ещё нет, то в конце файла конфигурации (в формате JSON) добавьте параметры настройки SMTP:

{
    ...,
    "smtp": {
        "default": {
            "enabled": true,
            "host": "smtp.gmail.com",
            "port": 465,
            "ssl": true,
            "username": "*****@gmail.com",
            "password": "*****"
        }
    }
    ...
}

Если вы настраиваете Gmail, замените только звёздочки на свои учётные данные и включите SMTP-подключение в настройках своей учётной записи Gmail. В противном случае замените все параметры на параметры своей учётной записи SMTP.

После сохранения изменений достаточно перезапустить Netuno, чтобы изменения конфигурации вступили в силу. Это настройки по умолчанию для отправки электронной почты, как указывает имя default.

...
    "default": {
        ...
    }
...

Можно добавить больше учётных записей SMTP, но только одна может быть назначена по умолчанию.

Чтобы добавить больше учётных записей SMTP, просто повторите блок конфигурации SMTP по умолчанию и замените имя default на другое имя по вашему выбору, например:

{
    ...,
    "smtp": {
        "default": {
            "enabled": true,
            "host": "smtp.gmail.com",
            "port": 465, "ssl": true,
            "username": "*****@gmail.com",
            "password": "*****"
        },
        "test": {
            "enabled": true,
            "host": "smtp.gmail.com",
            "port": 465,
            "ssl": true,
            "username": "*****@gmail.com",
            "password": "*****"
        }
    }
    ...
}

Подобная конфигурация, как в примере выше, позволит использовать учётную запись default, когда она вызывается в коде следующим образом:

const smtp = _smtp.init()

А чтобы использовать конфигурацию test, достаточно добавить имя конфигурации как параметр в функцию _smtp.init() следующим образом:

const smtp = _smtp.init("test")

Если не добавить имя конфигурации как параметр, всегда будет использоваться учётная запись по умолчанию.

Подробный код

Давайте теперь внимательно разберём пример кода, который предоставляет Netuno. В данном случае это JavaScript, и он структурирован следующим образом:

Инициализация SMTP:

const smtp = _smtp.init()

Помните, что можно инициализировать с другой конфигурацией, например: _smtp.init("test")

Добавляя .to к переменной smtp, задаётся адрес получателя электронного письма; при нескольких получателях достаточно разделить их символом ‘;‘ или ‘,‘:

smtp.to = '*****@gmail.com'

Добавляя .from, задаётся адрес отправителя электронного письма:

smtp.from = '*****@gmail.com'

Добавляя .cc, задаются адреса получателей копии письма; при нескольких получателях копии достаточно разделить их символом ‘;‘ или ‘,‘:

smtp.cc = '*****@gmail.com'

То же самое относится к .bcc, где задаются получатели скрытой копии:

smtp.bcc = '*****@gmail.com'

Добавляя .subject, задаётся тема электронного письма:

smtp.subject = 'Тест Netuno'

Добавляя .text, задаётся содержимое в виде обычного текста:

smtp.text = 'Вы получили это письмо?'

Добавляя .html, задаётся содержимое письма в HTML:

smtp.html = `<div>
<img src="cid:logo" width="200" />
Вы получили это письмо?</p>
</div>`

Чтобы добавить изображение как вложение, добавляют (как показано выше) в HTML для изображений (img) в атрибуте src префикс cid: (Content ID), а сразу после него — cid, который задаётся при добавлении вложений с помощью функции attachment (как показано ниже).

Чтобы добавить прикреплённое изображение к письму, добавьте .attachment к переменной smtp следующим образом:

smtp.attachment(
    "logo.png", // Файл
    "image/png", // Формат файла
    _storage.filesystem("server", "samples/mail", "logo.png").file(), // Расположение файла
    "logo" // Имя переменной, заданной в "cid:logo"
)   

Обратите внимание, что cid (Content ID) нужен только для встраивания изображений, которые прикреплены к HTML-содержимому письма.

Чтобы добавить вложение без встраивания в HTML (например, документ), поступите следующим образом:

smtp.attachment(
    "doc.text",
    "text/plain",
    _storage.filesystem("server", "samples/mail", "doc.txt").file()
)   

Наконец, чтобы отправить письмо, достаточно вставить следующий код:

smtp.send()

Наконец, если всё настроено правильно, вы получите письмо, похожее на следующее:

отправка-писем1.png

Обратите внимание, что в зависимости от вашего почтового клиента письмо может отличаться от изображения выше.

Полный пример с шаблоном

Размещать HTML-содержимое посреди кода не очень элегантно, как показано выше:

smtp.html = `<div>
<img src="cid:logo" width="200" />
Вы получили это письмо?</p>
</div>`

Чтобы избежать этого и сохранить код более чистым и элегантным, HTML-содержимое следует импортировать как шаблон следующим образом:

smtp.html = _template.getOutput('email/contact', data)

В этом примере настройка SMTP в конфигурации приложения будет выглядеть так:

...
    "smtp": {
        "contact": {
            "enabled": true,
            "host": "МОЙ.СЕРВЕР.com",
            "port": 465,
            "ssl": true,
            "subjectPrefix": "Обратная связь с сайта - ",
            "from": "noreply@МОЙ.ДОМЕН.com",
            "to": "info@МОЙ.ДОМЕН.com",
            "username": "noreply@МОЙ.ДОМЕН.com",
            "password": "S3gr3d0"
        }
    },
...

Обратите внимание ниже, как это можно использовать в полном примере кода сервиса, который может находиться в файле server/services/contact.js:

const name = _req.getString("name")
const email = _req.getString("email")
const subject = _req.getString("subject")
const message = _req.getString("message")

const smtp = _smtp.init("contact")

smtp.subject = subject

smtp.text = "Содержимое в HTML."

const data = _val.map()
      .set("name", name)
      .set("email", email)
      .set("subject", subject)
      .set("message", message)

smtp.html = _template.getOutput('email/contact', data)

smtp.attachment(
    "logo.png",
    "image/png",
    _app.file("public/images/logo.png"),
    "logo"
)

smtp.send()

_out.json(
    _val.map()
        .set("result", true)
)

В относительном пути шаблона не нужно указывать расширение .html; обратите внимание, что при необходимости можно передавать информацию внутрь шаблона.

HTML-содержимое шаблона должно быть определено в отдельном файле, который должен находиться в папке server/templates/; этот путь отсчитывается от корневой папки приложения.

Следуя примеру, показанному выше, файл шаблона из примера будет находиться здесь:

server/templates/email/contact.html

Пример содержимого этого файла может быть таким:

<div style="padding: 40px; background: #ffffff;">
  <img src="cid:logo" height="60" />
  <div style="padding: 20px;"></div>
  <div style="padding: 40px; background: #ffffff; font-size: 20px; font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; border: 5px solid #666;">
    <h1 style="color: #666; font-weight: bold; margin-bottom: 15px;">
      Обратная связь с сайта
    </h1>
    <p>Имя: _{&data=name}</p>
    <p>Эл. почта: _{data=email}</p>
    <p>Тема: _{&data=subject}</p>
    <p>_{&data=message}</p>
  </div>
</div>

Когда в шаблон внедряются данные с помощью _{data=...}, & добавляется, когда должна выполняться HTML-кодировка специальных символов, в результате получается _{&data=...}; после = вместо ... указывается ключ содержимого, которое будет внедрено.

Расширенные настройки

Конфигурации окружения config/_*.json позволяют задать гораздо больше расширенных настроек.

Свойства smtp, используемые в коде, такие как .from, .to, .cc, .bcc, .subject, .text и .html, можно определить в конфигурации, чтобы они были предварительно заданы по умолчанию следующим образом:

...
    "default": {
        ...
        "from": "*****@gmail.com",
        "to": "*****@gmail.com",
        "cc": "*****@gmail.com",
        "bcc": "*****@gmail.com",
        "subject": "Тема по умолчанию...",
        "text": "Содержимое по умолчанию... ок!",
        "html": "<p>Содержимое по умолчанию... <b>ок!</b></p>"
        ...
    }
...

Заранее задать .from довольно полезно, так как обычно письма всегда отправляются с одного и того же адреса.

Также возможны другие настройки. Ниже приведён их полный список:

ПАРАМЕТР	ТИП	ПО УМОЛЧАНИЮ	ОПИСАНИЕ
`enabled`	boolean	true	Включает и отключает отправку почты.
`debug`	boolean	false	Включает режим отладки, который показывает сообщения, подробно описывающие взаимодействие с сервером.
`protocol`	string		Определяет тип протокола: smtp или smtps.
`host`	string		Имя или IP-адрес SMTP-сервера.
`port`	integer	465	Номер порта SMTP-сервера.
`ssl`	boolean	true	Включает SSL.
`tls`	boolean	false	Включает TLS
`socketFactoryFallback`	boolean	true	Если создание Socket завершится неудачно, будет использован нативный java.net.Socket.
`socketFactoryClass`	string		Определяет класс, реализующий интерфейс javax.net.SocketFactory, который будет использоваться для создания сокетов для SMTP.
`socketFactoryPort`	integer		Определяет порт, который должен использоваться сокетами.
`quitWait`	boolean	false	Если включено, ожидает ответа сервера после команды QUIT; если выключено, сразу разрывает соединение с сервером после команды QUIT.
`authMechanisms`	string		Список механизмов аутентификации; по умолчанию — «LOGIN PLAIN DIGEST-MD5 NTLM», поэтому поддерживаются все механизмы.
`authNTLMDomain`	string		Домен аутентификации NTLM.
`username`	string		Определяет пользователя при аутентификации на сервере.
`html`	string		HTML-содержимое электронного письма.
`password`	string		Определяет пароль при аутентификации на сервере.
`from`	string		Адрес электронной почты отправителя.
`to`	string		Адрес электронной почты получателя; можно добавить больше адресов, разделяя их «;» или «,».
`cc`	strinf		Адрес электронной почты получателя копии; можно добавить больше адресов, разделяя их «;» или «,».
`bcc`	string		Адрес электронной почты получателя скрытой копии; можно добавить больше адресов, разделяя их «;» или «,».
`subjectPrefix`		string	Определяет префикс темы электронного письма, так гарантируется, что все отправленные письма имеют этот префикс.
`subject`	string		Тема электронного письма.
`text`	string		Текстовое содержимое электронного письма в виде обычного текста.

Если у вас есть вопросы, не стесняйтесь связаться с нами через способы, указанные в конце страницы.

Удачной разработки!

Перед началом​

Демонстрация отправки электронных писем​

Настройка​

Подробный код​

Полный пример с шаблоном​

Расширенные настройки​