Common Macros

From ESM Wiki
Jump to: navigation, search

The following macros can be used in templates and conditions of all engines:

$attachment
$attachment.base64
$attachment.headers
$attachment.text
$attachment.malformed
$attachment.multipart
$attachment.resource_fork
$attachment.resource_fork.base64
$attachment.file_name
$attachment.mime_type
$body
$body.html
$body_part
$body_part.base64
$body_part.is_body
$body_part.is_attachment
$body_part.size
$body_part.headers
$body_part.text
$body_part.malformed
$body_part.multipart
$body_part.file_name
$body_part.mime_type
$body_part.digest
$body_part.resource_fork
$body_part.resource_fork.size
$body_part.resource_fork.digest
$current_time

$data
$data.size
$data.digest
$decode_base64
$decrypt_eb64
$embedded.ch_wbl.result
$embedded.spam_traps.result
$embedded.wbl.result
$embedded.spf.result
$embedded.rbl.result
$embedded.rbl.site
$embedded.rbl.reason
$embedded.greylist.result
$empty
$encode_base64
$exception
$globals_set
$globals_append
$globals_get
$globals_defined
$json_escape
$header
$header.name
$header.body
$header_is_present_by_name
$header_body_by_name
$headers
$headers.address

$headers.address.domain
$headers.address.domain.part
$headers.address.local
$headers.address.name
$headers.address.type
$headers.date
$headers.date.timestamp
$headers.message_id
$headers.in_reply_to
$headers.references
$headers.from
$headers.from.local
$headers.from.domain
$headers.from.domain.part
$headers.from.name
$headers.sender
$headers.sender.local
$headers.sender.domain
$headers.sender.domain.part
$headers.sender.name
$headers.reply_to
$headers.reply_to.local
$headers.reply_to.domain
$headers.reply_to.domain.part
$headers.reply_to.name
$headers.return_path
$headers.return_path.local
$headers.return_path.domain

$headers.return_path.name
$headers.return_path.domain.part
$headers.fake_sender
$headers.fake_sender.local
$headers.fake_sender.domain
$headers.fake_sender.name
$headers.to
$headers.to.local
$headers.to.domain
$headers.to.domain.part
$headers.to.name
$headers.cc
$headers.cc.local
$headers.cc.domain
$headers.cc.domain.part
$headers.cc.name
$headers.bcc
$headers.bcc.local
$headers.bcc.domain
$headers.bcc.domain.part
$headers.bcc.name
$headers.subject
$hmac
$host
$ip
$ip.dec
$ip.hex
$if_not_empty

$gethostname
$group
$math_sum
$message_id
$md5
$not_empty
$pid
$recipient
$recipient.local
$recipient.domain
$recipient.domain.part
$recipient.component
$result
$sender
$sender.local
$sender.domain
$sender.domain.part
$sender.component
$sha1
$size
$size_hex
$sp, $br, $cr, $lf, $crlf, $htab
$subject
$tag.name
$tag.value
$text_find_replace_all
$text_map

$text_pad_left
$text_size
$text_truncate
$thread
$time
$time6
$timezone, $timezone.sign,
$timezone.hh, $timezone.mm,
$timezone.ss

$uri_escape
$wait
$wrap
$xml_cdata
$xml_escape
$xml_date
$xml_time
$xml_dateTime
$year, $month, $day,
$hour, $minute, $second

$attachment

Description: Email attachment data. Attachment is every body part that is not body in body-attachments-view typical for MUA's.
Dimension: $attachment
Stage: smtp-end-of-data

$attachment.base64

Description: Email attachment data encoded as base64. Using this macro may be more effective then using ${encode_base64 $attachment} in most cases because attachment data in email is likely to be already encoded as base64.
Dimension: $attachment
Stage: smtp-end-of-data

$attachment.headers

Description: Email attachment headers as single string.
Dimension: $attachment
Stage: smtp-end-of-data

$attachment.text

