Zum Inhalt

mail: Eine hochgradige, einfach zu verwendende und nicht-blockierende E-Mail- und SMTP-Bibliothek für nginx-module-lua

Installation

Wenn Sie noch kein RPM-Repository-Abonnement eingerichtet haben, melden Sie sich an. Dann können Sie mit den folgenden Schritten fortfahren.

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

Um diese Lua-Bibliothek mit NGINX zu verwenden, stellen Sie sicher, dass nginx-module-lua installiert ist.

Dieses Dokument beschreibt lua-resty-mail v1.2.0, veröffentlicht am 04. Februar 2026.

Eine hochgradige, einfach zu verwendende und nicht-blockierende E-Mail- und SMTP-Bibliothek für OpenResty.

Funktionen

  • SMTP-Authentifizierung, STARTTLS und SSL-Unterstützung.
  • Multipart-Text- und HTML-Nachrichtentexte.
  • Von-, An-, Cc-, Bcc-, Antwort-an- und Betrefffelder (benutzerdefinierte Header werden ebenfalls unterstützt).
  • E-Mail-Adressen im Format "test@example.com" und "Name <test@example.com>".
  • Dateianhänge.

Verwendung

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 ist da!",
  text = "Es gibt Pizza im Abwasser.",
  html = "<h1>Es gibt Pizza im Abwasser.</h1>",
  attachments = {
    {
      filename = "toppings.txt",
      content_type = "text/plain",
      content = "1. Käse\n2. Pepperoni",
    },
  },
})
if err then
  ngx.log(ngx.ERR, "mailer:send error: ", err)
  return ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
end

API

new

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

Erstellt und gibt ein neues Mail-Objekt zurück. Im Falle von Fehlern gibt es nil und eine Zeichenfolge zurück, die den Fehler beschreibt.

Die options-Tabelle akzeptiert die folgenden Felder:

  • host: Der Host des SMTP-Servers, zu dem eine Verbindung hergestellt werden soll. (Standard: localhost)
  • port: Die Portnummer des SMTP-Servers, zu dem eine Verbindung hergestellt werden soll. (Standard: 25)
  • starttls: Auf true setzen, um sicherzustellen, dass STARTTLS immer verwendet wird, um die Kommunikation mit dem SMTP-Server zu verschlüsseln. Wenn nicht gesetzt, wird STARTTLS automatisch aktiviert, wenn der Server es unterstützt (aber es ist vorzuziehen, dies auf true zu setzen, wenn Ihr Server es unterstützt, um STRIPTLS-Angriffe zu verhindern). Dies wird normalerweise in Verbindung mit Port 587 verwendet. (Standard: nil)
  • ssl: Auf true setzen, um SMTPS zu verwenden, um die Kommunikation mit dem SMTP-Server zu verschlüsseln (nicht erforderlich, wenn stattdessen STARTTLS verwendet wird). Dies wird normalerweise in Verbindung mit Port 465 verwendet. (Standard: nil)
  • username: Benutzername zur Verwendung für die SMTP-Authentifizierung. (Standard: nil)
  • password: Passwort zur Verwendung für die SMTP-Authentifizierung. (Standard: nil)
  • auth_type: Der Typ der durchzuführenden SMTP-Authentifizierung. Kann entweder plain oder login sein. (Standard: plain, wenn Benutzername und Passwort vorhanden sind)
  • domain: Der Domainname, der dem SMTP-Server während der EHLO-Verbindung präsentiert wird und als Teil des Message-ID-Headers verwendet wird. (Standard: localhost.localdomain)
  • ssl_verify: Ob die Überprüfung des Serverzertifikats durchgeführt werden soll, wenn entweder ssl oder starttls aktiviert ist. Wenn dies aktiviert ist, muss die lua_ssl_trusted_certificate Einstellung konfiguriert werden. (Standard: false)
  • ssl_host: Wenn der Hostname des Serverzertifikats anders ist als die host-Option, kann diese Einstellung verwendet werden, um einen anderen Host für SNI- und TLS-Überprüfung anzugeben, wenn entweder ssl oder starttls aktiviert ist. (Standard: der Wert der host-Option)
  • timeout_connect: Der Timeout (in Millisekunden) für die Verbindung zum SMTP-Server. (Standard: OpenRestys globaler lua_socket_connect_timeout, der standardmäßig auf 60s eingestellt ist)
  • timeout_send: Der Timeout (in Millisekunden) für das Senden von Daten an den SMTP-Server. (Standard: OpenRestys globaler lua_socket_send_timeout, der standardmäßig auf 60s eingestellt ist)
  • timeout_read: Der Timeout (in Millisekunden) für das Lesen von Daten vom SMTP-Server. (Standard: OpenRestys globaler lua_socket_read_timeout, der standardmäßig auf 60s eingestellt ist)

mailer:send

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

Sendet eine E-Mail über den SMTP-Server. Diese Funktion gibt true bei Erfolg zurück. Im Falle von Fehlern gibt es nil und eine Zeichenfolge zurück, die den Fehler beschreibt.

Die data-Tabelle akzeptiert die folgenden Felder:

  • from: E-Mail-Adresse für den From-Header.
  • reply_to: E-Mail-Adresse für den Reply-To-Header.
  • to: Eine Tabelle (listenähnlich) von E-Mail-Adressen für die To-Empfänger.
  • cc: Eine Tabelle (listenähnlich) von E-Mail-Adressen für die Cc-Empfänger.
  • bcc: Eine Tabelle (listenähnlich) von E-Mail-Adressen für die Bcc-Empfänger.
  • subject: Betreff der Nachricht.
  • text: Textkörper der Nachricht (reine Textversion).
  • html: Textkörper der Nachricht (HTML-Version).
  • headers: Eine Tabelle zusätzlicher Header, die für die Nachricht festgelegt werden sollen.
  • attachments: Eine Tabelle (listenähnlich) von Dateianhängen für die Nachricht. Jeder Anhang muss eine Tabelle (kartenähnlich) mit den folgenden Feldern sein:
  • filename: Der Dateiname des Anhangs.
  • content_type: Der Content-Type des Dateianhangs.
  • content: Der Inhalt des Dateianhangs als Zeichenfolge.
  • disposition: Die Content-Disposition des Dateianhangs. Kann entweder attachment oder inline sein. (Standard: attachment)
  • content_id: Die Content-ID des Dateianhangs. (Standard: zufällig generierte ID)

Entwicklung

Nach dem Auschecken des Repos kann Docker verwendet werden, um die Test-Suite auszuführen:

docker-compose run --rm app make test

Veröffentlichungsprozess

Um eine neue Version für LuaRocks und OPM zu veröffentlichen:

  • Stellen Sie sicher, dass CHANGELOG.md auf dem neuesten Stand ist.
  • Aktualisieren Sie die _VERSION in lib/resty/mail.lua.
  • Aktualisieren Sie die version in dist.ini.
  • Verschieben Sie die rockspec-Datei auf die neue Versionsnummer (git mv lua-resty-mail-X.X.X-1.rockspec lua-resty-mail-X.X.X-1.rockspec), und aktualisieren Sie die version- und tag-Variablen in der rockspec-Datei.
  • Committen und taggen Sie die Veröffentlichung (git tag -a vX.X.X -m "Tagging vX.X.X" && git push origin vX.X.X).
  • Führen Sie make release VERSION=X.X.X aus.

GitHub

Sie finden möglicherweise zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-mail.