esi-smtp

A library for sending a mail using the simple mail transfer protocol via socket.smtp, wincurl or luacurl.

Changes

version date description

1.0.1

2020-12-08

TFS code synchronisation

1.1.0

2021-06-10

Implemented mail attachments for LCURL

1.2.0

2023-10-17

Improvements for sending emails to multiple recipients

Dependencies

library version inmation core library

lcurl

0.3.9

yes

esi-string

1.0.3

yes

Available functions

All functions have to be called according to the ESI standard, using colons, e.g. lib:FUNCTIONNAME(params)

Documentation

SETMAILSERVERACCOUNT

SETMAILSERVERACCOUNT(user,pw,server,port,sendmode,ssl,sslurl)

Mandatory function to setup the sending requirements

Parameters

user

The user account of the sender

pw

Password of the user account. If no password is required by the SMTP server, provide a dummy password

server

The mailserver

port

The port of the server, commonly 25, 587 or 465

sendmode

The sendmode sets which sending method should be taken (CURL, LCURL or LUASMTP)

Sending attachments is only supported in the LCURL sendmode.
ssl

Enables or disables ssl requiring

sslurl

Determines if the smtps url variant should be used (smtps:// instead of smtp://)

Usage

lib:SETMAILSERVERACCOUNT("myuser@mydomain.com", "anyPass", "smtp.whatever.com", 25, lib.SENDMODE.CURL, true, false)

SETMAILINGLIST

SETMAILINGLIST(name,rcps)

Register a mailing list that can be used using lib:SENDLIST. Alternatively use lib:SEND and provide an array of recipients.

Parameters

name

The name of the mailing list

rcps

The recipients as a table

Usage

lib:SETMAILINGLIST("list", { "myemail@addres.one", "myemail@address.two" })

SEND

SEND(rcps,subj,content[,attachments])

The executing function to send emails

Parameters

rcps

Either a string for a single recipient or an array for multiple recipients

subj

The subject of the mail

content

The mail content in Hyper Text Markup Language (HTML)

attachments

A lua table object which holds lua objects in a specific format. Read below for more details.

Attachments are only supported by the LCUR sendmode.

Returns

For CURL and LUASMTP a code of '1' is returned in case of success, otherwise a nil and an error message. For LCURL the SMTP response code is returned and an error message in case of an error.

Usage

local respone, error = lib:SEND("myname@mydomaing.com", "My subject", "<p>My HTML code </p>")
if error then return error else return response end

LCURL: Sending mails with attachments

When using LCURL to send mails, starting from version 1.1.0 you can attach and/or embed file into mails.

lib:SEND accepts a 4th parameter "attachments" when sendmode is set to LCURL in SETMAILSERVERACCOUNT.

Attachments are defined as lua object with following structure

name description

filename

The name of the file including extension

mime

The MIME which defines the data format of the attachment according to RFC822

encoding

Defines how the content got encoded

content

The content of the attachment

local attachments = {}
table.insert(attachments, {
    filename = "example.png",
    mime = "image/png",
    encoding = "base64",
    content = myB64String
})

table.insert(attachments, {
    filename = "systemlogs.json",
    mime = "application/json",
    content = json.encode(syslib.getlogs(syslib.now() - 10 * 60 * 1000 , syslib.now()))
})

local html =
[[<html>
<body>
    <div>
        <p>This is an automated message</p>
        ![](cid:example.png){ width=1000 height=700 }
        <p>Cheers, Robot</p>
    </div>
</body>
</html>]]

local res, err = lib:SEND("myname@mydomaing.com", "My subject", html, attachments)

SENDLIST

SENDLIST(name,subject,content)

The executing function to send emails using a self defined mailing list

Parameters

name

The name of the mailing list

subj

The subject of the mail

content

The mail content in Hyper Text Markup Language (HTML)

Returns

A response message, otherwise returns a error message

Usage

local respone, error = lib:SENDLIST("listname", "My subject", "<p>My HTML code </p>")
if error then return error else return response end