Перейти к содержанию

mail: Высокоуровневая, простая в использовании и неблокирующая библиотека для работы с электронной почтой и SMTP для nginx-module-lua

Установка

Если вы еще не подписались на репозиторий RPM, зарегистрируйтесь. Затем вы можете продолжить с следующими шагами.

CentOS/RHEL 7 или Amazon Linux 2

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-mail

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-mail

Чтобы использовать эту библиотеку Lua с NGINX, убедитесь, что установлен nginx-module-lua.

Этот документ описывает lua-resty-mail v1.1.0, выпущенную 23 сентября 2023 года.

CircleCI

Высокоуровневая, простая в использовании и неблокирующая библиотека для работы с электронной почтой и SMTP для OpenResty.

Особенности

  • Поддержка SMTP-аутентификации, STARTTLS и SSL.
  • Многочастные текстовые и HTML-сообщения.
  • Поля From, To, Cc, Bcc, Reply-To и Subject (также поддерживаются пользовательские заголовки).
  • Электронные адреса в форматах "test@example.com" и "Name <test@example.com>".
  • Вложения файлов.

Использование

local mail = require "resty.mail"

local mailer, err = mail.new({
  host = "smtp.gmail.com",
  port = 587,
  starttls = true,
  username = "[email protected]",
  password = "password",
})
if err then
  ngx.log(ngx.ERR, "mail.new error: ", err)
  return ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
end

local ok, err = mailer:send({
  from = "Master Splinter <[email protected]>",
  to = { "[email protected]" },
  cc = { "[email protected]", "Raphael <[email protected]>", "[email protected]" },
  subject = "Pizza is here!",
  text = "There's pizza in the sewer.",
  html = "<h1>There's pizza in the sewer.</h1>",
  attachments = {
    {
      filename = "toppings.txt",
      content_type = "text/plain",
      content = "1. Cheese\n2. Pepperoni",
    },
  },
})
if err then
  ngx.log(ngx.ERR, "mailer:send error: ", err)
  return ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
end

API

new

синтаксис: mailer, err = mail.new(options)

Создает и возвращает новый объект почты. В случае ошибок возвращает nil и строку, описывающую ошибку.

Таблица options принимает следующие поля:

  • host: Хост SMTP-сервера, к которому нужно подключиться. (по умолчанию: localhost)
  • port: Номер порта на SMTP-сервере, к которому нужно подключиться. (по умолчанию: 25)
  • starttls: Установите в true, чтобы гарантировать, что STARTTLS всегда используется для шифрования связи с SMTP-сервером. Если не установлено, STARTTLS будет автоматически включен, если сервер его поддерживает (но предпочтительно явно установить это в true, если ваш сервер его поддерживает, чтобы предотвратить атаки STRIPTLS). Обычно используется вместе с портом 587. (по умолчанию: nil)
  • ssl: Установите в true, чтобы использовать SMTPS для шифрования связи с SMTP-сервером (не требуется, если используется STARTTLS). Обычно используется вместе с портом 465. (по умолчанию: nil)
  • username: Имя пользователя для аутентификации SMTP. (по умолчанию: nil)
  • password: Пароль для аутентификации SMTP. (по умолчанию: nil)
  • auth_type: Тип аутентификации SMTP, который нужно выполнить. Может быть plain или login. (по умолчанию: plain, если указаны имя пользователя и пароль)
  • domain: Имя домена, представленное SMTP-серверу во время соединения EHLO и используемое как часть заголовка Message-ID. (по умолчанию: localhost.localdomain)
  • ssl_verify: Необходимо ли выполнять проверку сертификата сервера, когда включены ssl или starttls. Если это включено, потребуется настроить lua_ssl_trusted_certificate. (по умолчанию: false)
  • ssl_host: Если имя хоста сертификата сервера отличается от параметра host, это значение можно использовать для указания другого хоста, используемого для SNI и проверки TLS, когда включены ssl или starttls. (по умолчанию: значение параметра host)
  • timeout_connect: Таймаут (в миллисекундах) для подключения к SMTP-серверу. (по умолчанию: глобальный таймаут lua_socket_connect_timeout OpenResty, который по умолчанию составляет 60 секунд)
  • timeout_send: Таймаут (в миллисекундах) для отправки данных на SMTP-сервер. (по умолчанию: глобальный таймаут lua_socket_send_timeout OpenResty, который по умолчанию составляет 60 секунд)
  • timeout_read: Таймаут (в миллисекундах) для чтения данных с SMTP-сервера. (по умолчанию: глобальный таймаут lua_socket_read_timeout OpenResty, который по умолчанию составляет 60 секунд)

mailer:send

синтаксис: ok, err = mailer:send(data)

Отправляет электронное письмо через SMTP-сервер. Эта функция возвращает true при успешном выполнении. В случае ошибок возвращает nil и строку, описывающую ошибку.

Таблица data принимает следующие поля:

  • from: Электронный адрес для заголовка From.
  • reply_to: Электронный адрес для заголовка Reply-To.
  • to: Таблица (похожая на список) электронных адресов для получателей To.
  • cc: Таблица (похожая на список) электронных адресов для получателей Cc.
  • bcc: Таблица (похожая на список) электронных адресов для получателей Bcc.
  • subject: Тема сообщения.
  • text: Тело сообщения (версия в обычном тексте).
  • html: Тело сообщения (HTML версия).
  • headers: Таблица дополнительных заголовков, которые нужно установить в сообщении.
  • attachments: Таблица (похожая на список) вложений файлов для сообщения. Каждое вложение должно быть таблицей (похожей на карту) со следующими полями:
  • filename: Имя файла вложения.
  • content_type: Content-Type файла вложения.
  • content: Содержимое файла вложения в виде строки.
  • disposition: Content-Disposition файла вложения. Может быть attachment или inline. (по умолчанию: attachment)
  • content_id: Content-ID файла вложения. (по умолчанию: случайно сгенерированный ID)

Разработка

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

docker-compose run --rm app make test

Процесс выпуска

Чтобы выпустить новую версию для LuaRocks и OPM:

  • Убедитесь, что CHANGELOG.md актуален.
  • Обновите _VERSION в lib/resty/mail.lua.
  • Обновите version в dist.ini.
  • Переместите файл rockspec на новый номер версии (git mv lua-resty-mail-X.X.X-1.rockspec lua-resty-mail-X.X.X-1.rockspec), и обновите переменные version и tag в файле rockspec.
  • Зафиксируйте и тегируйте выпуск (git tag -a vX.X.X -m "Tagging vX.X.X" && git push origin vX.X.X).
  • Запустите make release VERSION=X.X.X.

GitHub

Вы можете найти дополнительные советы по настройке и документацию для этого модуля в репозитории GitHub для nginx-module-mail.