Description: Text extracted from email attachment and converted to utf-8 encoding. This macro is intended to extract pure text from different types of documents for this text to be used in content analyzing tools. Though currently this macro is fully equivalent to $attachment it will be enhanced to support as much types of documents as possible.
Dimension: $attachment
Stage: smtp-end-of-data

$attachment.malformed

Description: Flag that indicates whether attachment is malformed from MIME point of view. It has two values: "yes" and "no". When attachment is malformed its data will be empty. One should use this flag to exclude malformed attachments from processing to avoid lost of data in scenarios like attachment stripping. For example:
<engines>
  <file>
    <save>
      <precondition>$attachment.malformed $EQ no</precondition>
      ...
    </save>
  </file>
</engines>
Dimension: $attachment
Stage: smtp-end-of-data

$attachment.multipart

Description: Flag that indicates whether attachment is a legacy Apple file that consists from data and resource forks. It has two values: "yes" and "no". When attachment is multipart its $attachment.resource_fork may be not empty. One should use this flag to exclude multipart attachments from processing to avoid lost of data in scenarios like attachment stripping. For example (in combination with malformed flag):
<engines>
  <file>
    <save>
      <precondition>$attachment.malformed $EQ no $AND $attachment.multipart $EQ no</precondition>
      ...
    </save>
  </file>
</engines>

However it is expected that such file format is depricated thus will rarely appear in emails.

Dimension: $attachment
Stage: smtp-end-of-data

$attachment.resource_fork

Description: Resource fork of legacy Apple file that consists from data and resource forks. It is expected that such file format is depricated thus will rarely appear in emails.
Dimension: $attachment
Stage: smtp-end-of-data

$attachment.resource_fork.base64

Description: Base64 encoded resource fork of legacy Apple file that consists from data and resource forks. Using this macro may be more effective then using ${encode_base64 $attachment.resource_fork} in most cases because attachment data in email is likely to be already encoded as base64. It is expected that such file format is depricated thus will rarely appear in emails.
Dimension: $attachment
Stage: smtp-end-of-data

$attachment.file_name

Description: File name of an attachment as extracted from headers and converted to utf-8. Will be empty if no file name is specified in headers.
Dimension: $attachment
Stage: smtp-end-of-data

$attachment.mime_type

Description: MIME type of an attachment as extracted from headers. Will be empty if no MIME type is specified in headers.
Dimension: $attachment
Stage: smtp-end-of-data

$body

Description: Email body in body-attachment-view typical for MUA's. Body is the first text body part in email or text body part in first alternative.
Stage: smtp-end-of-data

$body.html

Description: Html alternative of email body in body-attachment-view typical for MUA's. Html body is the first html body part in email or html body part in first alternative.
Stage: smtp-end-of-data

$body_part

Description: Body part of a email in body-part-view. Unlike a body-attachments-view body-part-view doesn't distinguish between body and attachments. It treats all body parts in the same manner. This is more closely corresponds to MIME standard because it doesn't distinguish body and attachments - all are body parts.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.base64

Description: Base64-encoded body part of a email. Using this macro may be more effective then using ${encode_base64 $body_part} in most cases because body part data in email is likely to be already encoded as base64.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.is_body

Description: Flag that indicates whether body part is body in body-attachments-view. It has two values: "yes" and "no". Body is the first text or html body part in email or text or html body part in first alternative.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.is_attachment

Description: Flag that indicates whether body part is attachment in body-attachments-view. It has two values: "yes" and "no". Everything that is not body is attachment.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.size

Description: Size of body part in bytes. This is deprecated because of available $size macro.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.headers

Description: Body part headers as single string.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.text

Description: Text extracted from email body part and converted to utf-8 encoding. This macro is intended to extract pure text from different types of documents for this text to be used in content analyzing tools. Though currently this macro is fully equivalent to $body_part it will be enhanced to support as much types of documents as possible.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.malformed

Description: Flag that indicates whether body part is malformed from MIME point of view. It has two values: "yes" and "no". When body part is malformed its data will be empty. One should use this flag to exclude malformed body parts from processing to avoid lost of data in scenarios like body stripping. For example:
<engines>
  <file>
    <save>
      <precondition>$body_part.malformed $EQ no</precondition>
      ...
    </save>
  </file>
