Lua Functions Reference


Name Description
msys.db.execute Execute a query that is not expected to return data
ac:esmtp_capability_add Add a capability to the EHLO response
ac:esmtp_capability_remove Remove a capability string from the EHLO response
ac:inbound_session_count Return the current inbound session count to this listener for the connecting IP
msys.cloudmark.analyze Analyze a message using Cloudmark
msys.cloudmark.add_af_data Pass data for use with the Cloudmark ActiveFilter.
msys.cloudmark.score Scan messages using Cloudmark
msys.cloudmark.score_af Set the Cloudmark ActiveFilter score threshold
msys.cloudmark.set_af_mode_discard Set the Cloudmark ActiveFilter mode to DISCARD.
msys.cloudmark.set_af_mode_keep Set the Cloudmark ActiveFilter mode to KEEP.
msys.cloudmark.set_af_mode_movemsg Set the Cloudmark ActiveFilter mode to MOVEMSG.
msys.cloudmark.set_af_msi_address Set the address for the Cloudmark ActiveFilter MSI Messages.
msys.apn.apn_status_classifier Determine whether the delivery status code represents a permanent or temporary failure
client:do_request Perform an HTTP request
client:get_body Get the body of an HTTP response
client:get_headers Get HTTP headers
client:get_status Return the status of an HTTP request
sess:request_add_header Add a header to an HTTP session
sess:request_delete_header Delete a header from an HTTP session
sess:request_finalize Finalize changes to an HTTP request
sess:request_set_body Set the body of an HTTP session
msys.httpclnt.http_status_classifier Determine the delivery status of the "DLV_Response_Status" variable
msys.http.client.new Create an HTTP client
client:parse_headers Parse the headers of an HTTP response
client:set_header Set an HTTP header
client:set_timeout Set the timeout for an HTTP client
c:close Close a curl object
c:perform Perform the file transfer
c:setopt Set the option value of a curl object
curl.escape URL encode a string
curl.new Create a cURL object
curl.unescape Unescape URL encoding in strings
msys.core.dns_get_domain Get a domain record
msys.core.get_now_ts Get the current time
msys.core.mail_queue_delay_domain Add a domain record to the delayed queue
msys.core.string_new Create an ec_string
msg:code Get or set the message code
msg:get_envelope2 Get envelope values
msg:header Manipulate message headers
msg:listener_addr Get the recv_via IP and/or PORT.
msg:reception_peer Get the recv_from IP and/or PORT.
msg:context_delete Delete a context variable
msg:context_exists Check if a context variable exists
msg:context_exists_and_get Check if a context variable exists and get it
msg:context_get Get a context variable
msg:context_set Sets a context variable
msgpart:unlink Remove the part (and its children) from the MIME tree
msys.core.io_wrapper_open Open a handle to a resource
msys.cast Cast an object to the specified class
msys.config Set or get configuration values
msys.dnsLookup Perform a DNS lookup
msys.expandMacro Expand macros (such as sieve, spf and custom_logger macros)
msys.getClassMetaTable Return the metatable for the named class
msys.httpsrv.register Register a Lua function as an HTTP endpoint
msys.idn.to_idn Attempts to convert the domain to the IDN format
msys.idn.to_utf8 Converts an IDN formatted string to unicode
msys.lock The current running OS level thread obtains a lock on the named mutex
msys.parseRFC2822Addresses Parse the address string per the address parsing rules defined in RFC2822
msys.readfile Read the entire contents of the specified file or URI
msys.registerAuth Register an authentication/authorization scheme that can be used for SMTP or control channel authentication
msys.registerControl Register a command with the control channel subsystem
msys.registerModule Register a Lua module with the system.
msys.runInPool Run a function in a separate threadpool
msys.sleep When called in the scheduler thread, suspend the current session for the specified duration
msys.snmpTrap Issue an SNMP trap
msys.type Return the type name of the supplied parameter
msys.unlock Release a lock obtained via msys.lock
session:request_url_get Get the request URL
session:response_status_set_std Set the HTTP status for the session response
json.decode Create a JSON object from a JSON string
json.encode Convert a Lua variable or an expression for use with a JSON object
json.new Create an empty JSON object
json.strerror Return the description of a JSON error code
msg.batch_id Return the human-readable ec_message.batch_id
msg.conn_id Return the human-readable ec_message.conn_id
msg.id Return the human-readable ec_message.id
msg:address_header Returns address components as an array
msg:binding Set or get the message binding
msg:binding_group Sets the binding_group to the named binding, if one is provided.
msg:body Set the message body (minus headers) if provided
msg:body_match Streaming interface to a PCRE search of a message body (minus headers)
msg:body_replace Streaming interface to a PCRE replacement of a message body (minus headers)
msg:build Create a message
msg:discard Silently discard a message
msg:forward Forward the current message to recipients other than the original recipients
msg:get_delivery_method Return the delivery method for a message
msg:get_message_size Return the size of a message
msg:inject Use this function to send mail
msg:is_mcmt Determine whether a message is a MCMT message
msg:mailfrom Sets the 'MAIL FROM' email address if one is provided
msg:makeBoundary Generates a unique boundary string
msg:makeContainer Creates a new, unlinked, container message part
msg:makePart Creates a new, unlinked, singleton (or leaf) message part
msg:mime Returns the top of the MIME tree for the message, a message part
msg:raw Set or returns the message content
msg:raw_match Streaming interface to a PCRE search of the message content
msg:raw_replace Streaming interface to a PCRE replacement of message content
msg:rcptto Sets the 'RCPT TO' email address if one is provided
msg:routing_domain Set or return the routing domain for a message
msg:text Return the transfer decoded text for the body
msg:text Replace the entire message body
msg:text_match Streaming PCRE search across the transfer-decoded, UTF-8 text version of the message body
msg:text_replace Streaming interface to a PCRE replacement of textual content from the message body
msgpart:addFirstChild Adds a child as the first child on this part
msgpart:addLastChild Adds a child as the last child on this part
msgpart:address_header Parse each instance of the named header for RFC2822 addresses
msgpart:body_match Streaming interface to a PCRE search of a message body part (minus headers)
msgpart:body_replace Streaming interface to a PCRE replacement of a message body part (minus headers)
msgpart:content_type Returns a table of content type related information
msgpart:header Return an array of header values for the given name
msgpart:header Unset the header name of the current message part
msgpart:header If mode is replace (or unspecified): first deletes all other headers of that name before appending the new value to the message headers
msgpart:insertAfter Insert this part into the MIME tree after the given parameter
msgpart:insertBefore Insert this part into the MIME tree before the given parameter
msgpart:raw_match Streaming interface to a PCRE search of the current message part
msgpart:raw_replace Streaming interface to a PCRE replacement message part content
msgpart:text The entire message body part is replaced by the supplied text
msgpart:text Returns the transfer decoded text for the message part, in UTF-8
msgpart:text_match Streaming a PCRE search across the transfer decoded UTF-8 text version of the message body part
msgpart:text_replace Streaming interface to a PCRE replacement of textual content from the message body parts
msys.asyncOk Check if the current execution environment is suitable for suspend/resume operations
msys.audit.connections Return the number of connections that have occurred for a CIDR block within a configured time window
msys.audit.inbound_session_count Count connections currently established from the specified cidr to the specified service
msys.audit.receptions Return the number of receptions that have occurred for a CIDR block within a configured time window
msys.audit.rejections Return the number of rejections that have occurred for a CIDR block within a configured time window
msys.audit_series.add Adjust the counter for the current time window of a named series
msys.audit_series.count Return the total associated with the named series
msys.audit_series.define Define an audit series
msys.audit_series.remove_item Remove a counter from a named series
msys.av.engines Return a list of configured engine names in a table
msys.av.scan Perform a virus scan using the named engine
msys.av.scan_part Perform a virus scan on a specific message part using the named engine
msys.base64.decode Decode a base64 encoded string
msys.base64.encode Base64-encode a string
msys.bounce.classify Create a bounce classification for a message
msys.bounce.classify_smtp_response Create a bounce classification from SMTP response text and the domain name
msys.brightmail.scan Use Brightmail to scan messages
msys.cidr.define Define a named CIDR object
msys.cidr.query Look up address against the named CIDR
msys.cidr.reload Refresh CIDRs of type datasource and rbldnsd
msys.commtouch.diagnose Scan messages using Commtouch
msys.counter.add Add to the current value of the specified counter
msys.counter.inc Increment a counter
msys.counter.open Create a counter object
msys.counter.read Read the specified counter
msys.counter.reset Reset a counter
msys.counter.unlink Unlink a counter
msys.db.fetch_row If successful, return the first row of the query result as a table
msys.db.query Query a datasource
msys.delivery.ob_get_current_message Get the current message from the session context
msys.dumper.Dumper Dump information about an object
msys.expurgate.scan Scan using the Eleven antivirus engine
msys.gauge_cache.dec Decrement the value associated with keystring in the named cache
msys.gauge_cache.define Create a cache that can be used to maintain a set of counters
msys.gauge_cache.get Look up the value associated with keystring in the named cache
msys.gauge_cache.inc Increment the value associated with keystring in the named cache
msys.gauge_cache.remove_item Remove the value associated with keystring from the named cache
msys.gcm.gcm_classify_error Determine the delivery status of the "DLV_Response_Status" variable
msys.gcm.gcm_get_result_error_code Get the error code from the response results error
msys.pcre.match Perform a PCRE regex match operation
msys.pcre.replace Perform a PCRE replace operation
msys.pcre.split Perform a PCRE split operation
msys.os.statvfs_read Request a snapshot of the stream
msys.os.statvfs_subscribe Provide a "stream" for file system statistics (statvfs) updates
msys.qp.decode Decode a quoted-printable message
msys.qp.encode Quoted-printable encode a string
msys.rfc3464.compute_delivery_status Generate RFC3464 compliant delivery status headers
msys.rfc3464.compute_delivery_status_string Generate RFC3464 compliant delivery status headers
msys.rfc3464.create_mdn Generate an MDN from a message
msys.rfc3464.extract_delivery_status Return a table of parsed email headers
msys.rfc3464.send_mdn Generate and enqueue an MDN
msys.symantec_beik.scan Scan using BEIK
msys.threadpool.count Return the current number of thread pools
msys.threadpool.find Find a thread pool name from a job class ID or a job class ID from a thread pool name
msys.threadpool.stat Return stats regarding a threadpool
msys.timer.after execute closure after a given time
msys.timer.at execute closure at a given time
msys.timer.every execute closure every interval
msys.validate.dk.get_responsible_domain Return the domain responsible for the current message
msys.validate.dk.sign Sign a message using a Domain Key
msys.validate.opendkim.get_num_sigs Return the number of DKIM signatures
msys.validate.opendkim.get_sig Get a signature from a DKIM object
msys.validate.opendkim.get_sig_canons Fetch the canonicalizers used for a signature
msys.validate.opendkim.get_sig_domain Fetch the signing domain from a DKIM_SIGINFO object
msys.validate.opendkim.get_sig_errorstr Fetch the error associated with a DKIM signature
msys.validate.opendkim.get_sig_flags Fetch the flags associated with a DKIM signature
msys.validate.opendkim.get_sig_hdrsigned Determine whether a given header was signed
msys.validate.opendkim.get_sig_identity Fetch the identity associated with a DKIM signature
msys.validate.opendkim.get_sig_keysize Fetch the size of the key used to generate a signature
msys.validate.opendkim.get_sig_selector Fetch the selector associated with a DKIM signature
msys.validate.opendkim.get_sig_signalg Return the signing algorithm as a string
msys.validate.opendkim.sign Sign a message using OpenDKIM
msys.validate.opendkim.verify Verify a DKIM signature
thread.mutex create a new mutex
vctx:add_recipient Add an address to the recipient list for the inbound session
vctx:disconnect Disconnect the session associated with the current validation context
vctx:get Get the value of a context variable
vctx:recipient_list Return or set the current recipient list
vctx:remove_recipient Remove an address from the recipient list
vctx:set Set the value of a context variable
vctx:set_code Set the inbound disposition and response message
vctx:tarpit Issue a time cost on the inbound session
doc:root Return the root node of an XML document
doc:tostring Output a DOM document as a string
doc:xpath Perform an XPath query
node:addchild Add a child node
node:attribute Set or get the attribute of a node
node:children Return an iterator of all child nodes
node:contents Get or set a text node
node:doc Return the document object that contains the specified node
node:name Return the name of a node
node:tostring Output a node as a string
node:unlink Unlink an XML node from its DOM container
xml.parsexml Create an XML document object

This section details all Lua functions. Functions are ordered alphabetically by name.

Warning

Many Lua functions act as wrappers for C code which means that the calling code needs to take steps to ensure safety. When calling a C API, make sure that all the arguments are valid as an unexpected nil may crash the system or have other undesirable results. Additionally, the data structures returned from C APIs are often shared between C and Lua. The most important consequence of this is that arrays coming from C APIs must only be accessed with existing indices, as opposed to Lua which simply returns nil on out-of-bounds access. Failure to do this on a Lua table connected to a C array will cause the system to fail.