> ## Documentation Index
> Fetch the complete documentation index at: https://docs.levelblue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding Email Policy Elements

> Connectors, user groups, IP groups, TextCensor scripts, message templates and stamps, variables, folders and classifications, header rewriting, external commands, and reputation services.

Email policy elements are building blocks you can use when you create MailMarshal policy groups and rules. These elements help you to specify complex rule conditions and rule actions.

Some examples of each type of element are provided by default when MailMarshal is installed. These examples are used in the default email policy.

You can edit the existing elements or create new ones to support your policy requirements.

The following types of elements are available:

**Connectors**

Allow you to import user and group information from Azure Entra, Active Directory or LDAP servers. For more information, see [Configuring Connectors](#configuring-connectors).

**User Groups**

Allow you to apply policy based on email addresses. MailMarshal can retrieve groups from Azure Entra, Active Directory or LDAP servers. You can also create local groups and enter members using wildcard characters.

MailMarshal uses two types of groups: MailMarshal groups and Imported groups. MailMarshal groups contain users and groups that you specify directly. Imported groups contain users and groups that you import from Azure Entra, Microsoft Active Directory servers or LDAP servers. For more information, see [Configuring User Groups](#configuring-user-groups).

**IP Groups**

Allow you to apply policy based on the connecting IP address. For more information, see [Configuring IP Groups](#configuring-ip-groups).

**TextCensor Scripts**

Allow you to apply policy based on the textual content of email messages and attachments. You can create complex conditions using weighted combinations of Boolean and proximity searches. For more information, see [Identifying Email Text Content Using TextCensor Scripts](#identifying-email-text-content-using-textcensor-scripts).

**Message Templates and Message Stamps**

Allow you to notify email users and administrators about MailMarshal actions, and insert disclaimers and confidentiality statements. You can include specific information about a message using variables. For more information, see [Notifying Users with Message Templates and Message Stamps](#notifying-users-with-message-templates-and-message-stamps).

**Virus Scanners**

Allow you to check email messages for virus content. For more information, see [Using Virus Scanning](#using-virus-scanning).

**Folders and Classifications**

Allow you to quarantine or copy messages, or simply to record the results of MailMarshal evaluation. You can report on folder and classification actions using Marshal Reporting Console. For more information, see [Using Folders and Message Classifications](#using-folders-and-message-classifications).

**Email Header Matching and Rewriting**

Allow you to search for the content of email header fields using Regular Expressions. You can modify, add, or delete headers. For more information, see [Header Matching and Rewriting](#header-matching-and-rewriting).

**External Commands**

Allow you to extend MailMarshal functionality with customized conditions and actions. For more information, see [Extending Functionality Using External Commands](#extending-functionality-using-external-commands).

**Reputation Services**

Allow you to configure settings for externally maintained filtering lists that MailMarshal queries by DNS (also known as DNS Blocklists). For more information, see [Configuring Reputation Services](#configuring-reputation-services).

You can create or edit many policy elements on the fly while you are working with rules. For more information, see [Creating Rules](/documentation/mailmarshal/user-guide/email-policy-groups-and-rules.md#creating-rules). You can also create elements in advance.

To work with policy elements, open the MailMarshal Management Console from the MailMarshal program folder. In the left pane of the Management Console select **Policy Elements.**

## Configuring Connectors

Connectors allow MailMarshal to import user and group information from Azure Entra, Active Directory and LDAP servers. Connectors allow you to import email addresses from user accounts, contacts, groups, and public folders.

For information about creating connectors, see [Creating Directory Connectors](/documentation/mailmarshal/user-guide/installing-and-configuring.md#creating-directory-connectors).

To edit a connector:

1. In the left menu of the Management Interface website, expand **Policy Elements**.
2. In the right pane, click **Connectors**.
3. Select a connector, and then click **Edit**.
4. On the Connector Type tab, you can edit the name and description of the connector.
5. In the Reload Schedule section you can edit the schedule on which MailMarshal checks for updated information on the groups imported through this connector. You can choose to import once a day at a specific time, or more than once a day, or manually.
6. *If this is an Azure Entra connector,* on the Entra Properties tab you can update the tenant, client, and secret.
7. *If this is an Active Directory connector,* on the Active Directory Logon tab you can choose to connect as anonymous, or as a specific account. If you choose to connect using a specific account, enter the account details.
8. *If this is a LDAP connector,* edit the information provided.
   1. On the LDAP Server tab you can edit the server name, port, and logon information. You can choose to connect as anonymous, or as a specific account. If you choose to connect using a specific account, enter the account details. You can enter or browse for a search root for this server. See the Help for full details of the fields on this tab. To change the attributes MailMarshal uses to retrieve group and member information from the LDAP server, click **Advanced.**
   2. On the Group Attributes tab, edit the information MailMarshal will use to retrieve groups from the LDAP server. See the Help for full details of the fields on this tab.
   3. On the User Attributes tab, edit the information MailMarshal will use to retrieve user email addresses from the LDAP server. See the Help for full details of the fields on this tab. For more information about how to retrieve all email addresses from a server, see Knowledgebase article Q11877.

When you have completed all required changes to the connector, click **Save.**

## Configuring User Groups

You can use MailMarshal user groups within policy groups and rules. User groups allow you to apply policy to specific users. MailMarshal uses SMTP email addresses to perform user matching. You can create and populate user groups within MailMarshal by entering email addresses manually or copying them from other Groups. You can use wildcard characters when you define groups. You can also import user groups with the Group File Import tool (see [Using the Group File Import Tool](/documentation/mailmarshal/user-guide/managing-configuration.md#using-the-group-file-import-tool)).

### Creating and Populating User Groups

To create and maintain user groups, in the left pane of the Management Console, select Policy Elements. Then select **User Groups** from the right pane menu.

To create a user group:

1. In the right pane menu of the Management Console, select **User Groups**.
2. From the list header, click **Add**.
3. Enter a name and description for the group.
4. To create the group, click **Save**.

To import a user group:

1. In the right pane menu of the Management Console, select **User Groups**.
2. From the list header, click **Import Connector Group**.
3. To find groups, depending on the connector type click **Browse** or **Search**. Select the desired groups from the results. For more information see Help.
4. To import the selected groups, click **Save**.

#### Adding Members to a MailMarshal Group

You can add addresses or wildcard patterns to a MailMarshal user group.

> [!NOTE]
>
> **Note:** You can also automatically harvest addresses from email messages into a group. For more information, see [Add message users into group](/documentation/mailmarshal/user-guide/email-policy-groups-and-rules.md#add-message-users-into-group).

To add members to a MailMarshal user group:

1. In the left pane of the Management Console, select **Policy Elements**.
2. Select the appropriate user group from the right pane menu or list.
3. From the list heading, click **Add**.
4. On the User Group Member panel, enter an individual SMTP address, a partial address using wildcard characters, or a domain name.

   > [!NOTE]
   >
   > **Note:** For more information about wildcard characters, see [Wildcard Characters](/documentation/mailmarshal/user-guide/wildcards-and-regular-expressions.md#wildcard-characters).
5. To add the value, click **Save**.
6. Repeat to add more entries.

#### Adding Groups to a MailMarshal Group

You can add Entra, Active Directory, LDAP, and MailMarshal groups to a MailMarshal user group.

To add other groups to a MailMarshal user group:

1. Select a MailMarshal user group from the right pane of the Management Console.
2. From the list heading, click **Add**.
3. Choose **Select a user group**, and then select a group from the list.
4. To add the value, click **Save**.
5. Repeat to add more items.

#### Pruning a MailMarshal Group

You can configure MailMarshal to remove user addresses from a MailMarshal group. You can prune addresses that have not been seen for a time. You can also prune addresses if a group grows too large.

To configure group pruning:

1. Right-click a MailMarshal user group in the right pane of the Management Console, and select **Edit**.
2. Select (toggle on) one or both pruning options (*Delete members who have not been seen* and *Delete members when the group exceeds*), and set the limits.
3. Click **Save.**

For more information about pruning, see Help, and see also Knowledgebase article Q12772.

### Moving and Copying Users and Groups

To copy a user group, right-click it in the list in the right pane of the Management Console. To make a copy, choose **Duplicate** from the context menu.

To add a user group to another user group, select the target group and then click **Add**. On the User Group Member panel, choose to select a user group, select a group from the list, and then click **Save**.

To move users or groups, you must delete them from the original location and add them to the new location.

## Configuring IP Groups

You can use MailMarshal IP groups within policy groups and rules. IP groups allow you to apply policy based on the connecting IP address from which an SMTP connection was made or email was received. You can create and populate user groups within MailMarshal by entering individual IP addresses, ranges, or CIDR blocks.

### Creating and Populating IP Groups

To create and maintain IP groups, in the left pane of the Management Console, select **Policy Elements**. Then select **IP Groups** from the right pane menu.

To create an IP group:

1. In the right pane menu of the Management Console, select **IP Groups.**
2. From the list header, click **Add**.
3. Enter a name and description for the group.
4. Click **Save**.

#### Adding Members to an IP Group

You can add individual IP addresses, ranges, or CIDR blocks to an IP group.

To add members to an IP group:

1. Select the appropriate user group from the right pane of the Management Console.
2. On the Action menu, select **Insert IPs.**
3. On the Add IP window, complete the required information. See Help for details. When you have completed the information, click **Save.**
4. Repeat these actions to add additional items.

#### Editing an IP Group Member

You can edit the information in an IP Group member record.

To edit a member, double-click the entry in the list, make required changes, and then click **Save**.

#### Adding Groups to an IP Group

You can add other IP groups to a MailMarshal IP group.

To add other groups to a MailMarshal IP group:

1. Select a MailMarshal IP group from the right pane of the Management Console.
2. On the Action menu, select **Insert IP Groups**.
3. In the Insert Into IP Group window, select a group from the list. Click **Save**.
4. Repeat these actions to add additional items.

### Moving and Copying IP Groups

To add an IP group to another IP group, in the left pane select it and drag it over the target group in the same pane.

To move entries or groups, you must delete them from the original location and add them to the new location.

## Identifying Email Text Content Using TextCensor Scripts

**TextCensor scripts** check for the presence of particular lexical (text) content in an email message. MailMarshal can check one or more parts of a message, including the message headers, message body, and any attachments that can be lexically scanned.

Apply TextCensor scripts to email messages by using Content Analysis Policy rules.

A script can include many conditions. Each condition is based on words or phrases combined using logical and positional operators. The script matches, or triggers, if the weighted result of all conditions reaches the target value you set.

> [!NOTE]
>
> **Note:** For MailMarshal to detect and block explicit language (such as profanity and pornographic language), objects such as the Email Policy rules and the TextCensor scripts need to contain that explicit language. Anyone who has permission to use the MailMarshal Management Console or Marshal Reporting Console may be exposed to this explicit language. As this language may be objectionable, please follow your company's policy with respect to exposure to content of this type.

### TextCensor Elements

TextCensor scripts contain one or more expressions, each consisting of a word or phrase.

#### Wildcards

You can use two wildcard characters, anywhere in a word or phrase.

* `*` matches zero or more letter or digit characters or ideographs.
* `?` matches one letter, digit, or ideograph.

Wildcards match only letters and digits, and apostrophes or hyphens that are treated as part of words (see [Word Breaks](#word-breaks)). Wildcards do not match other symbol characters.

> [!NOTE]
>
> **Notes:**
>
> * You cannot use pure wildcard patterns comprised entirely of a mixture of `[DIGIT]`, `[LETTER]`, `*`, or `?`
> * Make patterns as specific as possible. Patterns that produce a very large number of matches will take a long time to evaluate and consume unacceptable amounts of system resource. For example, do not use the patterns `*e*` or `a*` when evaluating English-language documents.

If you want to set the order of evaluation of a complex expression that uses more than one operator, use parentheses ( ).

Each TextCensor expression can include logical and positional operators. The operators must be entered in UPPERCASE.

#### Positional Operators

TextCensor works with the positions of words or phrases within a file. For example, in the sentence "The quick brown fox jumps over the lazy dog" the word "quick" starts and ends at position 2, and the phrase "jumps over" starts at position 5 and ends at position 6.

A positional operator works with expressions that evaluate to sets of positions. It takes two sets of positions as parameters, and returns a new set of positions.

> [!TIP]
>
> **Tip:** In a simple TextCensor expression, you can think of the expression result as "true" or "matched" if the word or phrase is found in any position in the text. When the word or phrase is found in more than one position, this counts as more than one match of the expression.
>
> When you combine positional operators to make a complex expression, note the explanations of the sets returned by each operator (see below). Test your script before applying it in production.

You can specify a distance for many positional operators. The default distance (if you do not specify a value) is 4.

**Table 14: TextCensor Positional Operators**

| Operator and Syntax | Matching Results |
| - | - |
| **FOLLOWEDBY** `A FOLLOWEDBY[=distance] B` | The start of B occurs within *distance* words from the end of A. Returns a set of positions spanning from the start of A to the end of B. `dog FOLLOWEDBY hous*` matches `Dog in the house` |
| **NOT FOLLOWEDBY** `A NOT FOLLOWEDBY[=distance] B` | The start of B does not occur within *distance* words from the end of A. Returns a set containing the positions in A that are not followed by B. `dog NOT FOLLOWEDBY=1 hous*` matches `Dog in the house` |
| **PRECEDEDBY** `A PRECEDEDBY[=distance] B` | The end of B occurs within *distance* words from the start of A. Returns a set of positions spanning from the start of B to the end of A. `dog PRECEDEDBY cat` matches `Cat chasing dog` |
| **NOT PRECEDEDBY** `A NOT PRECEDEDBY[=distance] B` | The end of B does not occur within *distance* words from the start of A. Returns a set containing the positions in A that are not preceded by B. `dog NOT PRECEDEDBY=2 cat` matches `Cat was not chasing dog` |
| **NEAR** `A NEAR[=distance] B` | If A occurs within *distance* words before B the resulting position spans from the start of A to the end of B. If B occurs within *distance* words before A the resulting position spans from the start of B to the end of A. `dog NEAR cat` matches `Cat chasing dog` and also matches `Dog chasing cat` |
| **NOT NEAR** `A NOT NEAR[=distance] B` | Returns the positions of all instances of A where B is not found within *distance* words from A `dog NOT NEAR=2 cat` matches `Cat was not chasing dog` and also matches `Dog was not chasing cat` |
| **OR** `A OR B` | This form of the OR operator is applied when both A and B are sets of positions, even if one or both are empty sets. It returns the union of position sets A and B. For the sentence "A rose is a rose", the expression `(rose OR is)` returns the position set 2,3,5. |

#### Logical (Boolean) and Special Operators

A logical operator takes Boolean (true/false) values as input, and returns a Boolean result. These results cannot be used as parameters of a positional operator.

When one of the parameters to a logical operator is an expression that returns a position set, the parameter is treated as a logical value. A set with at least one position match is treated as true. A set that has no matches is treated as false.

TextCensor also supports the special operator INSTANCES.

**Table 15: TextCensor Logical and Special Operators**

| Operator and Syntax | Matching Results |
| - | - |
| **OR** `A OR B` | Returns true if A or B (or both) is true. This form of the OR operator is applied when either A or B (or both) are logical expressions. If both A and B are position sets then the positional OR operator is used instead. |
| **AND** `A AND B` | Returns true if both A and B are true. |
| **NOT** `NOT A` | Returns the opposite of A (true if A is false). |
| **INSTANCES** `A INSTANCES=count` | A must be an expression that returns a position set. The result is true if A contains *count* or more word positions; otherwise the result is false. |

#### Anchored Regular Expressions

TextCensor supports use of Regular Expressions through the ARX operator.

An anchored regular expression is a regular expression (regex) which must be preceded by a word on the left hand side of the ARX operator. Matching of the regex begins at the next character following the word. Regex patterns should always begin by matching one or more non-word characters. In most cases you can start the regex pattern with `\W` (to match whitespace).

> [!NOTE]
>
> **Notes:**
>
> * ARX is based on Google RE2. The syntax is generally similar to the syntax used in MailMarshal Header Matching (see [Regular Expressions](/documentation/mailmarshal/user-guide/wildcards-and-regular-expressions.md#regular-expressions)).
> * Distance parameters for ARX operators are specified in characters. The default is 100 characters.
> * Regular expressions are case insensitive by default. You can force case sensitive matching with the operator `?-i`
> * ARX does not support lookahead or lookbehind.
> * ARX does not support capture groups. Capture groups will be ignored or converted to non-capturing sequences.
> * ARX does not support `\Q...\E` literal text.
> * For further details of the ARX syntax, see the [RE2 wiki](https://github.com/google/re2/wiki/Syntax).

**Table 16: TextCensor Regular Expression Operators**

| Operator and Syntax | Matching Results |
| - | - |
| **ARX** `A ARX[=distance] /pattern/` | Locates instances of A where it is followed by text matching the regex pattern within *distance* characters of the end of A. The entire pattern must occur within the specified distance. The resulting position list spans from the beginning of A to any content matched by the regex. `dog chasing ARX /\W(one\|two\|10) cat(s*)/` |
| **NOT ARX** `A NOT ARX[=distance] /pattern/` | Locates instances of A where text matching the regex pattern does not occur within *distance* characters of the end of A. When this expression matches, the resulting position list is the position list of A. |

Multiple anchored regular expressions can be combined with other expressions and operators to create complex statements. For example,

```text theme={null}
((dog OR boy) FOLLOWEDBY=1 ((chasing OR leading) ARX /\W(one|two|10)/) NEAR big) FOLLOWEDBY (white ARX /\W(horse|cat)s*/)
```

matches the phrase: *dog chasing one or more big white cats*.

### TextCensor Concepts

The following concepts clarify how TextCensor expressions are evaluated.

> [!NOTE]
>
> **Note:** This section does not apply to Regular Expression patterns.

#### Words

A word is made up of one or more letters and digits, and sometimes symbols.

* In alphabetic languages, a word is a group of letters or digits separated by other characters (such as punctuation, other symbols, and white space).
* In Chinese, or Japanese kanji, a word or "token" may be composed of one or more characters (ideographs).

#### Phrases

A phrase is made up of a series of words separated by word break characters.

#### Symbols and Punctuation

Symbols other than letters and digits are not treated as part of a word unless they appear in the specific statement being evaluated. A group of symbols is not treated as a word.

> [!TIP]
>
> **Tip:**
>
> * The text `word$deed` is matched as two words by the expression `word FOLLOWEDBY deed`, and also by the exact expression `word$deed`
> * The text `$word$` is matched by any of `word`, `$word`, `word$`, or `$word$`
> * The text `Save $$$ Now` is matched by `save FOLLOWEDBY=1 now`

#### Word Breaks

The sets of characters that are treated as word and number break characters generally follow Unicode standards.

A word break character can also be matched exactly or by a wildcard.

> [!TIP]
>
> **Tip:**
>
> * Each of the following strings is treated as one word: `John's`, `3.14159`, `1,234.56`, `3a`, `REV.B` (the full stop between letters with no surrounding spaces is not a word break)
> * The text `half-baked` is treated as two words and is matched by any of the following expressions: `half FOLLOWEDBY=1 baked`, `half-baked`, `half?baked`

#### Accented Letters

TextCensor treats each accented character as a single letter. A letter with additional composed accent characters is normalized to a single character before the text is evaluated.

#### Escape Characters

Some characters have special meanings in TextCensor. These characters are parentheses, square braces, the asterisk, the equal sign, the double quote character, and the question mark. You can place a backslash character (`\`) before any of these characters in order to use the character's normal meaning. To use a normal backslash character, place two of them together (`\\`).

Within ARX expressions, the Regular Expression reserved characters apply (in particular the forward slash `/`) which marks the start and end of the regex pattern).

#### Case Sensitivity

TextCensor evaluation is NOT case sensitive by default. To perform a case sensitive match, quote the content using double quote characters. All special characters and escape characters retain their meaning within double quotes.

#### Classes

You can use TextCensor Classes to match specific types of characters inside a word, or special types of words.

**Table 17: TextCensor Classes**

| Operator and Syntax | Matching Results |
| - | - |
| **\[LETTER]** | Matches any single letter inside a word. |
| **\[DIGIT]** | Matches any single digit inside a word. For example, `A[LETTER]B[DIGIT]C` would match both "axb0c" and "aab9c". |
| **\[NUM]** | Use in place of a word to match any number made up of one or more digits. This class does not match numbers with a decimal point, or Asian language numbers that use words between characters |
| **\[CCARD]** | Use in place of a word to match a series of digits that look like credit/payment card numbers. These numbers consist of up to 5 groups of digits, are up to 19 digits in length, and must pass checksum validation (using the Luhn algorithm). This class should match most card numbers. |
| **\[US-SSN]** | Use in place of a word to match series of digits that look like US Social Security Numbers. Valid numbers must follow a specific format. However, the format is loosely defined and it is not possible to prevent accidental matching of other numbers. |
| **\[CAN-SIN]** | Use in place of a word to match a series of digits that looks like a Canadian Social Insurance Number. Valid numbers must follow a specific format and pass a Luhn check. |

#### Named Statements

You can give a TextCensor statement a name. When a named statement is executed, the result is stored. You can reference it in later statements within the same script.

If a statement contains only words or only uses positional operators, the stored result is the set of word positions found by that statement. If the statement uses any other operators then the result is logical.

You can reference the result of a statement by using `[@name]` inside a statement. This can be used anywhere that you would otherwise use the bracketed result of an operator.

> [!NOTE]
>
> **Note:** Naming a statement does not affect the statement's score. To use a named statement as a macro expression, in most cases you should set the statement's score to zero.
>
> When using named statements within other expressions, remember that the result must match the required parameter type. If a statement returns a logical result you cannot use it as a parameter to a positional operator. Test your scripts before applying them in production.

### Scoring a TextCensor Script

Each script is given a trigger threshold, expressed as a number. Each expression in a script is given a positive or negative score. If the total score of the content being checked reaches or exceeds the trigger threshold, the script is triggered.

The total score is determined by summing the scores resulting from evaluation of the individual expressions in the script.

For each expression, if the result is a true logical value, the expression score is the base score.

If the expression result is a position set (the word or phrase was found one or more times in the text), by default the final score of the expression is the base score. You can choose how to add the score when the expression is matched more than once. The options are:

**Table 18: Cumulative scoring options**

| Option | Description |
| - | - |
| Every time | Each match of the words or phrases adds the score to the total. |
| First Match Only | Only the first match of the words or phrases adds the score to the total. |
| First N Matches | Each match, up to the number you set, adds the score to the total. For instance if the expression score is 5 and you select "first 3 matches," then the expression can contribute up to 15 to the total score, but never more than 15. |

Negative scores and trigger levels allow you to compensate for the number of times a word could be used in text that you do not want to match. For instance: if `breast` is given a positive score in an "offensive words" script, `cancer` could be assigned a negative score (since the presence of this word suggests the use of `breast` is medical/descriptive).

> [!NOTE]
>
> **Note:** Script evaluation always checks all expressions to obtain the final score. The order of expressions in a script is not significant. This is a change from earlier versions.

### Creating Scripts

To work with TextCensor Scripts, in the left pane of the Management Console, select **Policy Elements**. Then select **TextCensor Scripts** from the right pane menu.

To add a TextCensor Script:

1. In the right pane of the Management Console, select **TextCensor Scripts.**
2. On the menu above the list, choose **Add** to open the TextCensor Script window\*\*.\*\*\
    ![TextCensor Script window with name, trigger threshold, and message part options](https://mintcdn.com/levelblue-5324744e/x21QTv9fJshn3W3y/images/mailmarshal/textcensor-script.png?fit=max\&auto=format\&n=x21QTv9fJshn3W3y\&q=85\&s=dd584e4db46dc996f129463f32d45efe)
3. Enter a name for the script.
4. Select which portions of an email message you want this script to scan by selecting one or more of the check boxes Subject, Headers, Body, and Attachments

   > [!NOTE]
   >
   > **Note:** The script will check each part separately.
   >
   > For instance, if you select both Headers and Message Body, the script will be evaluated once for the headers, then again for the body. Script scoring is not cumulative over the parts.
5. Add one or more TextCensor items. To begin adding items, in the TextCensor Script window click **New** to open the Add TextCensor expression window\*\*.\*\*
6. Enter the expression, optionally using the operators described earlier. For example:

   ```text theme={null}
   (Dog FOLLOWEDBY hous*) AND NOT cat
   ```

   In this example the expression score is added to the script total if the document contains the words `dog house` (or `dog houses`, and so forth) in order, and does not contain the word `cat`.

   > [!NOTE]
   >
   > **Note:** TextCensor expressions are **not** case sensitive by default. However, quoted content is case sensitive. So `textcensor` would match TextCensor, but `"textcensor"` would not.
7. Select a score and contribution method for this expression (see [Scoring a TextCensor Script](#scoring-a-textcensor-script) for more information).\
    ![TextCensor Expression window with expression, weighting type, and score](https://mintcdn.com/levelblue-5324744e/x21QTv9fJshn3W3y/images/mailmarshal/textcensor-expression.png?fit=max\&auto=format\&n=x21QTv9fJshn3W3y\&q=85\&s=60b158fa8dce37b65e3b0889b772205b)
8. Click **Add** (or press **Enter**) to add the expression to this script. The window remains open so you can create additional expressions.
9. When you have finished entering expressions, click **Close** to return to the New TextCensor Script window.
10. Select a trigger threshold. If the total score of the script reaches or exceeds this level, the script is triggered. The total score is determined by evaluation of all expressions in the script.

### Editing Scripts

You can change the content of an existing script, including the individual items and overall properties.

To edit a TextCensor Script:

1. Double-click the script to be edited in the right pane.
2. Edit an item by double-clicking it.
3. Delete an item by selecting it, and then clicking **Delete.**
4. Change the contents of other fields such as the script name, parts of the message tested, and trigger threshold.
5. Click **Save** to accept changes or **Cancel** to revert to the stored script.

### Duplicating Scripts

Duplicate a script if you want to use it as the basis for an additional script.

To duplicate a TextCensor Script:

1. Right-click the script name in the Management Console.
2. Choose **Duplicate** from the context menu.
3. After duplicating the script, make changes to the copy.

### Importing Scripts

You can import scripts in files. Use this function to copy a script from another MailMarshal installation, or to restore a backup.

> [!NOTE]
>
> **Note:** Some older product versions used a different format for the exported scripts. The earlier version scripts will be upgraded to the new format automatically. Any problems with upgrading will be reported.

To import a TextCensor Script from an XML file:

1. On the Action menu, choose **New TextCensor Script** to open the TextCensor Script window\*\*.\*\*
2. Click **Import**.
3. Choose the file to import from, and click **Open.**
4. In the Edit TextCensor Script window, click **Save**.

### Exporting Scripts

You can save scripts in files. Use this function to move a script between MailMarshal installations, or to edit a script in another application such as Microsoft Excel.

To export a TextCensor Script to an XML file:

1. Double-click the name of the script to be exported in the right pane to open the Edit TextCensor Script window.
2. Click **Export.**
3. Enter the name of the file to export to, and click **Save**.
4. In the Edit TextCensor Script window, click **Save.**

### TextCensor Best Practices

To use TextCensor scripts effectively, you should understand how the TextCensor facility works and what it does.

MailMarshal applies TextCensor scripts to text portions of messages. Depending on the portions you select, a script can apply to message subject, message headers, message bodies, and attachment content. MailMarshal can generally apply TextCensor scripts to the text of Microsoft Office documents and Adobe PDF files, as well as to attached email messages and plain text files.

> [!NOTE]
>
> **Note:** When you apply complex scripts to large documents, the script evaluation can consume significant system resources and process slowly. Use the minimum number of statements and operators, and match the most specific text possible.

#### Constructing TextCensor Scripts

The key to creating good TextCensor scripts is to enter exact words and phrases that are not ambiguous. They must match the content to be blocked. Also, if certain words and phrases are more important, you should give those words and phrases a higher score. For instance, if your organizational Acceptable Use Policy lists specific terms that are unacceptable, you should give those terms a higher score to reflect the policy.

In creating TextCensor scripts, strike a balance between over-generality and over-specificity. For instance, suppose you are writing a script to check for sports-related messages. If you enter the words "score" and "college" alone your script will be ineffective because those words could appear in many messages. The script will probably trigger too often, potentially blocking general email content.

You could write a better script using the phrases "extreme sports", "college sports" and "sports scores" as these phrases are sport specific. However, using only a few very specific terms can result in a script that does not trigger often enough.

You can strike a good balance using both very specific and more general terms. Again using the example of sports related content, you could give a low positive weighting to a phrase such as "college sports." Within the same script you could give a higher weighting to the initials NBA and NFL, which are very sports specific.

#### Decreasing Unwanted Triggering

TextCensor scripts sometimes trigger on message content which is not obviously related to the content types they are intended to match.

To troubleshoot unwanted triggering:

1. Use the problem script in a rule which copies messages and their processing logs to a folder. You could call this folder "suspected sports messages".
2. After using this rule for some time, check on the messages that have triggered the script. Review the message logs to determine exactly which words caused the script to trigger. See [Viewing Messages](/documentation/mailmarshal/user-guide/monitoring-email-flow.md#viewing-messages).
3. Revise the script by changing the expression scores, expression contribution method, trigger threshold, or key words, so as to trigger only on the intended messages.
4. When you are satisfied, modify the rule so as to block messages that trigger the script. You could also choose to notify the sender and/or the intended recipient.

### Testing Scripts

When you are working with a TextCensor script in the Management Console, you can test it against a file or pasted text.

To test a TextCensor Script:

1. On the New or Edit TextCensor Script window, click **Test**.
2. *To test using a file,* select **Test script against file.** Enter the name of a file containing the test text (or browse using the button provided).
3. *To test using pasted text,* select **Test script against text**. Type or paste the text to be tested in the field.
4. Click **Test.** MailMarshal will show the result of the test, including details of the items which triggered and their weights, in the **Test Results** pane.

## Notifying Users with Message Templates and Message Stamps

MailMarshal provides two ways of sending notifications by email.

**Message stamps** are short blocks of text that can be added to an email message. You can use a stamp to add a company disclaimer, or to warn the recipient of a message that MailMarshal has modified it.

**Message templates** are complete email messages that can be sent to a user or administrator. MailMarshal uses templates for system notifications such as non-delivery reports. You can also use them to provide auto-responders or other custom notices. MailMarshal can use special digest templates to provide users with summary information about quarantined email.

MailMarshal applies message stamps to both HTML and plain text portions of an email message. Message templates can also include plain text and HTML bodies.

Variables can be used in both templates and stamps. **Variables** are specially formatted strings you can insert in a stamp or template. When MailMarshal uses the stamp or template, it replaces the variables with information about the specific message. This facility allows you to provide detailed information about the actions MailMarshal has taken on a specific message.

### Message Templates

Message templates are used when MailMarshal sends a notification email message based on the outcome of rule processing. The most common use of notification messages is to notify appropriate parties when an email message is blocked.

Notifications are a very powerful tool to inform and modify user behavior. When well thought out and constructed, they can save the administrator a lot of time.

You can also use a notification to set up a general auto responder based on message headers or content. For instance, MailMarshal could respond to a message to `robot@ourcompany.com` with the subject "Send Catalog" by returning the product catalog to the sender as an email attachment.

The same rule can send several notification messages. For instance, if MailMarshal detects a virus you could choose to send different messages to an email administrator, the external sender, and the intended internal recipient of the message.

You can attach files to a notification. Attachments can include the original message, the MailMarshal processing log for the message, and any other file (such as a virus scanner log file).

You can create a template as plain text, HTML, or both. If you choose to create a template with both HTML and plain text bodies, you must edit the two bodies separately. If you choose to create a template with HTML only, MailMarshal will automatically generate a plain text equivalent of the template with similar formatting.

You can include links to images in HTML templates. You cannot embed images.

> [!NOTE]
>
> **Note:** In addition to rule notification templates, MailMarshal uses a number of pre-configured templates for administrative notifications (such as delivery failure notifications). For more information about modifying these templates, see [MailMarshal Properties – Advanced](/documentation/mailmarshal/user-guide/managing-configuration.md#setting-advanced-options).

### Creating a Message Template

To work with templates, in the left pane of the Management Console, select **Policy Elements**. Then select **Message Templates** from the right pane menu.

To create a message template:

1. In the right pane of the Management Console, select **Message Templates.**
2. On the Action menu, select **New Message Template** to open the Message Template window.
3. By default, MailMarshal creates a HTML message body. MailMarshal will automatically generate a plain text equivalent of the message body when using the template. To choose a plain text body or edit both types separately, click **Options.**
4. To see additional address fields, click **Options.**
5. Enter a name for the template.
6. Enter appropriate information in the Header Details section. For instance, enter the email address to which replies should be sent in the **Return Path** field.

   > [!NOTE]
   >
   > **Note:** The MailMarshal default configuration includes numerous templates. These are a good source of ideas for the creation of new templates.
7. Enter text in the body section. To view the raw HTML, right-click in the HTML pane and select **Edit Raw HTML.** Edit the HTML, or paste HTML source from another editor, then click **Save** to return to the message template window.
8. You can attach files to the notification, including the original message, the MailMarshal message processing log, and other files. To attach one or more files, select the appropriate box(es) and enter the file names if necessary.
9. You can use variables marked with braces `{ }`. To see a list of variables available in any field, type `{` to open a context menu. You can also enter variable names manually. You can use nested variables. For details of the variables available in templates, see [Using Variables](#using-variables).

   > [!NOTE]
   >
   > **Note:** When sending a notification to the original sender of an email message, use the `{ReturnPath}` variable in the To: field to reduce the chance of looped messages. Do not use the `{ReturnPath}` variable in the From: field.

### Creating Digest Templates

The MailMarshal Array Manager uses digest templates to deliver periodic message digests to users who self-manage end-user management folders. For details of digesting, see [Setting Up Message Digests](/documentation/mailmarshal/user-guide/delegating-spam-and-quarantine-management.md#setting-up-message-digests).

Digest templates are similar to message templates. The key differences are:

* You cannot attach files to digest templates.
* You must associate each digest template with a message digest. See [Setting Up Message Digests](/documentation/mailmarshal/user-guide/delegating-spam-and-quarantine-management.md#setting-up-message-digests).
* You cannot edit the "To" field. The recipient is controlled by settings of the message digest.

Digest templates support variables specific to the digesting function that are not available in message templates. These variables allow MailMarshal to provide a list of information about several messages within the same notification message. The most important of these variables is the HTML digest table variable `$MessageDigestTableHTML`.

The following arguments are available to customize the behavior of this variable. All arguments are optional.

**Table 19: Digest detail levels**

| Detail Level | Results |
| - | - |
| BRIEF | Single line for each message, with From, Subject, Date, and small portion of message body (default level). |
| COMPACT | Two lines for each message; portion of message body starts on second line. |
| VERBOSE | Longer version including up to 200 characters of message body. |

**Table 20: Digest options**

| Option | Results |
| - | - |
| SHOWRELEASE | Show the message release link for each message (default option). |
| RELEASETRUST | For incoming digests, in addition to the release link, show a "Trust" link for each message (in the Sender column). If the "Trust" link is clicked, release the message and also add the sender to the user's Safe Senders list. • For the Trust feature to function, SQM must be configured, and user management of safe senders must be enabled (in the Administrator tab of the SQM site). • With SQM Forms authentication, if the digest recipient's address is not found as a SQM user or alias, MailMarshal creates a SQM user and sends a password email. With SQM Windows authentication, the address must pre-exist as an alias. |
| NORELEASE | Do not show the message release links. |
| RELEASEURL=*url* | Specify the URL path to the Release webpage used for this digest (see example below). Defaults to the URL of the local MailMarshal Spam Quarantine Management website. A URL could be specified, for instance, in the digests for user groups that cannot browse to the default location. |
| GROUP | Group entries by folder, for digests covering multiple folders. |
| SHOWFROM=*yes\|no* | Show the sender address. Defaults to yes. |
| SHOWTO=*yes\|no* | Show the recipient address. This option will generally be required when digests for multiple users are sent to the same address. Defaults to no. |

Example:

```text theme={null}
{$MessageDigestTableHTML=COMPACT,GROUP,SHOWFROM=no,RELEASEURL=http://extranet.example.com/SpamConsole}
```

For details of other variables available in digest templates, see [Using Variables](#using-variables).

> [!NOTE]
>
> **Note:** To obtain the best results with digest templates, edit the plain text and HTML versions of the template separately using the "Both" option.

To create a digest template:

1. In the right pane of the Management Console, select **Message Templates.**
2. On the Action menu, select **Add Digest** to open the Digest Template window.\
    ![Message Template window showing a new digest template with HTML body](https://mintcdn.com/levelblue-5324744e/x21QTv9fJshn3W3y/images/mailmarshal/digest-template.png?fit=max\&auto=format\&n=x21QTv9fJshn3W3y\&q=85\&s=0d8aea733c259b1c480fa4d1e99ae28f)
3. By default, MailMarshal populates the template with basic information. MailMarshal creates separate HTML and plain text message bodies. To choose to use only one of the two types, click **Options.**
4. To see additional address fields, click **Options.**
5. Enter a name for the template.
6. Enter appropriate information in the Header Details section. For instance, enter the email address to which replies should be sent in the **Return Path** field.
7. Enter text in the body section. To view the raw HTML, right-click in the HTML pane and select **Edit Raw HTML.** Edit the HTML, or paste HTML source from another editor, then click **Save** to return to the message template window.
8. You can use variables marked with braces `{ }`. To see a list of variables available in any field, type `{` to open a context menu. You can also enter variable names manually. You can use nested variables. For details of the variables available in templates, see [Using Variables](#using-variables).
9. Click **Save.**

### Editing Templates

You can edit a template, including the address information and the message bodies.

To edit a template:

1. Double-click a template name in the Management Console.
2. Make changes then click **Save.** If you have created both a plain text and a HTML version of the template, remember to change both versions.

### Duplicating Templates

You can make a copy of a template if you want to use it as the starting point for another template.

To copy a template:

1. Right-click a template name in the Management Console.
2. Choose **Duplicate** from the context menu.
3. After duplicating the template, make changes to the copy.

### Deleting Templates

You can delete a template if it is not used in any rules.

To delete a template:

1. Select a template in the Management Console.
2. Click the **Delete** icon in the toolbar.

### Working with Message Stamps

Message stamps are short blocks of text that MailMarshal can apply to the top or bottom of an email message body. MailMarshal message stamps can include a plain text and an HTML version. MailMarshal will apply the appropriate stamp format to the body text of the same type in the message.

Many companies use message stamps to apply disclaimers or advertising on outgoing email. MailMarshal can also use a message stamp to notify the recipient that a message has been processed (for example by having an offending attachment stripped).

To work with Message Stamps, in the left pane of the Management Console, select **Policy Elements**. Then select **Message Stamps** from the right pane menu.

To create a message stamp:

1. In the right pane of the Management Console, select **Message Stamps.**
2. On the Action menu, select **New Message Stamp**.
3. Enter a name for the stamp.
4. Select whether the stamp is to appear at the top or the bottom of messages.
5. Enter a plain text version of the message stamp in the Plain Text tab.
6. Enter an HTML version of the stamp in the HTML tab.
   * You can apply various formatting, including hyperlinks, to the HTML text using the buttons provided.
   * You can define and use local CSS classes in a stamp. See Help for details.
   * To view the raw HTML, right-click in the HTML pane and select **Edit Raw HTML.** Edit the HTML, or paste HTML source from another editor, then click **Save** to return to the message stamp window.
7. To add the new stamp to the list of available message stamps, click **Save**.

> [!NOTE]
>
> **Note:** If message stamping is enabled for RTF (Microsoft TNEF) messages, the plain text message stamp will be used for these messages. To enable RTF stamping, see the Engine Advanced section of MailMarshal Properties.

Both plain text and HTML message stamps can include the same variables available within email notification templates.

#### Duplicating Message Stamps

You can make a copy of a stamp if you want to use it as the starting point for another stamp.

To duplicate a message stamp:

1. Right-click the stamp name in the Management Console.
2. Choose Duplicate from the context menu.
3. After duplicating the message stamp, make any required changes to the copy. Remember to make changes to both the Plain Text stamp and the HTML stamp.

#### Editing Message Stamps

You can make changes to a stamp. Remember to make changes to both the Plain Text stamp and the HTML stamp.

To edit a message stamp:

1. Double-click the stamp name in the right hand pane of the Management Console.
2. Make the required changes.
3. Click **Save.**

#### Deleting Message Stamps

You can delete a message stamp if it is not used in any rules.

To delete a message stamp:

1. Select the stamp in the right hand pane of the Management Console.
2. Click the **Delete** icon in the toolbar.

### Using Variables

You can use variables when you create a message template, digest template, message stamp, or message classification description, and also in the field substitution of content analysis Header Rewrite rules. MailMarshal substitutes the appropriate information when processing each message or digest.

Variables are marked by curly braces `{ }`. You can select from available variables in any field where they are available in a template, stamp, or classification. To see a list of available variables in a specific field, type `{` .

Not all variables are available in all contexts. MailMarshal may not have the required information to substitute. In particular, if a message is deadlettered, information about the message content is not available. If MailMarshal does not have any data, it will enter empty text into the variable marker or return the variable marker text.

The following table lists commonly used variables and their functions:

**Table 21: MailMarshal variables**

| Variable | Data inserted |
| - | - |
| `{$MessageDigestTableHTML=detail[,option,option,...]}` | The HTML version of a message digest detail listing. For full information about options, see [Creating Digest Templates](#creating-digest-templates). See also the variable `{MessageDigestTableText}`. |
| `{Administrator}` | Email address of the administrator as set during post-installation configuration and accessible from the Notifications section of MailMarshal Properties. |
| `{ArrivalTime}` | The time when MailMarshal received a message. |
| `{AttachmentName}` | File name of the attached file that triggered a rule condition. |
| `{CmdFileName}` | Full path to a file unpacked from the message being scanned. Used in the parameters of an External Command or Command Line Virus Scanner to take action on a specific file. |
| `{Date}` | The current date. For more information, see [Date Formatting](#date-formatting). |
| `{DateLastRun}` | The date of the previous MailMarshal message digest for a folder. |
| `{Errorlevel}` | The last error returned by a virus scanner or an external command. |
| `{ExternalCommand}` | The name of the last External Command used. |
| `{Env=varname}` | Inserts the value of a Windows environment variable. |
| `{ExternalSender}` | Returns 'y' or 'n' depending on whether the sender was outside or inside the "allowed to relay" space. |
| `{File=fullpath}` | Inserts a text file within the body of a message (for instance, can be used to insert the MailMarshal log for a message in a notification email body). |
| `{Folder}` | The name of the folder that is the subject of a MailMarshal message digest email. |
| `{FolderRetention}` | The retention period for a folder that is the subject of a MailMarshal message digest email. |
| `{FormattedRecipients}` | Available in Engine dead letter templates only. Lists recipients of the message (in the To: or CC: fields), formatted for use in the message body. |
| `{FormattedRecipientsAffected}` | Available in Sender templates only. Where a message could not be send to some recipients (in the To: or CC: fields), shows the affected recipients of the message, formatted for use in the message body. |
| `{From}` | Email address in the 'From' field of the message. |
| `{HasAttachments}` | Returns '1' if the message has attachments. |
| `{Header-Reply-To}` | Email address in the 'Reply-To' header of the email message. If the 'Reply-To' header is not present, the return-path email address is used. |
| `{HelloName}` | Name given by the remote email server when MailMarshal received this message. |
| `{Hostname}` | The host name of the server. |
| `{If variable}...[{else}...]{endif}` | Allows conditional substitution of text. The condition is true if the variable is not empty. For example: `{If VirusName}This message contained the virus {VirusName}.{endif}` The Else clause is optional. |
| `{InitialMessageBody}` | The first 200 characters of the body of the message. |
| `{Install}` | The install location of MailMarshal. |
| `{LastAttemptDate}` | The date and time of the most recent attempt to deliver the message. |
| `{LastTextCensorRuleTriggered}` | The name of the TextCensor Script that was run and the phrase that triggered. |
| `{LocalRecipient}` | The message recipient, if any, within the local domains. Includes multiple recipients, CC and BCC recipients. • To preserve the privacy of BCC recipients when sending notifications, do not use this variable in the template TO: field or in the body of the template. Place this variable in the BCC: field. |
| `{LocalSender}` | The message sender, if any, within the local domains. |
| `{LogName}` | The name of the Logging Classification used. |
| `{Message-ID}` | Original SMTP Message ID of the message. |
| `{MessageFullName}` | Full path to the message file. |
| `{MessageCount}` | The number of messages quarantined for a user in a specific folder and listed in a message digest email. |
| `{MessageDigestTableText}` | The plain text version of a message digest detail listing. See also `{$MessageDigestTableHTML}`. **Note:** The plain text version does not use any detail level or option settings. |
| `{MessageName}` | Filename only of the message. |
| `{MessageSize}` | The size of the message as originally received. |
| `{MMSmtpMapsRBL}` | **Note:** This variable name is deprecated. Use `{ReputationServices}`. |
| `{PolicyGroupTitle}` | The title of the policy group containing the rule triggered by the message. Replaces `{RulesetTitle}`. |
| `{RawSubject}` | Message subject with any encoding included, as originally received. Use this variable to include the subject in the Subject field of notification templates. See also `{Subject}`. |
| `{Recipient}` | Message recipient. Includes multiple recipients and CC recipients. |
| `{ReleasePassThrough}` | Inserts a code recognized by the gateway to release the message applying no further rules. See [Using the Message Release External Command](/documentation/mailmarshal/user-guide/delegating-spam-and-quarantine-management.md#using-the-message-release-external-command). |
| `{ReleaseProcessRemaining}` | Inserts a code recognized by the gateway to release the message applying any additional applicable rules. See [Using the Message Release External Command](/documentation/mailmarshal/user-guide/delegating-spam-and-quarantine-management.md#using-the-message-release-external-command). |
| `{RemoteDomainName}` | The name of the domain on the remote machine (connecting email server). |
| `{RemoteIP}` | The IP of the remote machine. |
| `{ReplyTo}` | SMTP "Mail From" email address. |
| `{ReputationServices}` | A list of Reputation Services (DNS blocklists) that triggered on the message within a Connection Policy rule. Does not include information generated by the Category Script (SpamCensor) process. |
| `{ReturnPath}` | SMTP "Mail From" email address. |
| `{RuleTitle}` | The title of the rule triggered by the message. |
| `{Sender}` | Email address of the sender. Uses the address in the "From" field unless it is empty, in which case the SMTP "Mail From" email address is used. |
| `{SenderIDFrom}` | The address used for the Sender ID check. |
| `{SenderIDIPAddress}` | The IP address used for the Sender ID check. |
| `{SenderIDResult}` | The result of the Sender ID check (`Pass`, `Fail`, `None`, `SoftFail`, `Neutral`, `TempError`, or `PermError`). |
| `{SenderIDReturnedExplanation}` | The text explanation returned from the Sender ID query (if any). |
| `{SenderIDScope}` | The scope of the Sender ID check (`pra` or `mfrom`). |
| `{SenderIP}` | IP address of the sender. |
| `{ServerAddress}` | Email address used as the 'From' address for notifications as set during post-installation configuration and accessible from the Notifications section of MailMarshal Properties. |
| `{SpamBotCensorResult}` | The result string as returned by the SpamBotCensor facility. |
| `{SpamBotCensorScore}` | The numeric score as returned by the SpamBotCensor facility. |
| `{SpamCategoryResult}` | The result string as returned by a Category script rule condition (other than SpamCensor or SpamBotCensor). If you run more than one Category condition on a message, this variable returns only the result of the latest condition (at the time the variable is used). |
| `{SpamCategoryScore}` | The numeric score as returned by the latest Category script rule condition (other than SpamCensor or SpamBotCensor). If you run more than one Category condition on a message, this variable returns only the score of the latest condition (at the time the variable is used). |
| `{SpamCensorResult}` | The result string as returned by the SpamCensor facility. |
| `{SpamCensorScore}` | The numeric score as returned by the SpamCensor facility. |
| `{SPFExplanation}` | The default explanation configured in the SPF Settings window, or the text explanation returned from the SPF query (if any) |
| `{SsmUrl}` | The URL of the MailMarshal Spam Quarantine Management Website. You can change this value on the Administrator tab of the SQM website. |
| `{StrippedFiles}` | The names of any attachment files stripped from the message by rule action. |
| `{Subject}` | Message subject, decoded if applicable. Use this variable in most cases. See also `{RawSubject}`. |
| `{ThreadWorking}` | The MailMarshal working folder name. |
| `{Time}` | The current time. See also [Date Formatting](#date-formatting). |
| `{TimeEnteredQueue}` | The time that the message entered the MailMarshal Queue. |
| `{TimeLeft}` | The time left to attempt delivering the message in question. |
| `{UnsubscribeUrl}` | The URL used to unsubscribe from digests. This variable can be used in digest templates. The variable evaluates blank if a user cannot unsubscribe. Suggested usage: `{if UnsubscribeUrl}To unsubscribe from this digest, use the following link: {UnsubscribeUrl} {endif}` |
| `{VirusName}` | Name of the virus detected. This information is only available if the virus scanner being used is a DLL based scanner. If a command line scanner reports a virus this variable is set to "Unknown." |
| `{VirusScanner}` | Name of the virus scanner used. |

### Date Formatting

When you use dates in variables within message templates, message stamps, and logging classifications, you can include formatted dates. This feature is especially useful to avoid confusion about the order of day, month, and year in dates.

To use date formatting, include the template variable `{date=%%var}` where var is one of the sub-variables from the table below. You can include more than one sub-variable within the same date variable. For instance `{date=%%d %%b %%Y}` would return `07 Apr 2004`.

> [!NOTE]
>
> **Note:** Each sub-variable must be preceded by %%. For example, to ensure that the date is formatted according to the Windows locale, use `{date=%%c}`.
>
> To use locale-specific settings you must ensure that the Windows locale is applied to the account used by MailMarshal services. For more information, see Knowledgebase article Q12670.

The following table lists the available date formatting sub-variables:

**Table 22: Date formatting variables**

| Variable | Value inserted |
| - | - |
| a | Abbreviated weekday name |
| A | Full weekday name |
| b | Abbreviated month name |
| B | Full month name |
| c | Date and time representation appropriate for locale |
| d | Day of month as decimal number (01–31) |
| H | Hour in 24-hour format (00–23) |
| I | Hour in 12-hour format (01–12) |
| j | Day of year as decimal number (001–366) |
| m | Month as decimal number (01–12) |
| M | Minute as decimal number (00–59) |
| p | Current locale's A.M./P.M. indicator for 12-hour clock |
| S | Second as decimal number (00–59) |
| U | Week of year as decimal number, with Sunday as first day of week (00–53) |
| w | Weekday as decimal number (0–6; Sunday is 0) |
| W | Week of year as decimal number, with Monday as first day of week (00–53) |
| x | Date representation for current locale |
| X | Time representation for current locale |
| y | Year without century, as decimal number (00–99) |
| Y | Year with century, as decimal number |
| z | Time-zone name or abbreviation; no characters if time zone is unknown |

## Using Virus Scanning

You can implement virus/malware scanning as an email policy element. For more information, see [Stopping Viruses and Malware](/documentation/mailmarshal/user-guide/implementing-email-content-security-policy.md#stopping-viruses-and-malware).

## Using Folders and Message Classifications

MailMarshal uses a Microsoft SQL Server database to log basic information about each message it has processed. This information includes the sender, recipient, message size, and actions taken.

If MailMarshal moves or copies a message to a folder, it logs this event in the database.

Using Message Classifications is another way to add detail to the log records. You can add Message Classifications by including an action within a MailMarshal Content Analysis Policy rule. You can view the classification given to a particular message using the Console Message History or reports from Marshal Reporting Console.

You should include at least one logging action (either a folder action or a Classification action) in each Content Analysis Policy rule. MailMarshal default rules include such actions.

> [!NOTE]
>
> **Note:** To avoid confusion in reporting, MailMarshal will not allow a folder and a classification with the same name.

### Working with Message Classifications

Message Classifications are useful for reporting on broad categories, such as viruses or executable files quarantined. You can also use classifications to record very specific occurrences such as a specific file or size of file being sent. For example you could answer the question "How many PDF files over 500K in size are sent by Sales each week?" by creating a rule to log sending of such files. If several rules place messages in a single MailMarshal folder, you can use classifications to give additional granularity for searching and reporting.

To work with classifications, in the left pane of the Management Console, select **Policy Elements**. Then select **Classifications** from the right pane menu. To create a message classification:

1. On the menu above the list, choose **Add.**
2. In the window, enter a meaningful name for the classification.
3. Give a brief description of the classification and its purpose. This description will be used in the Console and Reports, and can contain `{ }` variables as in message stamps and templates.
4. To add the classification, click **Save**.

#### Editing Message Classifications

You can edit the name and description of a classification.

To edit a message classification:

1. Double-click the classification name in the right pane of the Management Console to view its properties.
2. Make any required changes.
3. Click **Save.**

#### Duplicating Message Classifications

You can make a copy of a classification if you want to use it as the starting point for another classification.

To duplicate a message classification:

1. Right-click the classification name in the Management Console.
2. Choose **Duplicate** from the context menu.
3. After duplicating the classification, make any required changes to the copy.

#### Deleting Message Classifications

You can delete a classification if it is not used in any rules.

To delete a message classification:

1. Select the classification name in the right pane of the Management Console.
2. Click the **Delete** icon in the toolbar.

### Working with Folders

MailMarshal uses folders to store messages that it has quarantined, parked for later delivery, or archived. You can delete quarantined messages, release them to the recipient, and manage quarantined messages in other ways.

MailMarshal also uses special "Dead Letter" folders to store messages that it could not completely process. You can manage messages in these folders in many of the same ways that you can manage quarantined messages.

You can configure folders with specific security settings. You can configure folders to be available for end-user management through the Spam Quarantine Management console. You can configure folders to allow "fingerprinting" of released messages.

> [!NOTE]
>
> **Note:** In earlier versions of MailMarshal you could configure the default action that MailMarshal took if a message was released from a folder. This option has been replaced by the "release action" option in rule actions. For more information, see [Copy the message](/documentation/mailmarshal/user-guide/email-policy-groups-and-rules.md#copy-the-message) and [BCC a copy of the message](/documentation/mailmarshal/user-guide/email-policy-groups-and-rules.md#bcc-a-copy-of-the-message).

MailMarshal includes predefined folders that address common email security issues and automatically categorize quarantined mail. MailMarshal provides many predefined folder types, including folders that:

* Hold messages quarantined due to rule action (for instance, messages that are categorized as spam, virus infected, contain disallowed attachments, or blocked for other policy reasons).
* Hold archived messages.
* Hold historical information about delivered messages (Sent History).
* Hold messages that MailMarshal cannot process or cannot deliver, called dead letters. Dead Letters can result from bad email addresses, from corrupted data, from differing interpretations of Internet standards, or when a message is intentionally malformed in an attempt to exploit a security vulnerability.

Predefined and newly-created folders have default properties that you can modify. For example you can specify a custom file system location for a folder.

If existing MailMarshal folders are not appropriate for your needs, modify the properties of an existing folder or create your own folders.

### Creating Folders

You can create as many folders as your policy requires. You can create the following types of folders:

**Standard Folder**

Used to quarantine dangerous or suspect mail. You can specify that an administrator or regular user can manage the folder contents through SQM. You can specify that messages released from the folder are eligible for attachment fingerprinting.

**Archive Folder**

Used to keep historic copies of delivered mail. MailMarshal saves messages stored in the folder for a specific period of time. You cannot manually delete mail stored in an archive folder. You can specify that messages released from the folder are eligible for attachment fingerprinting.

**Parking Folder**

Used to delay the delivery of mail. MailMarshal releases messages stored in the folder according to a predefined schedule.

To create a folder:

1. In the left pane of the Management Console, select **Policy Elements**. Then select **Folders** from the right pane menu.
2. On the menu above the list, click **Add.**
3. Specify the appropriate values. For more information about available settings, click **Help**.
4. Click **Save.**

### Editing Folders

You can change the name and most features of a folder. You cannot change the type of an existing folder. You cannot change the name of dead letter folders.

To edit a folder:

1. In the left pane of the Management Console, select **Policy Elements**. Then select **Folders** from the right pane menu.
2. Double-click the folder you want to modify.
3. Specify the appropriate values. For more information about available settings, click **Help**.
4. Click **Save**.

#### Deleting Folders

You can delete a folder if it is not used in any rules. You cannot delete dead letter folders.

To delete a folder:

1. In the left pane of the Management Console, select **Policy Elements**. Then select **Folders** from the right pane menu.
2. Click the **Delete** icon on the menu above the list.

Deleting a folder in the Management Console deletes only the link to the folder that appears in the Management Console. This action does not delete the physical folder or any email messages it contains. To delete email messages use the Folders or Message History items in the Management section of the Management Console. To delete the folder on disk and its contents use Windows tools.

#### Configuring Default Folder Access

You can set the default folder permissions to control user ability to view and manipulate items in most MailMarshal folders.

To configure default access permissions for MailMarshal folders:

1. In the left pane of the Management Console, select **Policy Elements**. Then select **Folders** from the right pane menu. Click **Default Folder Security**.
2. This pane displays a list of security objects. Available object types include MailMarshal roles, MailMarshal Users, and Windows users and groups. Click an object name to show the permissions that role has over the features of MailMarshal folders.

   > [!TIP]
   >
   > **Tip:** Windows objects are only shown if Windows Authentication is used for the Management Console. To enable Windows Authentication, use the Config Service Admin Tool (see [Using the Config Service Admin Tool](/documentation/mailmarshal/user-guide/managing-configuration.md#using-the-config-service-admin-tool)).

   * To add items to the list, click **Add** then select the items. You can see and add individual users by selecting an item and selecting **Show Users**. Each item you add is given full permissions by default.
   * To delete an item from the list, select it and click **Delete**.
3. To change permissions for an item highlight the name. The lower pane shows the current permissions for this item. Set permissions by selecting the appropriate options.
   * A user could be a member of more than one role, and can also be listed individually. In this case, you can choose how permissions are applied by ordering the list. For details, see Help.
4. To save the changes, click **Save**.

#### Configuring Access for a Specific Folder

Set the permissions on a particular folder to control user ability to view and manipulate items in that folder. Permissions on a specific folder override the default folder permissions.

To configure access permissions for a specific MailMarshal folder:

1. In the left pane of the Management Console, select **Policy Elements**. Then select **Folders** from the right pane menu.
2. In the right pane, edit a specific folder. Enable the item **Override default folder security** to show the Security tab.
3. This pane displays a list of security objects as described above. Click a name to show the permissions that role has over the features of the specific MailMarshal folder.
   * To add items to the list, click **Add** then select the items. Each item you add is given full permissions by default.
   * To delete an item from the list, select it and click **Delete**.
4. To change permissions for an item highlight the name. The lower pane shows the current permissions for this item. Set permissions by selecting the appropriate options.
   * A user could be a member of more than one role, and can also be listed individually. In this case, you can choose how permissions are applied by ordering the list. For details, see Help.
5. To save the changes, click **Save**.
6. To apply the changes, click the **Commit** button in the toolbar.

> [!NOTE]
>
> **Note:** Setting access permissions for a folder in MailMarshal does not affect the Windows file permissions for the folder or items in it. To limit access through Windows, set the Windows access permissions for the MailMarshal Quarantine folder and all items in that folder on each MailMarshal email processing server.
>
> To ensure that only the users with MailMarshal permissions can access these items, give full control of the Quarantine folder to the LocalSystem account or other account used by the MailMarshal services, and deny access to all other accounts.

## Header Matching and Rewriting

MailMarshal can perform searches and replace text in email headers using a Regular Expression engine. You can apply rewriting globally when messages are received. You can also perform header searches and header replacements within Content Analysis Policy rules.

> [!WARNING]
>
> **Caution:** Regular Expression matching and substitution provides very powerful capabilities. However, regular expressions are complex and can be difficult to construct. If headers are rewritten incorrectly, you may be unable to determine the sender or intended recipient of affected messages. Use this facility with care.

### Changing and Adding Headers with the Receiver

MailMarshal provides global header rewriting to modify email header and envelope detail. Global rewriting is typically used to allow email aliasing. This action is performed by the MailMarshal Receiver during email message receipt.

Some examples of actions that can be performed are

* Address modification: for example, changing [user@host.domain.com](mailto:user@host.domain.com) to [user@domain.com](mailto:user@domain.com).
* Field removal: for example, stripping out the received: lines from outbound messages.
* Alias substitution: for example, replacing addresses via a lookup table, as in [user1@olddomain.com](mailto:user1@olddomain.com) being replaced by [user2@newdomain.com](mailto:user2@newdomain.com).
* Domain masquerading: for example, replacing all addresses in thisdomain.com with identical addresses in thatdomain.com.

To work with global header rewriting:

1. In the Management Console, select **System Configuration** and then expand **Receiver Properties**.
2. Select **Header Rewrite** from the right pane menu.
3. You can add a new global header rewrite rule, edit an existing rule, or delete an existing rule. You can also change the order of evaluation of the rules. For details of the rule editing processes, see [Using the Header Rewrite Editor](#using-the-header-rewrite-editor).

### Using Rules to Find Headers

You can search email headers using regular expressions using the MailMarshal Content Analysis Policy rule condition "Where message contains one or more headers." This rule condition allows matching based on the presence of specific email message headers, or specific content within any header.

To create a header match condition, in the rule condition window click **New.**

To perform more than one header match within a single condition, add a new header match rule for each match.

> [!NOTE]
>
> **Note:** If more than one header to match is entered within a single rule condition, all expressions must match for the condition to be true (logical AND). To check any of several headers (logical OR), use one rule per header.

For details of the rule editing processes, see [Using the Header Rewrite Editor](#using-the-header-rewrite-editor).

### Using Rules to Change Headers

You can alter email headers using regular expressions using the MailMarshal Content Analysis Policy rule action "Rewrite message headers using expressions." This rule action allows matching based on the presence of specific email message headers, or specific content within any header.

To create a header rewrite action, within the rule action window click **Add.**

To perform more than one header rewriting action within a single condition, add a header match rule for each header rewriting action.

> [!NOTE]
>
> **Note:** If more than one header to rewrite is entered within a single rule, the order in which rewriting is applied will be significant. Rewriting actions will apply in top down order as they are listed in the rule action window. To change the order, use the arrows in the window.

For details of the rule editing processes, see [Using the Header Rewrite Editor](#using-the-header-rewrite-editor).

### Using the Header Rewrite Editor

This panel allows you to create a header matching or header rewriting rule. Header matching and rewriting uses regular expression matching and substitution. For more information about regular expressions, see [Regular Expressions](/documentation/mailmarshal/user-guide/wildcards-and-regular-expressions.md#regular-expressions).

The header rewrite editor includes two tabs:

* On the General tab you can name the rule, select the header or envelope fields to be matched, select the portion of the field to be modified and choose logging options.
* On the Expressions tab you can enter matching and substitution expressions and test the rule.

You can also change the order of evaluation of header rewriting rules using the Move Up and Move Down buttons on the parent panel.

To use the Header Rewrite editor:

1. On the General tab, enter a name for the rewrite rule.
2. Optionally enter a comment to explain the purpose of the rule.
3. Choose a parsing method from the list. Depending on this selection, MailMarshal will apply regular expression matching to parts or all of the selected headers.

   > [!NOTE]
   >
   > **Note:** To insert a custom header, use the parsing method "Entire Line." To match or modify all email addresses, use the method "Email Address".

   * If you select the method "Entire Line" MailMarshal will use the entire text of the header as the input text for the substitution engine.
   * If you select the method "Email Address" MailMarshal will use each email address found in the line as the input text.
   * If you select the method "Domain" MailMarshal will use the domain part of each email address as the input text.
4. Select (toggle on) **Match Case** to perform a case sensitive search. Clear this option to make the search case insensitive.

   > [!NOTE]
   >
   > **Note:** To search for email addresses or domains, use a case insensitive search.
5. *If this is a rewriting rule,* select whether the changes will be actually applied and/or logged. Select the check box **Enable field changes** to apply this rule to messages. Select the check box **Log changes** to write a log of changes to the MailMarshal logs for the message. If only **Log changes** is selected, the logs will show the changes that would have occurred.
6. Select the fields that you want the rule to apply to from the list. You can add one or more custom header field names.\
    ![Header Rewrite Rule General tab with parsing method and header fields](https://mintcdn.com/levelblue-5324744e/x21QTv9fJshn3W3y/images/mailmarshal/header-rewrite-general.png?fit=max\&auto=format\&n=x21QTv9fJshn3W3y\&q=85\&s=0b4685890508252c4ea4efa376476238)
7. Click **Expressions** to continue.
8. In the **Optional Exclusion Filter** field, you can enter a regular expression. If this expression is found in the input text, the search will return "not matched".
9. In the **Field Search Expression** field, enter a regular expression that MailMarshal should use to select the data for matching or rewriting. If the input text matches this expression, the rule will match or rewrite it, subject to exceptions based on the exclusion filter.
10. *If this is a rewriting rule,* choose one of the rewriting methods:
    * **Substitute into field using expression** replaces the matched data using a sed or Perl-like syntax. You can use sub-expressions generated from the field search here. Refer to the sub-expressions as $1 through $9.

      > [!NOTE]
      >
      > **Note:** If you replace the entire contents of a field, be sure to terminate the text with a CRLF (`\r\n`). You can insert this value through the arrow to the right of the field. If you enter \$0 (the tagged expression containing the entire input line) at the end of the substitution expression, a CRLF will already be included.
    * **Map using file** provides for substitutions from a file, to allow a level of indirection in resolving what to substitute into the field. For details of syntax, see [Regular Expressions](/documentation/mailmarshal/user-guide/wildcards-and-regular-expressions.md#regular-expressions). For details of where to place the file, see Help.
    * **Delete the field** removes the matching material from the header. When **Entire line** is selected in the parsing options, selecting Delete the field removes the entire header line from the message.
    * **Insert if missing** permits you to add a new header if any of the selected headers does not exist. MailMarshal will use the text of this field as the value of the new header line. For instance if you have added the custom header `x-MyNewField` then you might enter the value `Created by Header Rewrite.`
      > [!NOTE]
      >
      > **Note:** In Content Analysis rule header rewriting, you can include MailMarshal variables in the Substitute or Insert text. For details, see Help.
11. To test the rule, enter an input string in the **Source** field and click **Test.** The result will appear in the **Result** field. For rewriting actions, the result will be the rewritten string. For matching, the result will be "matched" or "not matched".\
     ![Header Rewrite Rule Expressions tab with search expression, substitution, and test fields](https://mintcdn.com/levelblue-5324744e/x21QTv9fJshn3W3y/images/mailmarshal/header-rewrite-expressions.png?fit=max\&auto=format\&n=x21QTv9fJshn3W3y\&q=85\&s=378561af111644ea16a73c853dd025b2)
12. *If this is a rewriting rule,* adjust the order of evaluation using the arrows provided below the list of rules.

> [!NOTE]
>
> **Note:** If you use several header matching rules within a single Content Analysis Policy rule condition, all must evaluate true for the condition to be true.
>
> If you create several rewriting rules for global Header Rewrite or within a single Content Analysis Policy rule action, the order of evaluation will be significant. Rewriting actions will be applied in top-down order as shown on the window.

## Extending Functionality Using External Commands

An external command is a custom executable, Windows command, or batch file that can be run by MailMarshal. The command can be used to check email messages for a condition, or to perform an action when a message meets some other condition.

You can use custom executable files or batch files with the Content Analysis Policy rule condition "Where the external command is triggered." For instance, you can invoke fgrep.exe for advanced expression matching.

If you want to use an external command to check for a condition, the command must return a standard return code.

You can also use custom executable files with the Content Analysis Policy rule action "Run the external command." For instance, a particular email subject line could trigger a batch file to start or stop a system service, or to send a page or network notification to an administrator.

> [!NOTE]
>
> **Note:** If a command action changes the message or attachments, you must set an option on the rule action to force the message to be repacked. For details, see [Run the external command](/documentation/mailmarshal/user-guide/email-policy-groups-and-rules.md#run-the-external-command).

MailMarshal is provided with an external command for message release. See [Using the Message Release External Command](/documentation/mailmarshal/user-guide/delegating-spam-and-quarantine-management.md#using-the-message-release-external-command).

To use an external command in MailMarshal rules, you must first define it.

To create or edit an external command definition:

1. In the left pane of the Management Console select **Policy Elements**. In the right pane menu select **External Commands.**
2. To create a new external command, on the menu above the list click **Add.** To edit an existing external command, double-click an item in the list.
3. Enter a name for the external command.
4. Type the path for the executable file. You can also browse for the file by clicking **Browse**.

   > [!NOTE]
   >
   > **Note:** To use a batch file, you must invoke the command interpreter explicitly as follows:
   >
   > `%Systemroot%\system32\cmd.exe /C {batchfile.cmd} [variables...]`
5. In the **Parameters** field, enter any command line parameters necessary for the command. You can pass specific information about a message to the command using MailMarshal variables. Particularly note the variable `{CmdFileName}`.
6. The **Timeout** and **Timeout per MB** values control how long MailMarshal will wait for a response before ignoring the external command. The default values are very generous.

   > [!NOTE]
   >
   > **Note:** If the external command executable uses 10% of the timeout time in actual processing (CPU usage), MailMarshal will terminate the command, log the event as a runaway process, and place the message in the Dead Letter\Unpacking folder.
7. The **Single Thread** setting indicates whether the command must operate on one message at a time, or can be invoked multiple times. In most cases this box should be left selected. You can multi-thread certain executable files.
8. The **Only execute once for each message** setting determines whether an external rule condition command will be run for each component of a message, or only once. For example if you are using fgrep to perform Regular Expression searches of attached files, this box should be cleared to ensure that MailMarshal passes each component of each message to fgrep.exe.
9. If you plan to use the external command as a rule condition, you must set the trigger return code information. You should find this information in the documentation of the executable.\
    ![External Command window for the Message Release command](https://mintcdn.com/levelblue-5324744e/x21QTv9fJshn3W3y/images/mailmarshal/external-command.png?fit=max\&auto=format\&n=x21QTv9fJshn3W3y\&q=85\&s=f7267614a5db508f0f3b7d344233313c)

Two fields allow you to enter trigger values which further specify the meaning of the code returned from the virus scanner.

* If the code returned matches any value entered in the field **Command is triggered if return code is**, MailMarshal will consider the condition to be satisfied.
* If the code returned matches any value entered in the field **Command is not triggered if return code is,** MailMarshal will consider the condition not to be satisfied.
* If the code returned matches neither field, the file is moved to the Undetermined dead letter folder and an email notification is sent to the MailMarshal administrator.
* Entries in both return code fields can be exact numeric values, ranges of values (for example 2-4), greater than or less than values (for example \<5, >10). More than one expression can be entered in each field, separated by commas (for example 1,4,5,>10).

## Configuring Reputation Services

MailMarshal can retrieve information from DNS based blocklists or Reputation Services, including the Marshal IP Reputation Service and third-party services such as SpamCop and Spamhaus.

Configuring a DNS Blocklist for use in MailMarshal is a two step process. You configure details of the list in Policy Elements, then you configure one or more Connection Policy rules to filter email based on the list information

For more information about configuring Reputation Services, see [Controlling Who Can Send Email Through Your Server](/documentation/mailmarshal/user-guide/implementing-email-content-security-policy.md#controlling-who-can-send-email-through-your-server). For details of the information on the Reputation Services window of the Management Console, see Help.