7.7.1. Per message

The per-message end-of-DATA script is executed once, when the message is fully received (but not yet accepted). To relay the message for all recipients, call EODMailMessage.queue() for each $transaction["recipients"] and then Accept().

7.7.1.1. Variables

These are the pre-defined variables available.

Variable Type Read-only Description
$arguments array yes Context/hook arguments
$connection array yes Connection/session bound
$transaction array yes Transaction bound
$context any no Connection bound user-defined (default none)

7.7.1.1.1. Arguments

Array item Type Example Description
mail EODMailMessage   An instance of the mail message

7.7.1.1.2. Connection

Array item Type Example Description
id string “18c190a3-93f-47d7-bd...” ID of the connection
remoteip string “192.168.1.11” IP address of the connected client
remoteport number 41666 TCP port of connected client
remoteptr string “mail.example.org” Reverse DNS (FCrDNS) for remoteip (not always available)
remoteuid number 106 UNIX socket remote user id (not always available)
localip string “10.0.0.1” IP address of the server
localport number 25 TCP port of the server
serverid string “inbound” ID of the server
helo array   HELO information (not always available)
tls array   TLS information (if TLS was started)
auth array   AUTH information (not always available)

7.7.1.1.2.1. HELO

Array item Type Example Description
verb string “EHLO” HELO or EHLO command
host string “mail.example.com” HELO hostname

7.7.1.1.2.2. TLS

Array item Type Example Description
protocol string “TLSv1.3” The protocol
cipher string “ECDHE-RSA-AES256-SHA384” The cipher
keysize number 256 The keysize
peercert array   The peer certificate (if provided by the client)
7.7.1.1.2.2.1. Peercert
Array item Type Example Description
x509 X509Resource   An X509Resource to be used with the X509 class
error number 18 The peer certificate validation error (see OpenSSLs SSL_get_verify_result(3))

7.7.1.1.2.3. AUTH

Array item Type Example Description
mechanism string “PLAIN” SASL mechanism (always in uppercase)
username string “mailuser” SASL username (not always available)

7.7.1.1.3. Transaction

Array item Type Example Description
id string “18c190a3-93f-47d7-bd...” ID of the transaction
ts number 1575558785.1234 Unix time of transaction
sender string “test@example.org” Sender address (envelope), lowercase
senderaddress array [“localpart” => “test”...] Sender address (envelope)
senderparams array [“SIZE” => “2048”, ... ] Sender parameters to the envelope address (keys will always be in uppercase)
recipients array [recipient, ...] List of all accepted recipients (envelope), in order of scanning

7.7.1.1.3.1. Recipient

Array item Type Example Description
recipient string “test@example.com” Recipient address (envelope), lowercase
address array [“localpart” => “test”...] Recipient address (envelope)
params array [“NOTIFY” => “NEVER”, .. ] Recipient parameters to the envelope address (keys will always be in uppercase)
transportid string “inbound” Transport ID for recipient

7.7.1.1.3.2. Address

Array item Type Example Description
localpart string “test” Local part of address
domain string “example.org” Domain part of address

7.7.1.2. Functions

7.7.1.2.1. Actions

eodonce.Accept([options])

Accept the DATA command (mail data).

Returns:doesn’t return, script is terminated

The following options are available in the options array.

  • reason (string or array) The reason to report. The default is a system generated message.
  • reply_codes (array) The array may contain code (number) and enhanced (array of three numbers). The default is pre-defined.
eodonce.Reject([reason[, options]])

Reject (550) a message.

Parameters:
  • reason (string or array) – reject message with reason
  • options (array) – an options array
Returns:

doesn’t return, script is terminated

The following options are available in the options array.

  • disconnect (boolean) Disconnect the client. The default is false.
  • reply_codes (array) The array may contain code (number) and enhanced (array of three numbers). The default is pre-defined.
eodonce.Defer([reason[, options]])

Defer (421) a message.

Parameters:
  • reason (string or array) – defer message with reason
  • options (array) – an options array
Returns:

doesn’t return, script is terminated

The following options are available in the options array.

  • disconnect (boolean) Disconnect the client. The default is false.
  • reply_codes (array) The array may contain code (number) and enhanced (array of three numbers). The default is pre-defined.

7.7.1.2.2. Logging

eodonce.History(action, recipient[, options])

Add an entry to the history database table. This function is only available in the full system distribution (virtual machine) package. For long-term logging in high volume systems, remote logging to an external database such as Elasticsearch is recommended.

Parameters:
  • action (string) – the logged action; either of REJECT, DELETE, DELIVER, DEFER or ERROR
  • recipient (string or array) – the recipient email address, either as a string or an associative array with a localpart and domain
  • options (array) – an options array
