|| Tags and Macros
You can use tags anywhere in the message template body or header fields to indicate information to be merged in from a particular column in the mailing list. A tag looks like: |Name| where | is a tag indicator character (you can change the tag indicator character to anything you like in Preferences). Use two tag indicator characters in row if you want an actual tag indicator character to appear in the message. Tags are case-insensitive, so |name|, |Name|, and |NAME| are all treated the same. Your message template will generally contain a number of different tags such as:
Dear |Title| |LastName|: On |Date| you purchased...
CustomMailer uses this as an indication that the values in the mailing list columns labeled Title, LastName, and Date are to be substituted for those tags in the message for each selected recipient before their individualized message is sent, for example, messages for successive recipients might expand to:
Dear Mr. Jones: On 5/15/03 you purchased...
Dear Dr. Francis: On 3/23/01 you purchased...
Dear Ms. Taylor: On 10/12/02 you purchased...
Related to the notion of tags, you can also define a set of
substitution rules called a "macro". Macros are a powerful way to
create highly customized messages based on all the column data for each
recipient in your mailing list. Macros are like "conditional
tags", so that rather than simply substituting a mailing list column
value directly, you can perform tests on any of the values in the given
recipient's mailing list row to control the actual values to be merged
into your message. For example, you might specify a macro
called |WhichYear| with rules like:
IF |Date| ENDS WITH 2003 THEN Earlier this year
IF |Date| DOESN'T END WITH 2003 THEN Prior to this year
You create macros using the Macros dialog under the Settings
menu. Each macro consists of one or more rules. Each rule
is in the form:
IF operand1 operation operand2 THEN result
The value of operand1 is a tag representing any column of your mailing list and is selected from a popup menu in the Macros dialog.
The value of operation can be one of the following 17
values, also selected from a popup menu in the Macros dialog:
|STARTS WITH||DOESN'T START WITH|
|ENDS WITH||DOESN'T END WITH|
|LENGTH =||LENGTH <||LENGTH >|
|DATE =||DATE <||DATE >|
|VALUE =||VALUE <||VALUE >|
The first eight tests are string matching tests and (unlike the case for the Find and Select using Filters commands) are always case-sensitive. The next 3 LENGTH tests work on the length of the value as a string. The next 3 DATE tests work for dates given in most short and long standard formats (e.g. 8/15/00, August 15, 2000, etc.) and uses the internationalized dates, names, and formats appropriate for your country's locale as set in the Windows Control Panel "Regional Settings". If a DATE test encounters a value that isn't a date, it substitutes the date January 1, 1900 for the date. The last 3 VALUE tests work for either plain numbers (integers, such as 23 or -5, or non-integers, like 5.25) or the appropriate currency for your country's locale as set in the Windows Control Panel "Regional Settings". If a VALUE test encounters a value that isn't a number, it substitutes 0 for the value.
The value of operand2 can be any string not containing macros, but it can contain one or more tags, so that tag-to-tag comparisons are possible. For the LENGTH tests, operand2 should evaluate to an integer; and if not, it will be interpreted as 0.
The value of result can be any string, which itself may
contain any number of tags or macros. Because it can contain
macros, macros may be "nested" so one macro may turn into one or more
other macros which may call still more macros and finally produce a
result. As the following examples of possible result
fields show, the result field might include no tags or
macros, one tag or one macro, or multiple tags and/or macros as part of
an overall string:
Thank you for your order which contains no tags or macros
On |Date| you purchased our software where |Date| is a tag
|WhichYear|, you visited our website where |WhichYear| is a macro
Dear |Title| |LastName|: where |Title| is a tag and |LastName| is a macro
When a macro is found in the message template, all of the rules of that macro are evaluated in order, so the last rule that evaluates as "true" will define the final result substituted into the message. All the macros in a message are evaluated in a first pass. These may expand into any combination of strings, tags, and possibly more macros. Any new macros thus generated are evaluated in second pass, which may introduce further macros. Multiple passes are used until no more macros remain.
It is an error if you define "circular macros", that is, macros that directly or indirectly generate copies of themselves, since they can never finish evaluating.. CustomMailer detects this condition and reports a "MACRO/TAG ERROR" and will not send the message.
After one or more passes succeed in expanding all the macros, a final pass is used to expand any remaining tags using mailing list column values. Notice that if you have a macro called |Name| as well as a mailing list column called Name, then using |Name| in your message will never access the mailing list column called Name since either |Name| will go away during the macro expansion passes or |Name| will be detected as a circular macro.
NOTE: To catch errors caused by unexpected data values, each macro used in the message is expected to have at least one rule that evaluates as "true". If a recipient has data values for which any given macro has all rules "false" , you get a "MACRO/TAG ERROR" for this recipient and the message won't be sent. This feature permits a form of error checking on the data fields in your mailing list simply by making sure all rules evaluate to "false" for illegal values. See example below.
All tag names, whether used as macros or mailing list column
headings, are case-insensitive, so |Name|, |name|,
and |NAME| are all treated the same. However, all of
the string tests within the macro rules are case-sensitive, so
you should use separate rules if you want to test different cases, e.g.
IF |Date| CONTAINS Feb THEN February
IF |Date| CONTAINS feb THEN February
Also, the strings in the result field are used with their case preserved.
A Macros dialog is provided for creating and editing your macros. First, you can create a new macro, delete a macro, rename a macro, or copy an existing macro. Then, for any given macro, you can add a new macro rule, delete a macro rule, or reorder your macro rules. Your current set of macros are automatically remembered across runs of CustomMailer. Most customers think of macros as a set of standard rules and message parts they build up and reuse across different mailings they compose. Macros may also be written to or read from an external file. This allows different sets of macros to be swapped in and out if that is desired. The macros will be written as a tab-delimited plain text file with one rule per line using the macro name in the first column. This makes the macros file suitable for use in a spreadsheet program such as Microsoft Excel, which can further assist creation and editing of macro rules.
If you make any changes to your macros and you are in View as
after saying "OK" to the Macros Dialog, CustomMailer will re-expand
message from the current message template for the currently selected
list row, exactly as if you had clicked on that row. This is
the change of macro rules may affect the expansion of the macros in
message template. Likewise, the message re-expands if you edit
data in your mailing list or change your tag indicator character in
Preferences, since these changes might also cause the message to
|Tab| and |NewLine| macros
The macro result fields can be short phrases as in the
examples above, but they can be long sentences or paragraphs as well
CustomMailer automatically wraps long lines). Whole sections of a
message can be swapped in and out based on data in your mailing
However, note that because of the user interface in the Macros Dialog,
is not possible to type a tab character or a newline character into a
macro result field because typing a tab instead causes the
jump to the next text entry field and newline ("Enter") is the same as
the OK button.
For this reason, CustomMailer provides two optional pre-defined macros: |Tab| and |NewLine|. To enable either or both of these, go to the Message template tab of Preferences. Once enabled, you can enter |Tab| or |NewLine| in any field of any macro or in your email message itself and upon expansion CustomMailer will substitute a tab character or a newline character, respectively. The tab character may then be expanded into some number of spaces according to the tab stop setting also specified in the Message template tab of Preferences. The |Tab| and |NewLine| macros are optional because you might conceivably have a column in your mailing list named Tab or NewLine, which would be a conflict. Like all other macros, the |Tab| and |NewLine| macro names are case-insensitive, so that |TAB|, |tab|, |Tab|, etc. are all recognized as representing the tab character.
Tags and macros can be used in two other special ways called
The two sending exclusions are called "Don't Send If" and "Don't
HTML If". Both of these are controlled from the Preferences
under the Message sending tab.
Don't send if: This features allows you to use a tag or macro
control whether to send email to any given recipient. A popup
the Preferences dialog by default has the value "Always send", in which
all selected mailing list rows will be sent. Or you can use the
to choose any tag (= mailing list column name) or macro plus specify a
for it to EQUAL. In this case, when CustomMailer attempts to send
selected row in your mailing list, it first evaluates the tag or macro
that recipient and determines if the resulting value is EQUAL to the
you specify (this test is case-sensitive). If so, the email is
sent for that row even though it was selected, otherwise it will be
This feature is useful for disabling rows in your mailing list, for
example by adding a column called Inactive to your
mailing list and inserting a "Y" for those recipients who should
no longer receive email. This makes it easy to disable sending
email to particular recipients without needing to remove them from your
mailing list. By using this feature to specify exactly who should
get email, you can just choose Select All and hit Send. Some
customers prefer this more permanent style of designating recipients
instead of using the more transient method of selecting rows in the
mailing list. Note that the "Set Row Values" tool under the "Edit
Mailing List Column" command provides an easy way to convert selections
into row values.
Examples of using macros
The following examples illustrate possible uses of macros. Note that CustomMailer ships with a set of predefined macros which you may find useful as they are or as a starting point for creating your own macros.
Test for missing data
Rules for macro |Salutation|:
IF |First| LENGTH = 0 THEN Dear customer,
IF |First| LENGTH > 0 THEN Dear |First|,
Usage (as the first line in a message): |Salutation|
This takes care of the case where a customer enters nothing for
name (you might also want LENGTH = 1 to produce the
Dear customer, to handle the case where the customer
their initials and it wouldn't be appropriate to say: Dear B).
Substitute for keywords or abbreviations
Rules for macro |BrowserName|:
IF |Browser| CONTAINS Mozilla THEN Netscape Communicator
IF |Browser| CONTAINS MSIE THEN Microsoft Internet Explorer
Usage: Your browser is |BrowserName|
The result is that if the "Browser" column contains "Mozilla", you
get the string:
Your browser is Netscape Communicator
On the other hand, if the "Browser" column contains "MSIE", you get the string:
Your browser is Microsoft Internet Explorer
Rules like these can substitute real words for abbreviations and
codes you may have in your mailing list.
Don't send mail if missing data
Rule for macro |Salutation|:
IF |First| LENGTH > 0 THEN Dear |First|,
Usage (as the first line in a message): |Salutation|
This is almost the same as the first example except that there is no
rule for LENGTH = 0. In this case, if a customer
entered nothing for their first name, the absence of a rule will
generate a MACRO/TAG ERROR for this recipient, resulting in no message
being sent to them.
Use of default values
Rules for macro |HowLongSinceYou|:
IF |Date| EQUALS |Date| THEN It has been a long time since you
IF |Date| ENDS WITH 02 THEN It was some time last year that you
IF |Date| ENDS WITH 03 THEN Earlier this year you
IF |Date| LENGTH = 0 THEN This is the first time you have
Usage: |HowLongSinceYou| visited us.
The first rule, a test for whether |Date| EQUALS
itself, is always true. Rules are evaluated in order so the last
rule that is true will determine the final result. So, this first
always-true rule provides a default answer if no subsequent
rule evaluates to "true". Other rules that always evaluate to
"true" are STARTS WITH empty string, or CONTAINS
empty string, and LENGTH > -1. The above macro has
the following results:
Date missing: This is the first time you have visited us.
Date ends in 03: Earlier this year you visited us.
Date ends in 02: It was some time last year that you visited us.
Any other year: It has been a long time since you visited us.
Using address to control whether to send message
Rules for macro |EmailAddressing|:
IF |Email| STARTS WITH THEN |First| |Last| <|Email|>
IF |First| LENGTH = 0 THEN |Title| |Last| <|Email|>
IF |Last| LENGTH = 0 THEN |Email|
IF |Date| DOESN'T END WITH 03 THEN Don't send
Usage (in the TO: field): |EmailAddressing|
The last rule says that if the date wasn't this year, use the email
address "Don't send". Recall that when the address is
not of the form email@example.com, CustomMailer generates a
"MESSAGE ERROR" and automatically doesn't send the email message.
Thus, macro rules provide another way to select whether or not to send
messages to particular recipients. This macro has the following
Date doesn't end with 03: MESSAGE ERROR, message not sent
Last name missing: send message to: firstname.lastname@example.org
First but not last name missing: send message to Mr. Jones <email@example.com>
First and last names given: send message to: Robert Jones <firstname.lastname@example.org>
Rules for macro |YearReference|:
IF |Date| ENDS WITH THEN On |Date|
IF |Date| ENDS WITH /01 THEN In 2001
IF |Date| ENDS WITH /02 THEN In |MonthName| of last year
IF |Date| ENDS WITH /03 THEN On |MonthName| |DayName|
Rules for macro |MonthName|:
IF |Date| STARTS WITH 01/ THEN January
IF |Date| STARTS WITH 02/ THEN February
IF |Date| STARTS WITH 03/ THEN March
Rules for macro |DayName|:
IF |Date| CONTAINS /01/ THEN 1st
IF |Date| CONTAINS /02/ THEN 2nd
IF |Date| CONTAINS /03/ THEN 3rd
IF |Date| CONTAINS /04/ THEN 4th
This set of macros processes dates of the form mm/dd/yy. The DayName macro (you would have 31 rules in all) converts /dd/ in the middle of the date into the names 1st, 2nd, 3rd, etc. The MonthName macro (you would have 12 rules in all) converts the mm/ at the beginning of the date into the appropriate month name. Then, the overall YearReference macro produces difference phrases for different years, calling the MonthName and DayName macros as needed.
In addition, if you look carefully at the macros that come with CustomMailer, you will find that:
MonthName contains 9 additional rules like
IF |Date| STARTS WITH 1/ THEN January
to cover dates beginning with a single digit month.
DayName contains 9 more rules like
IF |Date| CONTAINS /1/ THEN 1st
to cover dates containing a single digit day.
YearReference contains 3 more rules like
IF |Date| ENDS WITH /2003 THEN On |MonthName| |DayName|
to cover dates ending with a four digit year.
Tags and macros in file attachments names, CC, BCC, PRIORITY, etc.
Note also that tags and macros can be used for any other header field of the message. Thus, tags and macros can be used to control whether file attachments are to be sent along with the message and if so which ones. Or they can be used to control whether to CC or BCC a copy of the message to an extra recipient or back to yourself, or to set the message sending PRIORITY to "High", etc.