7.7.2. Per recipient¶

The per-recipient end-of-DATA script is executed once for every recipient when the message is fully received (but not yet accepted). If different actions are performed, the response code and message (sent back to the client) will be chosen in the order of reject (5XX), defer (4XX), quarantine, delete (250) and deliver (250).

7.7.2.1. Variables¶

These are the read-only pre-defined variables available for each recipient (on a message).

7.7.2.1.1. Connection¶

Variable	Type	Example	Description
$senderip	string	“192.168.1.11”	IP address of the connected client
$senderport	number	41666	TCP port of connected client
$serverip	string	“10.0.0.1”	IP address of the server
$serverport	number	25	TCP port of the server
$serverid	string	“mailserver:1”	ID of the server
$senderhelo	string	“mail.example.com”	HELO hostname of sender
$tlsstarted	boolean	false	Whether or not the SMTP session is using TLS
$saslauthed	boolean	true	Whether or not the SMTP session is authenticated (SASL)
$saslusername	string	“mailuser”	SASL username

These are the writable pre-defined variables available.

Variable	Type	Description
$context	any	Connection-bound variable

7.7.2.1.2. Transaction¶

Variable	Type	Example	Description
$messageid	string	“18c190a3-93f-47d7-bd...”	ID of the message
$sender	string	“test@example.org”	E-mail address of sender (envelope)
$senderlocalpart	string	“test”	Local part of sender’s address (envelope)
$senderdomain	string	“example.org”	Domain part of sender’s address (envelope)
$senderparams	array	[“SIZE” => “2048”, ... ]	Sender parameters to the envelope address (keys will always be in uppercase)
$recipientdomains	array	[“example.com”, ...]	List of all domain part of all recipient addresses (envelope)
$recipients	array	[“test@example.com”, ...]	List of all recipient addresses (envelope), in order of scanning

7.7.2.1.3. Arguments¶

Variable	Type	Example	Description
$recipient	string	“test@example.com”	Email address of recipient (envelope), lowercase
$recipientlocalpart	string	“test”	Local part of recipient’s address (envelope)
$recipientdomain	string	“example.com”	Domain part of recipient’s address (envelope)
$recipientparams	array	[“NOTIFY” => “NEVER”, .. ]	Recipient parameters to the envelope address (keys will always be in uppercase)
$transportid	string	“mailtransport:1”	ID of the transport profile to be used
$actionid	number	1	ID; incremented per message action/recipient (Deliver, Quarantine, etc.)

7.7.2.2. Functions¶

Actions Deliver() Reject() Defer() Delete() Quarantine() Done()
DATA, MIME and attachments GetMailMessage()
Embedded scanning ScanDMARC() ScanDLP()
Miscellaneous GetTLS()
Arguments SetRecipient() SetMailTransport() SetDelayedDeliver() SetMetaData() GetMetaData() SetSender() SetSenderIP() SetSenderHELO()
Headers GetHeader() GetHeaders() AddHeader() SetHeader() PrependHeader() AppendHeader() DelHeader()

7.7.2.2.1. Actions¶

eodrcpt.Deliver([options])¶

Queue or deliver the message.

Parameters:	options (array) – an options array
Returns:	doesn’t return, script is terminated
Updates:	`$actionid`

The following options are available in the options array.

recipient (string or array) Set the recipient email address, either as a string or an associative array with a localpart and domain. The default is $recipientlocalpart and $recipientdomain.

transportid (string) Set the transport ID. The default is $transportid.

metadata (array) Add additional metadata (KVP). Same as SetMetaData().

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) Same as SetDelayedDeliver(). The default is 0 seconds.

done (boolean) If the function should terminate the script. Same as calling Done(). The default is true.

queue (boolean) Deliver the message using the queue. The default is true.

disconnect (boolean) Disconnect the client. The default is false.

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.

dsn (array) Associative array of envid (string), ret (string), notify (string) and orcpt (string).

eodrcpt.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
Updates:	`$actionid`

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.

eodrcpt.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
Updates:	`$actionid`

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.

eodrcpt.Delete()¶

Delete the message (and return 250).

Returns:	doesn’t return, script is terminated
Updates:	`$actionid`

eodrcpt.Quarantine(quarantineid[, options])¶

Quarantine or archive the message, by putting it in the hold queue.

Parameters:	quarantineid (string) – the quarantine profile ID options (array) – an options array
Returns:	doesn’t return, script is terminated
Updates:	`$actionid`

The following options are available in the options array.

recipient (string or array) Set the recipient email address, either as a string or an associative array with a localpart and domain. The default is $recipientlocalpart and $recipientdomain.

transportid (string) Set the transport ID. The default is $transportid.

metadata (array) Add additional metadata to the message (KVP). same as SetMetaData().

jobid (string) Assign a jobid the message.

quotas (array) An array of quotas to be associated with the message, for use with queue_quota().

done (boolean) If the function should terminate the script. Same as calling Done(). The default is true.

reject (boolean) If the function should return an 500 error. The default is true.

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.

dsn (array) Associative array of envid (string), ret (string), notify (string) and orcpt (string).

eodrcpt.Done()¶

Finishes the execution of the current recipient without doing an additional action. If a message is scanned without any action, it will be deferred.

Returns:	doesn’t return, script is terminated

7.7.2.2.1.1. DATA, MIME and attachments¶

eodrcpt.GetMailMessage()¶

Returns:	A MailMessage reference
Return type:	`MailMessage`

This is a “factory function” which returns a MailMessage object reference to the DATA (message) received as the result of the End-of-DATA command.

