A high-level, easy to use, and non-blocking email and SMTP library for OpenResty.
Via OPM:
opm get GUI/lua-resty-mail
Or via LuaRocks:
luarocks install lua-resty-mail
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
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
)ssl_verify
: Whether or not to perform verification of the server's certificate when either ssl
or starttls
is enabled. If this is enabled then configuring the lua_ssl_trusted_certificate
setting will be required. (default: false
)ssl_host
: If the hostname of the server's certificate is different than the host
option, this setting can be used to specify a different host used for SNI and TLS verification when either ssl
or starttls
is enabled. (default: the host
option's value)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)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)After checking out the repo, Docker can be used to run the test suite:
docker-compose run --rm app make test
To release a new version to LuaRocks and OPM:
CHANGELOG.md
is up to date._VERSION
in lib/resty/mail.lua
.version
in dist.ini
.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.git tag -a vX.X.X -m "Tagging vX.X.X" && git push origin vX.X.X
).make release VERSION=X.X.X
.