Awesome

lua-resty-smtp

I must be crazy trying to send mail with Nginx.

Purpose

To make Nginx a bridge between HTTP and SMTP.

Using lua-resty-smtp in your lua code under Nginx, you just need to issue a HTTP request with your handy HTTP client (curl, wget, urllib2 from Python etc.), in order to send a mail to your SMTP server.

Features

• Based on module socket.smtp from LuaScoket 2.0.2, and API-compatible with it also

• SSL connection supported (lua-nginx-lua >= v0.9.11 needed)

APIs

lua-resty-smtp is API-compatible with socket.smtp from LuaSocket 2.0.2, and you can check SMTP for detailed reference of it.

And to support SSL connection to SMTP server, optional parameter ssl is added:

• ssl: should be a table with following fields:

  • enable - boolean - whether or not use SSL connection to SMTP server, default false;

  • verify_cert - boolean - whether or not to perform SSL verification, default false. When set to true, the server certificate will be verified according to the CA certificate specified by the lua_ssl_trusted_cerfificate directive.

Extra filters

In addtion to the low-level filters provided by LuaSocket, two more filters is provided:

• mime.ew: used to encode non-ASCII string into the Encoded-Word format (not support Q-encoding yet);

• mime.unew: used to decode string in Encoded-Word format (not implemented);

Installation

make install

or

luarocks install --local rockspec/resty.smtp-0.0.3-1.rockspec

Example

local config = require("config")
local smtp = require("resty.smtp")
local mime = require("resty.smtp.mime")
local ltn12 = require("resty.smtp.ltn12")

-- ...
-- Suppose your mail data in table `args` and default settings
-- in table `config.mail`
-- ...

local mesgt = {
    headers= {
        subject= mime.ew(args.subject or config.mail.SUBJECT, nil,
                         { charset= "utf-8" }),
        ["content-transfer-encoding"]= "BASE64",
        ["content-type"]= "text/plain; charset='utf-8'",
    },

    body= mime.b64(args.body)
}

local ret, err = smtp.send {
    from= args.from or config.mail.FROM,
    rcpt= rcpts,
    user= args.user or config.mail.USER,
    password= args.password or config.mail.PASSWORD,
    server= args.server or config.mail.SERVER,
    domain= args.domain or config.mail.DOMAIN,
    source= smtp.message(mesgt),
}

NOTICES:

• ngx.tcp.socket uses Nginx's builtin and nonblocking DNS resolver to resolve domain names IF you configure server field with hostname instead of IP address. SEE doc of Nginx directive resolver for more information.

TODO

• Don't abort the whole SMTP request while one of the many recipients invalid;
• To reimplement MIME-relative pure-lua version low-level filters with FFI?
• To implement filter mime.unew;
• To Reduce namespace pollution by module();

Performance

Your SMTP server is the bottleneck. :)

Known Issues

• Only work with LuaJIT 2.x now, because the codebase relies on pcall massively and lua-nginx-module does not work well with standard Lua 5.1 VM under this situation. See Known Issues