How to use Custom Rule Data (formerly Dictionaries)

Updated 2 years ago by admin

This article explains how to use the Custom Rule Data feature of Email Security. Custom Rule Data entries are used in Message Rules to detect or insert text as part of conditions or actions. They can be text strings or regular expressions. This article is focussed on how to use the text string variant of Custom Rule Data.

To summarise Rule Data:

  • are simple text strings - for more complex pattern matching see the custom Rule RegEx support
  • they should only contain alpha numeric characters
  • take care when using certain special characters as it can generate unexpected or inconsistent results - see below
  • Rule Data entries are case insensitive by default; you do not need to enter multiple variations of capitalisation
Rule Data is converted into a simple regular expression by the system. Therefore, certain characters can cause inconsistent results. Understanding this will help you to create more effective Rule Data. If the power of a regular expression is required, we recommend using Rule RegEx instead.

Using Special Characters

In the context of Rule Data, a special character is any character outside of A to Z, a to z and 0 to 9.

Consider this example of attempting to locate a telephone number using the Rule Data 001-555-9876.

Behind the scenes, the rules engine will convert the string to a simple regular expression. This means the hyphens are treated as a range indicator, and won't be matched on the literal hyphen character. The end result is that 001556876 would match but the expected 001-555-9876 would not.

This can be resolved by using escaping. The corrected Rule Data to identify the telephone number pattern is 001\-555\-9876. Escaping uses a backslash (\) to tell the system that the special character should be used literally and not be used as part of the regular expression itself.

The table below shows how to escape a character properly for use in Rule Data.

Special Character

Escaped Version for use with Rule Data

.

\.

? (single character wildcard)

.

? (the question mark character)

\?

+

\+

<

\<

>

\>

(

\(

)

\)

[

\[

]

\]

{

\{

}

\}

* (multiple character wildcard match)

.+

* (the asterisk character)

\*

\_

\\_

_ (underscore)

_

^

\^

$

\$

\

\\

|

\|

Notes and Explanation

  • All Rule Data has an implicit wildcard either side of it. You do not need to add one in. e.g. the entry acmemail\.com would match user@acmemail.com and bounces+9812588-819d-user=acmemail.com@sendgrid.net
  • All Rule Data is processed case insensitively. You do not need variations for different capitalisation
  • The dashboard may automatically convert special characters to HTML codes for XSS security. For example, entering \> will be displayed in the Rule Data list as \&gt;. This will not change the behaviour of the Rule Data and can be ignored.
  • The question mark indicates zero or one occurrences of the previous character e.g. Great!? will match "Great!" or "Great". A period . should be used if you are looking for a wildcard character match.
  • An asterisk * may be used as a wildcard however it is not required at the beginning or end of Rule Data.
  • If you want to detect strings within strings or partial strings within strings, you can use .+. For example:

Rule Data example

Example Matches

receive.+alerts

“receive alerts” or “receive system alerts”, etc

bounces\+.+sendgrid.net or bounces\+.+acmemail\.co\.uk@sendgrid\.net

bounces+9812588-819d-tony=acmemail.co.uk@sendgrid.net

\+1.+9876

"+1 555 9876" or "+1 123 9876", etc

How did we do?