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

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.