</engines>
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.multipart

Description: Flag that indicates whether body part is a legacy Apple file that consists from data and resource forks. It has two values: "yes" and "no". When body part is multipart its $body_part.resource_fork may be not empty. One should use this flag to exclude multipart body parts from processing to avoid lost of data in scenarios like body stripping. For example (in combination with malformed flag):
<engines>
  <file>
    <save>
      <precondition>$body_part.malformed $EQ no $AND $body_part.multipart $EQ no</precondition>
      ...
    </save>
  </file>
</engines>

However it is expected that such file format is depricated thus will rarely appear in emails.

Dimension: $body_part
Stage: smtp-end-of-data

$body_part.file_name

Description: File name of a body part as extracted from headers and converted to utf-8. Will be empty if no file name is specified in headers.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.mime_type

Description: MIME type of a body part as extracted from headers and converted to utf-8. Will be empty if no file name is specified in headers.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.digest

Description: SHA1 digest calculated from body part data. This is deprecated because of available $sha1 macro.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.resource_fork

Description: Resource fork of legacy Apple file that consists from data and resource forks. It is expected that such file format is depricated thus will rarely appear in emails.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.resource_fork.size

Description: Size of resource fork of body part. This is deprecated because of available $size macro.
Dimension: $body_part
Stage: smtp-end-of-data

$body_part.resource_fork.digest

Description: SHA1 digest calculated from resource fork data of body part. This is deprecated because of available $sha1 macro.
Dimension: $body_part
Stage: smtp-end-of-data

$current_time

Description: Current unix time. Unlike $time macro this one is evaluated to current time at each occurrence.

$data

Description: Whole email data. Uses LF's for linebreaks.
Stage: smtp-end-of-data

$data.size

Description: Size of email data in bytes. This is deprecated because of available $size macro.
Stage: smtp-end-of-data

$data.digest

Description: SHA1 digest calculated from email data. This is deprecated because of available $sha1 macro.
Stage: smtp-end-of-data

$decode_base64

Description: Decodes data from base64 encoding.
Arguments: 1) Data to decode.

$decrypt_eb64

Description: Decryptes encrypted base64 data using keys from passwords file.
Arguments: 1) Encrypted base64 data to decrypt.

$embedded.ch_wbl.result

Description: Client Host WBL processing result. Possible values are: 'none', 'whitelist', 'blacklist' and 'tempfailure'. May have empty value in case of corresponding processing has not been run. Currently available for policy server requests.

$embedded.spam_traps.result

Description: Spam traps processing result. Possible values are: 'yes' and 'no'. May have empty value in case of corresponding processing has not been run. Currently available for policy server requests.

$embedded.wbl.result

Description: User-level WBL processing result. Possible values are: 'none', 'group_pass', 'group_reject', 'group_discard', 'acl_sender', 'acl_recipient', 'spam_whitelist' and 'blacklist'. May have empty value in case of corresponding processing has not been run. Currently available for policy server requests.

$embedded.spf.result

Description: SPF processing result. Possible values are: 'invalid', 'neutral', 'pass', 'fail', 'softfail', 'none', 'temperror' and 'permerror'. May have empty value in case of corresponding processing has not been run. Currently available for policy server requests.

$embedded.rbl.result

Description: RBL processing result. Possible values are: 'yes', 'no' and 'error'. May have empty value in case of corresponding processing has not been run. Currently available for policy server requests.

$embedded.rbl.site

Description: RBL site that indicated matched record. Macro has not empty value in case of 'yes' value of $embedded.rbl.result.

$embedded.rbl.reason

Description: Reason for record been in the list for RBL site. Macro may have not empty value in case of 'yes' value of $embedded.rbl.result.

$embedded.greylist.result

Description: Greylist processing result. Possible values are: 'first_seen', 'blocked' and 'auth'. May have empty value in case of corresponding processing has not been run. Currently available for policy server requests.

