Aller au contenu

mail: Une bibliothèque de messagerie et SMTP de haut niveau, facile à utiliser et non bloquante pour nginx-module-lua

Installation

Si vous n'avez pas encore configuré l'abonnement au dépôt RPM, inscrivez-vous. Ensuite, vous pouvez procéder avec les étapes suivantes.

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

Pour utiliser cette bibliothèque Lua avec NGINX, assurez-vous que nginx-module-lua est installé.

Ce document décrit lua-resty-mail v1.2.0 publié le 04 février 2026.

Une bibliothèque de messagerie et SMTP de haut niveau, facile à utiliser et non bloquante pour OpenResty.

Caractéristiques

  • Authentification SMTP, STARTTLS et support SSL.
  • Corps de messages en texte brut et HTML multipart.
  • Champs From, To, Cc, Bcc, Reply-To et Subject (en-têtes personnalisés également pris en charge).
  • Adresses e-mail au format "test@example.com" et "Nom <test@example.com>".
  • Pièces jointes de fichiers.

Utilisation

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 est arrivée !",
  text = "Il y a de la pizza dans les égouts.",
  html = "<h1>Il y a de la pizza dans les égouts.</h1>",
  attachments = {
    {
      filename = "toppings.txt",
      content_type = "text/plain",
      content = "1. Fromage\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)

Crée et retourne un nouvel objet mail. En cas d'erreurs, retourne nil et une chaîne décrivant l'erreur.

La table options accepte les champs suivants :

  • host: L'hôte du serveur SMTP auquel se connecter. (par défaut : localhost)
  • port: Le numéro de port sur le serveur SMTP auquel se connecter. (par défaut : 25)
  • starttls: Défini sur true pour s'assurer que STARTTLS est toujours utilisé pour chiffrer la communication avec le serveur SMTP. Si non défini, STARTTLS sera automatiquement activé si le serveur le prend en charge (mais il est préférable de le définir explicitement sur true si votre serveur le prend en charge pour éviter les attaques STRIPTLS). Cela est généralement utilisé en conjonction avec le port 587. (par défaut : nil)
  • ssl: Défini sur true pour utiliser SMTPS pour chiffrer la communication avec le serveur SMTP (non nécessaire si STARTTLS est utilisé à la place). Cela est généralement utilisé en conjonction avec le port 465. (par défaut : nil)
  • username: Nom d'utilisateur à utiliser pour l'authentification SMTP. (par défaut : nil)
  • password: Mot de passe à utiliser pour l'authentification SMTP. (par défaut : nil)
  • auth_type: Le type d'authentification SMTP à effectuer. Peut être plain ou login. (par défaut : plain si le nom d'utilisateur et le mot de passe sont présents)
  • domain: Le nom de domaine présenté au serveur SMTP lors de la connexion EHLO et utilisé comme partie de l'en-tête Message-ID. (par défaut : localhost.localdomain)
  • ssl_verify: Indique s'il faut ou non effectuer la vérification du certificat du serveur lorsque ssl ou starttls est activé. Si cela est activé, la configuration du paramètre lua_ssl_trusted_certificate sera requise. (par défaut : false)
  • ssl_host: Si le nom d'hôte du certificat du serveur est différent de l'option host, ce paramètre peut être utilisé pour spécifier un hôte différent utilisé pour la vérification SNI et TLS lorsque ssl ou starttls est activé. (par défaut : la valeur de l'option host)
  • timeout_connect: Le délai d'attente (en millisecondes) pour se connecter au serveur SMTP. (par défaut : délai d'attente global lua_socket_connect_timeout d'OpenResty, qui par défaut est de 60s)
  • timeout_send: Le délai d'attente (en millisecondes) pour envoyer des données au serveur SMTP. (par défaut : délai d'attente global lua_socket_send_timeout d'OpenResty, qui par défaut est de 60s)
  • timeout_read: Le délai d'attente (en millisecondes) pour lire des données depuis le serveur SMTP. (par défaut : délai d'attente global lua_socket_read_timeout d'OpenResty, qui par défaut est de 60s)

mailer:send

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

Envoyer un e-mail via le serveur SMTP. Cette fonction retourne true en cas de succès. En cas d'erreurs, retourne nil et une chaîne décrivant l'erreur.

La table data accepte les champs suivants :

  • from: Adresse e-mail pour l'en-tête From.
  • reply_to: Adresse e-mail pour l'en-tête Reply-To.
  • to: Une table (de type liste) d'adresses e-mail pour les destinataires To.
  • cc: Une table (de type liste) d'adresses e-mail pour les destinataires Cc.
  • bcc: Une table (de type liste) d'adresses e-mail pour les destinataires Bcc.
  • subject: Sujet du message.
  • text: Corps du message (version texte brut).
  • html: Corps du message (version HTML).
  • headers: Une table d'en-têtes supplémentaires à définir sur le message.
  • attachments: Une table (de type liste) de pièces jointes pour le message. Chaque pièce jointe doit être une table (de type map) avec les champs suivants :
  • filename: Le nom de fichier de la pièce jointe.
  • content_type: Le Content-Type de la pièce jointe.
  • content: Le contenu de la pièce jointe sous forme de chaîne.
  • disposition: Le Content-Disposition de la pièce jointe. Peut être attachment ou inline. (par défaut : attachment)
  • content_id: Le Content-ID de la pièce jointe. (par défaut : ID généré aléatoirement)

Développement

Après avoir cloné le dépôt, Docker peut être utilisé pour exécuter la suite de tests :

docker-compose run --rm app make test

Processus de publication

Pour publier une nouvelle version sur LuaRocks et OPM :

  • Assurez-vous que CHANGELOG.md est à jour.
  • Mettez à jour le _VERSION dans lib/resty/mail.lua.
  • Mettez à jour le version dans dist.ini.
  • Déplacez le fichier rockspec vers le nouveau numéro de version (git mv lua-resty-mail-X.X.X-1.rockspec lua-resty-mail-X.X.X-1.rockspec), et mettez à jour les variables version et tag dans le fichier rockspec.
  • Validez et taguez la publication (git tag -a vX.X.X -m "Tagging vX.X.X" && git push origin vX.X.X).
  • Exécutez make release VERSION=X.X.X.

GitHub

Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-mail.