Saltar a contenido

mail: Una biblioteca de correo electrónico y SMTP de alto nivel, fácil de usar y no bloqueante para nginx-module-lua

Instalación

Si no has configurado la suscripción al repositorio RPM, regístrate. Luego puedes proceder con los siguientes pasos.

CentOS/RHEL 7 o 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 con NGINX, asegúrate de que nginx-module-lua esté instalado.

Este documento describe lua-resty-mail v1.2.0 lanzado el 04 de febrero de 2026.

Una biblioteca de correo electrónico y SMTP de alto nivel, fácil de usar y no bloqueante para OpenResty.

Características

  • Autenticación SMTP, soporte para STARTTLS y SSL.
  • Cuerpos de mensajes en texto plano y HTML multipart.
  • Campos From, To, Cc, Bcc, Reply-To y Subject (también se admiten encabezados personalizados).
  • Direcciones de correo electrónico en formatos "test@example.com" y "Nombre <test@example.com>".
  • Archivos adjuntos.

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 = "¡La pizza ha llegado!",
  text = "Hay pizza en la alcantarilla.",
  html = "<h1>Hay pizza en la alcantarilla.</h1>",
  attachments = {
    {
      filename = "toppings.txt",
      content_type = "text/plain",
      content = "1. Queso\n2. Pepperoni",
    },
  },
})
if err then
  ngx.log(ngx.ERR, "mailer:send error: ", err)
  return ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
end

API

new

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

Crea y devuelve un nuevo objeto de correo. En caso de errores, devuelve nil y una cadena que describe el error.

La tabla options acepta los siguientes campos:

  • host: El host del servidor SMTP al que conectarse. (predeterminado: localhost)
  • port: El número de puerto en el servidor SMTP al que conectarse. (predeterminado: 25)
  • starttls: Establecer en true para asegurar que STARTTLS se utilice siempre para cifrar la comunicación con el servidor SMTP. Si no se establece, STARTTLS se habilitará automáticamente si el servidor lo admite (pero establecer esto explícitamente en verdadero si tu servidor lo admite es preferible para prevenir ataques STRIPTLS). Esto se utiliza generalmente junto con el puerto 587. (predeterminado: nil)
  • ssl: Establecer en true para usar SMTPS para cifrar la comunicación con el servidor SMTP (no es necesario si se está utilizando STARTTLS en su lugar). Esto se utiliza generalmente junto con el puerto 465. (predeterminado: nil)
  • username: Nombre de usuario para usar en la autenticación SMTP. (predeterminado: nil)
  • password: Contraseña para usar en la autenticación SMTP. (predeterminado: nil)
  • auth_type: El tipo de autenticación SMTP a realizar. Puede ser plain o login. (predeterminado: plain si se presentan nombre de usuario y contraseña)
  • domain: El nombre de dominio presentado al servidor SMTP durante la conexión EHLO y utilizado como parte del encabezado Message-ID. (predeterminado: localhost.localdomain)
  • ssl_verify: Si se debe o no realizar la verificación del certificado del servidor cuando se habilita ssl o starttls. Si esto está habilitado, será necesario configurar la opción lua_ssl_trusted_certificate. (predeterminado: false)
  • ssl_host: Si el nombre del host del certificado del servidor es diferente al de la opción host, esta configuración se puede usar para especificar un host diferente utilizado para la verificación de SNI y TLS cuando se habilita ssl o starttls. (predeterminado: el valor de la opción host)
  • timeout_connect: El tiempo de espera (en milisegundos) para conectarse al servidor SMTP. (predeterminado: tiempo de espera global lua_socket_connect_timeout de OpenResty, que por defecto es 60s)
  • timeout_send: El tiempo de espera (en milisegundos) para enviar datos al servidor SMTP. (predeterminado: tiempo de espera global lua_socket_send_timeout de OpenResty, que por defecto es 60s)
  • timeout_read: El tiempo de espera (en milisegundos) para leer datos del servidor SMTP. (predeterminado: tiempo de espera global lua_socket_read_timeout de OpenResty, que por defecto es 60s)

mailer:send

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

Envía un correo electrónico a través del servidor SMTP. Esta función devuelve true en caso de éxito. En caso de errores, devuelve nil y una cadena que describe el error.

La tabla data acepta los siguientes campos:

  • from: Dirección de correo electrónico para el encabezado From.
  • reply_to: Dirección de correo electrónico para el encabezado Reply-To.
  • to: Una tabla (tipo lista) de direcciones de correo electrónico para los destinatarios To.
  • cc: Una tabla (tipo lista) de direcciones de correo electrónico para los destinatarios Cc.
  • bcc: Una tabla (tipo lista) de direcciones de correo electrónico para los destinatarios Bcc.
  • subject: Asunto del mensaje.
  • text: Cuerpo del mensaje (versión de texto plano).
  • html: Cuerpo del mensaje (versión HTML).
  • headers: Una tabla de encabezados adicionales para establecer en el mensaje.
  • attachments: Una tabla (tipo lista) de archivos adjuntos para el mensaje. Cada archivo adjunto debe ser una tabla (tipo mapa) con los siguientes campos:
  • filename: El nombre del archivo del adjunto.
  • content_type: El Content-Type del archivo adjunto.
  • content: El contenido del archivo adjunto como una cadena.
  • disposition: El Content-Disposition del archivo adjunto. Puede ser attachment o inline. (predeterminado: attachment)
  • content_id: El Content-ID del archivo adjunto. (predeterminado: ID generado aleatoriamente)

Desarrollo

Después de clonar el repositorio, se puede usar Docker para ejecutar la suite de pruebas:

docker-compose run --rm app make test

Proceso de Lanzamiento

Para lanzar una nueva versión en LuaRocks y OPM:

  • Asegúrate de que CHANGELOG.md esté actualizado.
  • Actualiza el _VERSION en lib/resty/mail.lua.
  • Actualiza la version en dist.ini.
  • Mueve el archivo rockspec al nuevo número de versión (git mv lua-resty-mail-X.X.X-1.rockspec lua-resty-mail-X.X.X-1.rockspec), y actualiza las variables version y tag en el archivo rockspec.
  • Realiza un commit y etiqueta el lanzamiento (git tag -a vX.X.X -m "Tagging vX.X.X" && git push origin vX.X.X).
  • Ejecuta make release VERSION=X.X.X.

GitHub

Puedes encontrar consejos de configuración adicionales y documentación para este módulo en el repositorio de GitHub para nginx-module-mail.