logo
  Tags and Macros
 logo
[Tags] [Macros]
[|Tab| and |NewLine| macros]
[Sending exclusions (e.g. "Don't send if")]
[Tags and macros in RETURN-TO]
[Examples of using Macros]

Tags

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...
etc.
 

macros Macros

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:
 
CONTAINS DOESN'T CONTAIN
EQUALS DOESN'T EQUAL
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 Message mode, after saying "OK" to the Macros Dialog, CustomMailer will re-expand your message from the current message template for the currently selected mailing list row, exactly as if you had clicked on that row.  This is because the change of macro rules may affect the expansion of the macros in your message template.  Likewise, the message re-expands if you edit the data in your mailing list or change your tag indicator character in Preferences, since these changes might also cause the message to change.
 

|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 (since CustomMailer automatically wraps long lines).  Whole sections of a message can be swapped in and out based on data in your mailing list.  However, note that because of the user interface in the Macros Dialog, it is not possible to type a tab character or a newline character into a macro result field because typing a tab instead causes the cursor to jump to the next text entry field and newline ("Enter") is the same as hitting 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. 


Sending exclusions

Tags and macros can be used in two other special ways called "Sending exclusions".  The two sending exclusions are called "Don't Send If" and "Don't Send HTML If".  Both of these are controlled from the Preferences dialog under the Message sending tab.

Don't send if: This features allows you to use a tag or macro to control whether to send email to any given recipient.  A popup menu in the Preferences dialog by default has the value "Always send", in which case all selected mailing list rows will be sent.  Or you can use the popup to choose any tag (= mailing list column name) or macro plus specify a value for it to EQUAL.  In this case, when CustomMailer attempts to send each selected row in your mailing list, it first evaluates the tag or macro for that recipient and determines if the resulting value is EQUAL to the value you specify (this test is case-sensitive).  If so, the email is not sent for that row even though it was selected, otherwise it will be sent.

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.

Don't send HTML if:  This features allows you to use a tag or macro to control whether to send HTML mail or plain text mail to a given recipient.  A popup menu in the Preferences dialog by default has the value "Always send HTML", in which case all selected mailing list rows will be sent HTML email (including the Alternate Text portion).  Or you can use the popup to choose any tag (= mailing list column name) or macro plus specify a value for it to EQUAL.  In this case, when CustomMailer attempts to send each selected row in your mailing list, it first evaluates the tag or macro for that recipient and determines if the resulting value is EQUAL to the value you specify (this test is case-sensitive).  If so, only the Alternate Text portion of your email is sent as a plain text message for that row, otherwise the HTML message is sent (including the Alternate Text portion).

This feature is useful for distinguishing which of your recipients prefer to receive plain text email instead of HTML mail.  For example, you might add a column called HTML and insert a "N" for those recipients who should only receive plain text email.


Tags and macros in RETURN-TO

The RETURN-TO message header field lets you specify a special return address for bounced messages that can be different from the FROM address and different from the REPLY-TO address.  The fact that this field can be customized on a per-recipient basis provides for a particularly useful technique called Variable Envelope Return Paths.  Because of the many inconsistent replies that SMTP servers generate when messages bounce, it can be difficult to identify just which email sent by you caused the bounced mail so that you can remove it from your list. However, if your email domain (e.g., yourcompany.com) allows you to receive mail addressed to any user name at your domain (whatever@yourcompany.com), you can use tags and macros to encode the email address (or other unique identifier) to which  this email was sent in your RETURN-TO user name.  For example, you might have your RETURN-TO field contain:
   |email|@yourcompany.com
where |email| is a tag specifying the same address that you sent the email to.  

But note that since |email| will itself contain an @ sign, this bounce return address would have two @ signs, which is illegal.  For this reason, CustomMailer will replace the first @ sign in the RETURN-TO field with the sequence -AT- (hyphen A T hyphen).  As a result the bounceback of an undeliverable message sent to:
   recipient@theircompany.com
would be sent to the address:
   recipient-AT-theircompany.com@yourcompany.com
In this way you can easily tell from the return address of any bounced email, exactly which email address sent by you caused it.

If you don't get to control all the email addresses at your company's domain, you can still usually get your system administrator to include a special filter in your company's Send Mail processing (e.g., .procmailrc script) which would route messages starting with a special identifier to your mail box.  In this case, your RETURN-TO field might contain:
   bounce43578-|email|@yourcompany.com
Your administrator would route all emails starting with bounce43578 to your mail box, where you could parse out the |email| portion and use that to find the bouncing address in your mailing list.

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 their first name (you might also want LENGTH = 1  to produce the result:  Dear customer,  to handle the case where the customer entered 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 name@domain.type, 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 results:
         Date doesn't end with 03:             MESSAGE ERROR, message not sent
         Last name missing:                        send message to:   rjones@company.com
         First but not last name missing:      send message to  Mr. Jones <rjones@company.com>
         First and last names given:            send message to:   Robert Jones <rjones@company.com>


Nested macros
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
    etc.

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
    etc.

Usage:   |YearReference|

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.