$empty

Description: Empty string.

$encode_base64

Description: Encodes data to base64 encoding.
Arguments: 1) Data to encode.
2) Maximum line length in encoded data. Optional, default is unlimited (do not break on lines).
3) Flag whether to suppress final newline. Can be "yes" or "no". Optional, default to "yes".
4) Flag whether to use CRLF's instead of LF's for newlines. Can be "yes" or "no". Optional, default to "no".

$exception

Description: Text of exception been caught. The text is an evaluated <throw> option as described in result with validation. This macro is available in exception processing sequence.

$globals_set

Description: Sets value(s) of global variable(s) with specified name(s). Returns set value or concatenation of all values if multiple variables are set.
Arguments: 2 or more even number of arguments:
Odd) variable name.
Even) variable value.

$globals_append

Description: Appends to value(s) of global variable(s) with specified name(s). Returns appended value or concatenation of all values if multiple variables are appended.
Arguments: 2 or more even number of arguments:
Odd) variable name.
Even) value to append.

$globals_get

Description: Get a value of global variable. If variable is not set it is NULL.
Arguments: 1) Variable name.

$globals_defined

Description: Evaluates to "yes" if global variable is defined and "no" othewise
Arguments: 1) Variable name.

$json_escape

Description: Escapes string to be a valid JSON string.
Arguments: One or more arguments are concatenated and then escaped.

$header

Description: Email header.
Dimension: $header
Stage: smtp-end-of-data

$header.name

Description: Email header name.
Dimension: $header
Stage: smtp-end-of-data

$header.body

Description: Email header body.
Dimension: $header
Stage: smtp-end-of-data

$header_is_present_by_name

Description: Evaluates to "yes" if email header with specified name is present. Otherwise evaluate to "no".
Arguments: 1) Header name.
Stage: smtp-end-of-data

$header_body_by_name

Description: Evaluates to email header body by header name. If multiple headers with same name are present then macro evaluates to body of first header. If no such header present macro evaluates to empty value.
Arguments: 1) Header name.
Stage: smtp-end-of-data

$headers

Description: Email headers as single string.
Stage: smtp-end-of-data

$headers.address

Description: Aggregated macro for $headers.sender, $headers.from, $headers.reply_to, $headers.to, $headers.cc and $headers.bcc
Dimension: $headers.address
Stage: smtp-end-of-data

$headers.address.domain

Description: Domain part of $headers.address.
Dimension: $headers.address
Stage: smtp-end-of-data

$headers.address.domain.part

Description: Domain part components of $headers.address. There may be multiple addresses and parts so this macro has two dimensions.
Dimension: $headers.address, $headers.address.component
Stage: smtp-end-of-data

$headers.address.local

Description: Local part of $headers.address.
Dimension: $headers.address
Stage: smtp-end-of-data

$headers.address.name

Description: Mailbox name related to $headers.address converted to utf-8 encoding.
Dimension: $headers.address
Stage: smtp-end-of-data

$headers.address.type

Description: Address type of $headers.address. It is either "Sender", "From", "Reply-To", "To", "Cc" or "Bcc".
Dimension: $headers.address
Stage: smtp-end-of-data

$headers.date

Description: Date extracted from Date email header. Will be empty if no such header.
Stage: smtp-end-of-data

$headers.date.timestamp

Description: Date as timestamp (seconds since epoch) extracted from Date email header. Will be empty if no such header.
Stage: smtp-end-of-data

$headers.message_id

Description: ID extracted from Message-ID header value.
Stage: smtp-end-of-data

$headers.in_reply_to

Description: ID extracted from In-Reply-To header value. There may be multiple ID's so this macro has dimension.
Dimension: $headers.in_reply_to
Stage: smtp-end-of-data

$headers.references

Description: ID extracted from References header value. There may be multiple ID's so this macro has dimension.
Dimension: $headers.references
Stage: smtp-end-of-data

$headers.from

