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

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.