Pular para conteúdo

mail: Uma biblioteca de email e SMTP de alto nível, fácil de usar e não bloqueante para nginx-module-lua

Instalação

Se você ainda não configurou a assinatura do repositório RPM, inscreva-se. Depois, você pode prosseguir com os seguintes passos.

CentOS/RHEL 7 ou 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

Para usar esta biblioteca Lua com NGINX, certifique-se de que o nginx-module-lua esteja instalado.

Este documento descreve lua-resty-mail v1.2.0 lançado em 04 de fevereiro de 2026.

Uma biblioteca de email e SMTP de alto nível, fácil de usar e não bloqueante para OpenResty.

Recursos

  • Autenticação SMTP, suporte a STARTTLS e SSL.
  • Corpos de mensagens em texto simples e HTML multipart.
  • Campos From, To, Cc, Bcc, Reply-To e Subject (cabeçalhos personalizados também suportados).
  • Endereços de email nos formatos "test@example.com" e "Nome <test@example.com>".
  • Anexos de arquivo.

Uso

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 chegou!",
  text = "Tem pizza no esgoto.",
  html = "<h1>Tem pizza no esgoto.</h1>",
  attachments = {
    {
      filename = "toppings.txt",
      content_type = "text/plain",
      content = "1. Queijo\n2. Pepperoni",
    },
  },
})
if err then
  ngx.log(ngx.ERR, "mailer:send error: ", err)
  return ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
end

API

new

sintaxe: mailer, err = mail.new(options)

Cria e retorna um novo objeto de email. Em caso de erros, retorna nil e uma string descrevendo o erro.

A tabela options aceita os seguintes campos:

  • host: O host do servidor SMTP ao qual se conectar. (padrão: localhost)
  • port: O número da porta no servidor SMTP ao qual se conectar. (padrão: 25)
  • starttls: Defina como true para garantir que STARTTLS seja sempre usado para criptografar a comunicação com o servidor SMTP. Se não definido, o STARTTLS será habilitado automaticamente se o servidor suportar (mas definir isso explicitamente como verdadeiro, se seu servidor suportar, é preferível para evitar ataques STRIPTLS). Isso é geralmente usado em conjunto com a porta 587. (padrão: nil)
  • ssl: Defina como true para usar SMTPS para criptografar a comunicação com o servidor SMTP (não necessário se o STARTTLS estiver sendo usado). Isso é geralmente usado em conjunto com a porta 465. (padrão: nil)
  • username: Nome de usuário a ser usado para autenticação SMTP. (padrão: nil)
  • password: Senha a ser usada para autenticação SMTP. (padrão: nil)
  • auth_type: O tipo de autenticação SMTP a ser realizada. Pode ser plain ou login. (padrão: plain se nome de usuário e senha estiverem presentes)
  • domain: O nome de domínio apresentado ao servidor SMTP durante a conexão EHLO e usado como parte do cabeçalho Message-ID. (padrão: localhost.localdomain)
  • ssl_verify: Se deve ou não realizar a verificação do certificado do servidor quando ssl ou starttls estão habilitados. Se isso estiver habilitado, configurar a opção lua_ssl_trusted_certificate será necessário. (padrão: false)
  • ssl_host: Se o nome do host do certificado do servidor for diferente do valor da opção host, esta configuração pode ser usada para especificar um host diferente usado para verificação SNI e TLS quando ssl ou starttls estão habilitados. (padrão: o valor da opção host)
  • timeout_connect: O tempo limite (em milissegundos) para conectar-se ao servidor SMTP. (padrão: o tempo limite global lua_socket_connect_timeout do OpenResty, que é de 60s)
  • timeout_send: O tempo limite (em milissegundos) para enviar dados ao servidor SMTP. (padrão: o tempo limite global lua_socket_send_timeout do OpenResty, que é de 60s)
  • timeout_read: O tempo limite (em milissegundos) para ler dados do servidor SMTP. (padrão: o tempo limite global lua_socket_read_timeout do OpenResty, que é de 60s)

mailer:send

sintaxe: ok, err = mailer:send(data)

Envia um email via o servidor SMTP. Esta função retorna true em caso de sucesso. Em caso de erros, retorna nil e uma string descrevendo o erro.

A tabela data aceita os seguintes campos:

  • from: Endereço de email para o cabeçalho From.
  • reply_to: Endereço de email para o cabeçalho Reply-To.
  • to: Uma tabela (semelhante a lista) de endereços de email para os destinatários To.
  • cc: Uma tabela (semelhante a lista) de endereços de email para os destinatários Cc.
  • bcc: Uma tabela (semelhante a lista) de endereços de email para os destinatários Bcc.
  • subject: Assunto da mensagem.
  • text: Corpo da mensagem (versão em texto simples).
  • html: Corpo da mensagem (versão em HTML).
  • headers: Uma tabela de cabeçalhos adicionais a serem definidos na mensagem.
  • attachments: Uma tabela (semelhante a lista) de anexos de arquivo para a mensagem. Cada anexo deve ser uma tabela (semelhante a mapa) com os seguintes campos:
  • filename: O nome do arquivo do anexo.
  • content_type: O Content-Type do arquivo anexo.
  • content: O conteúdo do arquivo anexo como uma string.
  • disposition: O Content-Disposition do arquivo anexo. Pode ser attachment ou inline. (padrão: attachment)
  • content_id: O Content-ID do arquivo anexo. (padrão: ID gerado aleatoriamente)

Desenvolvimento

Após clonar o repositório, o Docker pode ser usado para executar a suíte de testes:

docker-compose run --rm app make test

Processo de Lançamento

Para lançar uma nova versão no LuaRocks e OPM:

  • Certifique-se de que o CHANGELOG.md esteja atualizado.
  • Atualize o _VERSION em lib/resty/mail.lua.
  • Atualize a version em dist.ini.
  • Mova o arquivo rockspec para o novo número da versão (git mv lua-resty-mail-X.X.X-1.rockspec lua-resty-mail-X.X.X-1.rockspec), e atualize as variáveis version e tag no arquivo rockspec.
  • Faça o commit e marque o lançamento (git tag -a vX.X.X -m "Tagging vX.X.X" && git push origin vX.X.X).
  • Execute make release VERSION=X.X.X.

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório GitHub para nginx-module-mail.