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

Note

This script type is only available in the FreeBSD VM packaging.

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

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

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

eodrcpt.Delete([options])

Delete the message (and return 250).

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

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

history (string) If set to “deliver”, log message as being delivered in the builtin History.

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

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.2. 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.2.1. 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.

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.2.2.3. Miscellaneous

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.4. 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(). Key names starting with a “_” (underscore) is reserved for Halon’s internal use.

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