GetMailMessage()->appendPart(
        MIME()
                ->setType("multipart/alternative")
                ->appendPart(
                        MIME()
                                ->setType("text/plain")
                                ->setBody("This is a custom footer")
                        )
                ->appendPart(
                        MIME()
                                ->setType("multipart/related")
                                ->appendPart(
                                        MIME()
                                                ->setType("text/html")
                                                ->setBody("This is a custom footer with an image <img src='cid:logo.png'>")
                                )
                                ->appendPart(
                                        MIME()
                                                ->setType("image/png")
                                                ->addHeader("Content-ID", "logo.png")
                                                ->setBody(
                                                        cache [ "ttl" => 3600 * 24 * 7 ]
                                                                http("https://pbs.twimg.com/profile_images/656816032930119680/52m1eugJ.jpg")
                                                )
                                )
                        )
);

7.7.2.2.1.2. DKIM¶

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

eodrcpt.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.2.2.1.3. 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.

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

eodrcpt.GetTLS([options])¶

Get the TLS information for a connection.

Parameters:	options (array) – options array
Return type:	array

The following options are available in the options array.

fingerprint (string) Generate the fingerprint of the certificate using one of the following hash function (md5, sha1, sha256 or sha512). The default no hashing.

The following items are available in the result.

started (boolean) If STARTTLS was issued.

protocol (string) The protocol used (eg. TLSv1.2)

cipher (string) The cipher used (eg. ECDHE-RSA-AES256-SHA384).

keysize (number) The keysize used (eg. 256).

peer_cert (array) The peer certificate (if provided by the client). Same format as TLSSocket.getpeerx509().

peer_cert_error (number) The peer certificate validation error (see OpenSSLs SSL_get_verify_result(3)).

7.7.2.2.2. Arguments¶

Those functions update the current recipient execution ($actionid) arguments, which is used by action functions such as Deliver().

eodrcpt.SetRecipient(recipient)¶

Changes the recipient.

Parameters:	recipient (string or array) – an email address, either as a string or an associative array with a `localpart` and `domain`
Returns:	recipient if successful
Return type:	string or none
Updates:	`$recipient`, `$recipientlocalpart` and `$recipientdomain`

eodrcpt.SetMailTransport(id)¶

Changes the transport profile.

Parameters:	id (string) – the transport ID to be used
Return type:	none
Updates:	`$transportid`

eodrcpt.SetDelayedDeliver(delay)¶

If the message is queued, the first delivery attempt is delayed.

Parameters:	delay (number) – delay in seconds
Return type:	none

eodrcpt.SetMetaData(metadata)¶

Set the metadata for the the current, and subsequent, recipient(s). The metadata must be an array with both string keys and values.

Parameters:	metadata (array) – metadata to set
Return type:	none

SetMetaData(["foo" => "bar", "foo2" => json_encode(["array", 123.45, false])]);

Note

To work-around the data type limitation of the metadata; data can be encoded using json_encode().

eodrcpt.GetMetaData()¶

Get the metadata set by SetMetaData(). If no data was set, an empty array is returned.

Returns:	the data set by `SetMetaData()`
Return type:	array

eodrcpt.SetSender(sender)¶

Change the sender.

Parameters:	sender (string or array) – an email address, either as a string or an associative array with a `localpart` and `domain`
Returns:	sender if successful
Return type:	string or none
Updates:	`$sender`, `$senderlocalpart` and `$senderdomain`

eodrcpt.SetSenderIP(ip)¶

Change the connecting client’s IP.

Parameters:	ip (string) – an IP address
Returns:	ip if successful
Return type:	string or none
Updates:	`$senderip`

eodrcpt.SetSenderHELO(hostname)¶

Change the connecting client’s HELO hostname.

Parameters:	hostname (string) – a hostname
Returns:	hostname if successful
Return type:	string or none
Updates:	`$senderhelo`

7.7.2.2.3. Headers¶

These functions operate on message headers, just like MIMEPart.

eodrcpt.GetHeader(name[, decode = true])¶

Return the value of a header (if multiple headers with the same name exists, the first will be returned). The name is not case sensitive.

Parameters:	name (string) – name of the header decode (boolean) – if false, the header will not be decoded
Returns:	header value
Return type:	string

eodrcpt.GetHeaders(name[, decode = true])¶

Return the value of all headers with the name. If name is boolean true, all headers will be returned. The name is not case sensitive.

Parameters:	name (string) – name of the header decode (boolean) – if false, the header will not be decoded
Returns:	headers’ values
Return type:	array

eodrcpt.AddHeader(name, value[, refold = true])¶

Add a new header (at the top of the message).

Parameters:	name (string) – name of the header value (string) – value of the header refold (boolean) – refold header to 80 characters per line
Return type:	none

eodrcpt.SetHeader(name, value[, refold = true])¶

Overwrite existing header(s) or create a new header. The name is not case sensitive.

Parameters:	name (string) – name of the header value (string) – value of the header refold (boolean) – refold header to 80 characters per line
Returns:	number of headers changed
Return type:	number

eodrcpt.PrependHeader(name, value[, refold = true])¶

Prepend to existing header(s) or create a new header. The name is not case sensitive.

Parameters:	name (string) – name of the header value (string) – value of the header refold (boolean) – refold header to 80 characters per line
Returns:	number of headers changed
Return type:	number

eodrcpt.AppendHeader(name, value[, refold = true])¶

Append to existing header(s) or create a new header. The name is not case sensitive.

Parameters:	name (string) – name of the header value (string) – value of the header refold (boolean) – refold header to 80 characters per line
Returns:	number of headers changed
Return type:	number

eodrcpt.DelHeader(name)¶

Delete all headers by the name. The name is not case sensitive.

Parameters:	name (string) – name of the header
Returns:	number of headers deleted
Return type:	number

7.7.2.3. On script error¶

On script error Defer() is called.

7.7.2.4. On implicit termination¶

If not explicitly terminated then Deliver() is called.