Description: Address extracted from From header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.from
Stage: smtp-end-of-data

$headers.from.local

Description: Local part of address extracted from From header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.from
Stage: smtp-end-of-data

$headers.from.domain

Description: Domain part of address extracted from From header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.from
Stage: smtp-end-of-data

$headers.from.domain.part

Description: Domain part components of address extracted from From header value. There may be multiple addresses and parts so this macro has two dimensions.
Dimension: $headers.from, $headers.from.component
Stage: smtp-end-of-data

$headers.from.name

Description: Mailbox name of address extracted from From header value and converted to utf-8 encoding. There may be multiple addresses so this macro has dimension.
Dimension: $headers.from
Stage: smtp-end-of-data

$headers.sender

Description: Address extracted from Sender header value.
Stage: smtp-end-of-data

$headers.sender.local

Description: Local part of address extracted from Sender header value.
Stage: smtp-end-of-data

$headers.sender.domain

Description: Domain part of address extracted from Sender header value.
Stage: smtp-end-of-data

$headers.sender.domain.part

Description: Domain part component of address extracted from Sender header value.
Dimension: $headers.sender.component
Stage: smtp-end-of-data

$headers.sender.name

Description: Mailbox name of address extracted from Sender header value and converted to utf-8 encoding.
Stage: smtp-end-of-data

$headers.reply_to

Description: Address extracted from Reply-To header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.reply_to
Stage: smtp-end-of-data

$headers.reply_to.local

Description: Local part of address extracted from Reply-To header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.reply_to
Stage: smtp-end-of-data

$headers.reply_to.domain

Description: Domain part of address extracted from Reply-To header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.reply_to
Stage: smtp-end-of-data

$headers.reply_to.domain.part

Description: Domain part components of address extracted from Reply-To header value. There may be multiple addresses and parts so this macro has two dimensions.
Dimension: $headers.reply_to, $headers.reply_to.component
Stage: smtp-end-of-data

$headers.reply_to.name

Description: Mailbox name of address extracted from Reply-To header value and converted to utf-8. There may be multiple addresses so this macro has dimension.
Dimension: $headers.reply_to
Stage: smtp-end-of-data

$headers.return_path

Description: Address extracted from Return-Path header value.
Dimension: $headers.return_path
Stage: smtp-end-of-data

$headers.return_path.local

Description: Local part of address extracted from Return-Path header value.
Dimension: $headers.return_path
Stage: smtp-end-of-data

$headers.return_path.domain

Description: Domain part of address extracted from Return-Path header value.
Dimension: $headers.return_path
Stage: smtp-end-of-data

$headers.return_path.domain.part

Description: Domain part components of address extracted from Return-Path header value.
Dimension: $headers.return_path, $headers.return_path.component
Stage: smtp-end-of-data

$headers.return_path.name

Description: Mailbox name of address extracted from Return-Path header value and converted to utf-8.
Dimension: $headers.return_path
Stage: smtp-end-of-data

$headers.fake_sender

Description: Special macro for backward compatibility with MPP archive database scheme. This macro is calculated as following: if there is From header and it contains single address then this address is taken; else if there is Sender header then address extracted from it is taken; otherwise if there is Return-Path header and it contains single address then this address is taken; otherwise empty value is taken.
Stage: smtp-end-of-data

$headers.fake_sender.local

Description: Local part of corresponding address.
Stage: smtp-end-of-data

$headers.fake_sender.domain

Description: Domain part of corresponding address.
Stage: smtp-end-of-data

$headers.fake_sender.name

Description: Mailbox name of corresponding address. Name is converted to utf-8 encoding.
Stage: smtp-end-of-data

$headers.to

Description: Address extracted from To header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.to
Stage: smtp-end-of-data

$headers.to.local

Description: Local part of address extracted from To header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.to
Stage: smtp-end-of-data

$headers.to.domain

Description: Domain part of address extracted from To header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.to
Stage: smtp-end-of-data

$headers.to.domain.part

