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
$data
$data.size
$data.digest
$decode_base64
$empty
$encode_base64
$json_escape
$header
$header.name
$header.body
$headers
$headers.message_id
$headers.in_reply_to
$headers.references
$headers.from
$headers.sender
$headers.reply_to
$headers.to
$headers.cc
|
$headers.bcc
$headers.subject
$hmac
$host
$ip
$ip.dec
$ip.hex
$if_not_empty
$gethostname
$group
$message_id
$md5
$not_empty
$pid
$recipient
$recipient.local
$recipient.domain
$recipient.component
$sender
$sender.local
$sender.domain
$sender.component
$sha1
|
$size
$size_hex
$sp, $br, $cr, $lf, $crlf, $htab
$subject
$text_find_replace_all
$text_truncate
$thread
$time
$time6
$timezone, $timezone.sign, $timezone.hh, $timezone.mm, $timezone.ss
$uri_escape
$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 |
| 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 |
$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. |
$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". |
$json_escape
| Description: |
Escapes string to be a valid JSON string. |
| Arguments: |
One or more arguments are concatenated and then escaped. |
| Description: |
Email header. |
| Dimension: |
$header |
| Stage: |
smtp-end-of-data |
| Description: |
Email header name. |
| Dimension: |
$header |
| Stage: |
smtp-end-of-data |
$header.body
| Description: |
Email header body. |
| Dimension: |
$header |
| Stage: |
smtp-end-of-data |
| Description: |
Email headers as single string. |
| Stage: |
smtp-end-of-data |
| Description: |
ID extracted from Message-ID header value. |
| Stage: |
smtp-end-of-data |
| 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 |
| 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 |
| 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 |
| Description: |
Address extracted from Sender header value. |
| Stage: |
smtp-end-of-data |
| 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 |
| 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 |
| 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 |
| 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 |
| 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. |
$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.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 |
$sender
| Description: |
SMTP sender address. |
$sender.local
| Description: |
Local part of SMTP sender address. |
$sender.domain
| Description: |
Domain part of SMTP sender address. |
$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
$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_truncate
| Description: |
Truncate data to a specified size if data size is greater then this size. Truncation occur at the end of data. Optionally puts specified truncation sequence (such as "...") at the end of data. If truncation sequence is specified data is truncated to lower size so that total size remains no more then specified size. |
| Arguments: |
1) Data to truncate.
2) Data size to truncate data 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. |
$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. |
