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

要在NGINX中使用此Lua库，请确保已安装nginx-module-lua。

本文档描述了lua-resty-mail v1.1.0，于2023年9月23日发布。

一个高层次、易于使用且非阻塞的电子邮件和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: 在EHLO连接期间向SMTP服务器呈现的域名，并用作Message-ID头的一部分。（默认: localhost.localdomain）
ssl_verify: 当启用ssl或starttls时，是否执行服务器证书的验证。如果启用，则需要配置lua_ssl_trusted_certificate设置。（默认: false）
ssl_host: 如果服务器证书的主机名与host选项不同，则可以使用此设置指定在启用ssl或starttls时用于SNI和TLS验证的不同主机。（默认: host选项的值）
timeout_connect: 连接到SMTP服务器的超时时间（以毫秒为单位）。（默认: OpenResty的全局lua_socket_connect_timeout超时，默认为60秒）
timeout_send: 向SMTP服务器发送数据的超时时间（以毫秒为单位）。（默认: OpenResty的全局lua_socket_send_timeout超时，默认为60秒）
timeout_read: 从SMTP服务器读取数据的超时时间（以毫秒为单位）。（默认: OpenResty的全局lua_socket_read_timeout超时，默认为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是最新的。
更新lib/resty/mail.lua中的_VERSION。
更新dist.ini中的version。
将rockspec文件移动到新版本号（git mv lua-resty-mail-X.X.X-1.rockspec lua-resty-mail-X.X.X-1.rockspec），并更新rockspec文件中的version和tag变量。
提交并标记发布（git tag -a vX.X.X -m "Tagging vX.X.X" && git push origin vX.X.X）。
运行make release VERSION=X.X.X。

GitHub

您可以在nginx-module-mail的GitHub仓库中找到此模块的其他配置提示和文档。