Description: Domain part components of address extracted from To header value. There may be multiple addresses and parts so this macro has two dimensions.
Dimension: $headers.to, $headers.to.component
Stage: smtp-end-of-data

$headers.to.name

Description: Mailbox name of address extracted from To header value and converted to utf-8 encoding. There may be multiple addresses so this macro has dimension.
Dimension: $headers.to
Stage: smtp-end-of-data

$headers.cc

Description: Address extracted from Cc header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.cc
Stage: smtp-end-of-data

$headers.cc.local

Description: Local part of address extracted from Cc header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.cc
Stage: smtp-end-of-data

$headers.cc.domain

Description: Domain part of address extracted from Cc header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.cc
Stage: smtp-end-of-data

$headers.cc.domain.part

Description: Domain part components of address extracted from Cc header value. There may be multiple addresses and parts so this macro has two dimensions.
Dimension: $headers.cc, $headers.cc.component
Stage: smtp-end-of-data

$headers.cc.name

Description: Mailbox name of address extracted from Cc header value and converted to utf-8. There may be multiple addresses so this macro has dimension.
Dimension: $headers.cc
Stage: smtp-end-of-data

$headers.bcc

Description: Address extracted from Bcc header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.bcc
Stage: smtp-end-of-data

$headers.bcc.local

Description: Local part of address extracted from Bcc header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.bcc
Stage: smtp-end-of-data

$headers.bcc.domain

Description: Domain part of address extracted from Bcc header value. There may be multiple addresses so this macro has dimension.
Dimension: $headers.bcc
Stage: smtp-end-of-data

$headers.bcc.domain.part

Description: Domain part components of address extracted from Bcc header value. There may be multiple addresses and components so this macro has two dimensions.
Dimension: $headers.bcc, $headers.bcc.component
Stage: smtp-end-of-data

$headers.bcc.name

Description: Mailbox name of address extracted from Bcc header value and converted to utf-8. There may be multiple addresses so this macro has dimension.
Dimension: $headers.bcc
Stage: smtp-end-of-data

$headers.subject

Description: Text extracted from Subject header value and converted to utf-8.
Stage: smtp-end-of-data

$hmac

Description: Calculates HMAC digest from provided data and key.
Arguments: 1) Data to calculate from.
2) Key to use.
3) Hash function to use. Optional, default to "sha1". Allowed values: "md2", "md4", "md5", "sha", "sha1", "dss", "dss1", "ecdsa", "sha224", "sha256", "sha384", "sha512", "ripemd160".

$host

Description: Host name of a client sending a request as extracted from message headers or from other sources.

$ip

Description: IP address in doted-decimal notation of a client sending a request as extracted from message headers or from other sources.

$ip.dec

Description: IP address as decimal of a client sending a request as extracted from message headers or from other sources.

$ip.hex

Description: IP address as hexadecimal of a client sending a request as extracted from message headers or from other sources.

$if_not_empty

Description: Checks if second argument is not empty, adds prefix and suffix and returns obtained value. Otherwise returns emtpy value.
Arguments: 1) Prefix.
2) Checked value.
3) Suffix.

$gethostname

Description: Result of gethostname() call. Name of the host where application is running.

$group

Description: ID of MPP policy group that request is processed with.

$math_sum

Description: Calculates a sum of its arguments. Arguments must evaluate to integers or floats otherwise exception will be thrown.
Arguments: One or more expressions that must evaluate to integers or floats.

$message_id

Description: Short equivalent to $headers.message_id.

$md5

Description: Calculates MD5 digest from data.
Arguments: 1) Data to calculate from.

$not_empty

Description: Returns first not null and not empty value from its arguments evaluating from left to right. Otherwise returns null (if all are null) or empty value. Has important property that it will be null only if ALL arguments are null. This property may be used for merging execution branches.
Arguments: One or more.

$pid

Description: Process ID of application.

$recipient

Description: SMTP recipient address.
Dimension: $recipient

$recipient.local

Description: Local part of SMTP recipient address.
Dimension: $recipient

$recipient.domain

