$ opm get GUI/lua-resty-mail

lua-resty-mail

[!CircleCI](https://circleci.com/gh/GUI/lua-resty-mail)

OpenResty 的一个高级、易用、非阻塞的邮件和 SMTP 库。

特性

• 支持 SMTP 认证、STARTTLS 和 SSL。

• 支持多部分纯文本和 HTML 消息体。

• 支持 From、To、Cc、Bcc、Reply-To 和 Subject 字段（也支持自定义标头）。

• 支持 "[email protected]" 和 "Name <[email protected]>" 格式的电子邮件地址。

• 支持文件附件。

安装

通过 OPM

    opm get GUI/lua-resty-mail

或通过 LuaRocks

    luarocks install lua-resty-mail

用法

    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（但如果您的服务器支持 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。