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	Description
mail	`EODMailMessage`	An instance of the mail message
metadata	any	User-defined data (only available through the HTTP API)
http	array	HTTP data (only available through the HTTP API)

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
sni	string	“example.com”	The SNI hostname (not always available)
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.1.3.3. http

Array item	Type	Example	Description
headers	array	[[“user-agent”, “…”],…	HTTP request headers (names are lowercase)

7.7.1.2. Functions

Actions Accept() Reject() Defer()
Logging History()
DATA, MIME and attachments EODMailMessage MIMEPart
Embedded scanning ScanDMARC()

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 code is 250 and enhanced is [2,0,0].

metadata (any) User-defined data (only available through the HTTP API)

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 code is 550 and enhanced is [5,7,1].

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 code is 421 and enhanced is [4,3,2].

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.

priority (number) The queue priority (0 - normal, 1 - high). The default is 0.

fsync (bool) Override default fsync behaviour for this specific message (for multiple recipients, true has precedence).

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.

rfc8301 (boolean) Follow RFC8301 and disable support for SHA1 signatures. The default is false.

“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.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.