Description: Domain part of SMTP recipient address.
Dimension: $recipient

$recipient.domain.part

Description: Domain part components of SMTP recipient address.
Dimension: $recipient, $recipient.component

$recipient.component

Description: Components of SMTP recipient address. Components are address itself and domains starting from more specific ending with less specific.
Dimension: $recipient, $recipient.component

$result

Description: Special macro that represent current result value in result with validation.

$sender

Description: SMTP sender address.

$sender.local

Description: Local part of SMTP sender address.

$sender.domain

Description: Domain part of SMTP sender address.

$sender.domain.part

Description: Domain part components of SMTP sender address.
Dimension: $sender.component

$sender.component

Description: Components of SMTP sender address. Components are address itself and domains starting from more specific ending with less specific.
Dimension: $sender.component

$sha1

Description: Calculates SHA1 digest from data.
Arguments: 1) Data to calculate from.

$size

Description: Calculates size of data in bytes.
Arguments: 1) Data to calculate from.

$size_hex

Description: Calculates size of data in bytes as hexadecimal value.
Arguments: 1) Data to calculate from.

$sp, $br, $cr, $lf, $crlf, $htab

Description: Special characters and sequences: SP, LF, CR, LF, CRLF, HTAB.

$subject

Description: Short variant of $headers.subject.

$tag.name

Description: Name of a tag currently associated with a message by previous pipeline(s). For details about tagging see result with tagging.
Dimension: $tag

$tag.value

Description: Value of a tag currently associated with a message by previous pipeline(s). For details about tagging see result with tagging.
Dimension: $tag

$text_find_replace_all

Description: In given data replaces all specified sequences with corresponding replacers. Can be used as general purpose escaping function.
Arguments: 1) Data to replace in.
Each even argument is a sequence to replace.
Each odd argument is a corresponding replacer.

$text_map

Description: Searches for a first match key in a specially formated textual map and returns corresponding value. Textual map evaluates to a string that must conform to the following format:
  • keys are listed in first line and corresponding values are listed in second line;
  • keys and values are linked positionally, for example, key number 5 corresponds to a value number 5;
  • keys are not sorted, duplicates are possible, searching for matched key is done from the begining of keys list until match if found, other matches are ignored;
  • list entries are strings quoted with ' (single quot) character, quotes are not part of values - they are markup, strings may contain escape sequences \' \\ \n \r with obvious meaning;
  • list entries may be separated by any number of any characters except ' \n \r;
  • for example real textual map may look like this:
'0038000000jGpR0AAK', '0039000000PGKR0AAK', '0048000000gGpR0AOK'
'00230000006GpU0AAK', '0034000000HGKf0AAK', '0058000000gRpRDAsK'
Arguments: 1) Key to search by.
2) Map to search in.

$text_pad_left

Description: Pads text to a specified size with a specified symbol. Pads to the left.
Arguments: 1) UTF-8 text to pad.
2) Desired number of characters in result.
3) Pad character.

$text_size

Description: Calculates number of characters in UTF-8 text.
Arguments: 1) UTF-8 text.

$text_truncate

Description: Truncate UTF-8 text to contain no more then specified number of characters. Truncation occur at the end of text. Optionally puts specified truncation sequence (such as "...") at the end of text. If truncation sequence is specified text is truncated to lower number of characters so that total number remains no more then specified number.
Arguments: 1) Text to truncate.
2) Number of characters to truncate text to.
3) Truncation sequence. Optional, default to empty.

$thread

Description: Current thread ID. Can be useful for unique ID's generation.

$time

Description: Current timestamp. Evaluated only once at first usage in a pipeline for each request and then remains the same even if actual time is changing while request is being processed.

$time6

Description: Current timestamp as compact 6-characters value. Evaluated at each usage. Can be useful for unique ID's generation.

$timezone, $timezone.sign, $timezone.hh, $timezone.mm, $timezone.ss

Description: Current timezone and its different parts. Timezone is presented in the following format +/-HH:MM (for example +02:00). Other macros are timezone parts: sign, hours, minutes, seconds.

