lights FAQ Forum github.com/luapower/resty.mail
This package
resty.mail

Misc
csv
daemon
dollar
font_db
fonts-amiri
fonts-awesome
fonts-dejavuserif
fonts-fireflysung
fonts-fixedsys
fonts-ionicons
fonts-material-icons
fonts-noto-emoji
fonts-open-sans
http
lx
minizip2
resty-core
resty-lrucache
resty.http
resty.mail
resty.string
socket2
website
x-widgets
xlsxwriter

lua-resty-mail

CircleCI

A high-level, easy to use, and non-blocking email and SMTP library for OpenResty.

Features

  • SMTP authentication, STARTTLS, and SSL support.
  • Multipart plain text and HTML message bodies.
  • From, To, Cc, Bcc, Reply-To, and Subject fields (custom headers also supported).
  • Email addresses in “test@example.com” and “Name <test@example.com>” formats.
  • File attachments.

Installation

Via OPM:

opm get GUI/lua-resty-mail

Or via LuaRocks:

luarocks install lua-resty-mail

Usage

local mail = require "resty.mail"

local mailer, err = mail.new({
  host = "smtp.gmail.com",
  port = 587,
  starttls = true,
  username = "example@gmail.com",
  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 <splinter@example.com>",
  to = { "michelangelo@example.com" },
  cc = { "leo@example.com", "Raphael <raph@example.com>", "donatello@example.com" },
  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

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

Create and return a new mail object. In case of errors, returns nil and a string describing the error.

The options table accepts the following fields:

  • host: The host of the SMTP server to connect to. (default: localhost)
  • port: The port number on the SMTP server to connect to. (default: 25)
  • starttls: Set to true to ensure STARTTLS is always used to encrypt communication with the SMTP server. If not set, STARTTLS will automatically be enabled if the server supports it (but explicitly setting this to true if your server supports it is preferable to prevent STRIPTLS attacks). This is usually used in conjunction with port 587. (default: nil)
  • ssl: Set to true to use SMTPS to encrypt communication with the SMTP server (not needed if STARTTLS is being used instead). This is usually used in conjunction with port 465. (default: nil)
  • username: Username to use for SMTP authentication. (default: nil)
  • password: Password to use for SMTP authentication. (default: nil)
  • auth_type: The type of SMTP authentication to perform. Can either be plain or login. (default: plain if username and password are present)
  • domain: The domain name presented to the SMTP server during the EHLO connection and used as part of the Message-ID header. (default: localhost.localdomain)
  • timeout_connect: The timeout (in milliseconds) for connecting to the SMTP server. (default: OpenResty’s global lua_socket_connect_timeout timeout, which defaults to 60s)
  • timeout_send: The timeout (in milliseconds) for sending data to the SMTP server. (default: OpenResty’s global lua_socket_send_timeout timeout, which defaults to 60s)
  • timeout_read: The timeout (in milliseconds) for reading data from the SMTP server. (default: OpenResty’s global lua_socket_read_timeout timeout, which defaults to 60s)

mailer:send

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

Send an email via the SMTP server. This function returns true on success. In case of errors, returns nil and a string describing the error.

The data table accepts the following fields:

  • from: Email address for the From header.
  • reply_to: Email address for the Reply-To header.
  • to: A table (list-like) of email addresses for the To recipients.
  • cc: A table (list-like) of email addresses for the Cc recipients.
  • bcc: A table (list-like) of email addresses for the Bcc recipients.
  • subject: Message subject.
  • text: Body of the message (plain text version).
  • html: Body of the message (HTML verion).
  • headers: A table of additional headers to set on the message.
  • attachments: A table (list-like) of file attachments for the message. Each attachment must be an table (map-like) with the following fields:
    • filename: The filename of the attachment.
    • content_type: The Content-Type of the file attachment.
    • content: The contents of the file attachment as a string.
    • disposition: The Content-Disposition of the file attachment. Can either be attachment or inline. (default: attachment)
    • content_id: The Content-ID of the file attachment. (default: randomly generated ID)

Development

After checking out the repo, Docker can be used to run the test suite:

docker-compose run --rm app make test

Release Process

To release a new version to LuaRocks and OPM:

  • Ensure CHANGELOG.md is up to date.
  • Update the _VERSION in lib/resty/mail.lua.
  • Update the version in dist.ini.
  • Move the rockspec file to the new version number (git mv lua-resty-mail-X.X.X-1.rockspec lua-resty-mail-X.X.X-1.rockspec), and update the version and tag variables in the rockspec file.
  • Commit and tag the release (git tag -a vX.X.X -m "Tagging vX.X.X" && git push origin vX.X.X).
  • Run make release VERSION=X.X.X.

Last updated: 2 months ago | Edit on GitHub

Package:resty.mail
Pkg type:Lua
Version: v1.0.2-1-gf37cfc9
Last commit:
License: Public Domain

Requires: none

Required by: none


Top