Returns:

true (or none)
Return type:

boolean or none

The following options are available in the options array.

  • sender (string or array) the sender email address, either as a string or an associative array with a localpart and domain. The default is $transaction["senderaddress"]
  • metadata (array) add metadata to the history entry, as a key-value pair array of strings
  • transportid (string) the transport profile ID
  • reason (string) reason message

7.7.1.2.3. DATA, MIME and attachments

class EODMailMessage : MailMessage

In the EOD once context the MailMessage class has been extended with one additional function; EODMailMessage.queue().

EODMailMessage.queue(sender, recipient, transportid[, options])

Queue the message.

Parameters:
  • sender (string or array) – the sender email address, either as a string or an associative array with a localpart and domain
  • recipient (string or array) – the recipient email address, either as a string or an associative array with a localpart and domain
  • transportid (string) – the transport profile ID
  • options (array) – an options array
Returns:

an id object (with transaction and queue)
Return type:

array

The following options are available in the options array.

  • metadata (array) Add metadata to the queued message, as a key-value pair array of strings.
  • hold (boolean) Put the message in the hold (inactive) queue. The default is false.
  • jobid (string) Assign a jobid the message.
  • quotas (array) An array of quotas to be associated with the message, for use with queue_quota().
  • delay (number) Delay the first delivery attempt, in seconds. The default is 0.
  • dsn (array) Associative array of envid (string), ret (string), notify (string) and orcpt (string).

7.7.1.2.4. DKIM

These are DKIM-related functions, including DMARC. Other modules, such as ARC, is available in the authentication folder of the script library.

eodonce.ScanDMARC([options])

Returns the DMARC policy to apply to the message for the From-address. It will return an associative array containing the domain as result. If the domain cannot be properly extracted or missing an error message will be returned.

Parameters:options (array) – options array
Returns:associative array containing the domain and result or an error.
Return type:array or string

The following options are available in the options array.

  • ip (string) Override the client ip for SPF lookup.
  • helo (string) Override the helo host for SPF lookup.
  • domain (string) Override the mail from domain for SPF lookup.
“permerror” An unknown error occurred (more details may be available in the log)
[“example.com” => “temperror”] A temporary error occurred (but the domain was known)
[“example.com” => “policy_absent”] No DMARC policy for domain
[“example.com” => “pass”] The DMARC passed
[“example.com” => “none”] The policy resulted in none
[“example.com” => “reject”] The policy resulted in reject
[“example.com” => “quarantine”] The policy resulted in quarantine

7.7.1.2.5. Embedded content scanning

These functions scan the message file using various engines. While the DLP engine dlpd is included in all software packages, the embedded anti-spam and anti-virus engines are available in the integrations library.

eodonce.ScanDLP([patterns[, options]])

Scan a message using the builtin DLP engine.

Parameters:
  • patterns (array) – array of pre-configured rules or an array of custom rules
  • options (array) – options array
Returns:

all patterns found (may include ERR_ rules even if not explicitly given in the patterns argument)
Return type:

array

The following options are available in the options array.

  • stop_on_match (boolean) processing the mail when one match (of the requested type) is found. The default is false.
  • timeout (number) set an approximate timeout time in seconds. The default in no timeout.
  • recursion_limit (number) how deep to dig through MIME trees, archive files (such as ZIP), etc. The default is 9.
  • partid (boolean) return a data structure with the partid where the pattern is found. The default is false.
  • extended_result (boolean) Return extended results. The default is false.

The following results are available in the extended results array.

  • rules (array) The rules matched

On error the following items are available.

  • error (boolean) Indicates if there was an error during the scanning

The patterns array may either be an array of pre-configured rules by name.

["RULE1", "RULE2", ...]

Or a custom rule with the patterns provided. A custom rule may contain multiple types (eg. filename, sha1hash etc.) with multiple patterns each. The available types may be extracted from the DLP configuration.

["RULE1" => ["filename" => ["/\\.exe$/i", "/\\.zip$/i"], "sha1hash" => ["..."]], ...]

Warning

Do not allow untrusted users to add custom regular expression, since not all regular expressions are safe. All user data should be escaped using pcre_quote() before compiled into a regular expression.

There are some builtin rules which may occur.

Builtin rules Description
ERR_UNKNOWN_ERROR An unknown error occurred (more details may be available in the log)
ERR_PASSWORD_PROTECTED The archive is password protected
ERR_RECURSION_LIMIT The archive is too nested

7.7.1.3. On script error

On script error Defer() is called.

7.7.1.4. On implicit termination

If not explicitly terminated then Defer() is called and no recipients will be queued.