$uri_escape

Description: Escapes string for URI.
Arguments: 1) String to escape.

$wait

Description: Causes dealy in processing on specified number of millisecond. Useful for testing/debuging synchronization issues. Macro always returns empty value.
Arguments: 1) Number of millisecond to wait.

$wrap

Description: Special tool to "wrap" expression by last dimension. Used to create lists from dimensional (multi-value) expressions. It works as follow:
  • Iterates through last dimension of an expression. Last dimension is the right-most dimension of a union of dimensions of macros used in an expression starting from left to right.
  • At each iteration evaluates expression and substitutes it instead of placeholder $# in a wrap template.
  • Evaluates other parts of a wrap template. Prefix is evaluated at each iteration except first, suffix - except last. Effectively prefix and suffix has same effect and serves as list separator.
  • Concatenates values of wrap template obtained at each iteration at single value. This value is a result of $wrap macro.
  • Result value looses dimension that it is wrapped by.

For example lets assume that an email has three recipients: rcpt_1@domain.com, rcpt_2@example.net and rcpt_3@my.host.edu. Expression:

${wrap $#{ OR } $recipient}

will be evaluated to:

rcpt_1@domain.com OR rcpt_2@example.net OR rcpt_3@my.host.edu

and will not have $recipient dimension.

Arguments: 1) Wrap template. Syntax is the following:
wrap_template =   "{" 0*1wrap_prefix wrap_main 0*1wrap_suffix "}"        ; generic version
                | 0*1wrap_prefix wrap_main_without_space 0*1wrap_suffix  ; simplified version if main part has no spaces inside

wrap_prefix              = "{" *(template | wrap_placeholder) "}"        ; prefix is added at each iteration except first
wrap_suffix              = "{" *(template | wrap_placeholder) "}"        ; suffix is added at each iteration except last
wrap_main                = *(template | wrap_placeholder)                ; main part is always added
wrap_main_without_space  = *(template_without_space | wrap_placeholder)  ; main part is always added

wrap_placeholder = "$#" | "${#}"                                         ; this will be replaced with expression value at each iteration
                                                                         ; note that it can't be used in arguments of a macro

template               = ...                                             ; usual template expression
template_without_space = ...                                             ; usual template expression without spaces inside

For example expression:

SELECT FROM `access_list` WHERE ${wrap `address`=$#{ OR } '${escape $recipient.component}'}

in the context of MySQL Engine will be evaluated for each recipient as follow:

SELECT FROM `access_list` WHERE `address`='test1@example.domain.com' OR `address`='example.domain.com' OR `address`='domain.com' OR `address`='com'

provided that recipient is test1@example.domain.com. Result value will have only $recipient dimension - $recipient.component dimension will be wrapped out.

2) Expression to wrap.

$xml_cdata

Description: Makes XML CDATA from a string: replaces all "]]>" with "]]]]><![CDATA[>", prefixes with "<![CDATA[" and suffixes with "]]>".
Arguments: 1) String to make from.

$xml_escape

Description: Escapes string for XML.
Arguments: 1) String to escape.

$xml_date

Description: Date in XML Scheme compliant format. Calculate from value of $time macro if no arguments are given or from timestamp value given as first argument.
Arguments: 1) Timestamp to calculate date from. Optional, default to value of $time macro.

$xml_time

Description: Time in XML Scheme compliant format. Calculate from value of $time macro if no arguments are given or from timestamp value given as first argument.
Arguments: 1) Timestamp to calculate time from. Optional, default to value of $time macro.

$xml_dateTime

Description: Date and time in XML Scheme compliant format. Calculate from value of $time macro if no arguments are given or from timestamp value given as first argument. Will have +00:00 explicit timezone specification at the end.
Arguments: 1) Timestamp to calculate date and time from. Optional, default to value of $time macro.

$year, $month, $day, $hour, $minute, $second

Description: Current year, month, etc. in current timezone. Calculated from value of $time macro thus evaluated once at first usage of any of them.
Personal tools