ARCOS Help: Personalizing Mailings

Personalizing Mailings

One way is to create a segment that targets a specific group of recipients and to write a message designed specifically for that group. For example, you might create a segment that targets all members within 100 miles of Dallas and then write a message specifically tailored to that audience, perhaps an email announcing an event taking place in Dallas.

This approach works well when you have a small number of segments you want to reach out to, but not so well when you have a large number of segments. For example, if you wanted to send everyone on the list their Senator's phone numbers, you would have to create 50 different segments and 50 different mailings, one for each state in the nation. Clearly this would be quite a pain!

A better way to handle this type of case is to use what's called "mailing expressions" -- a little bit of code you can add to the text body and HTML body to customize your mailing based on the recipient's name, address or any other variable found on the List Fields screen.

Variables You Can Use in Mailing Expressions

The system list fields -- standard, system-generated variables -- that are available to you are:

Prefix: <tmpl_var prefix>
First Name: <tmpl_var first_name>
Middle Name: <tmpl_var middle_name>
Last Name: <tmpl_var last_name>
Address Line 1: <tmpl_var address1>
Address Line 2: <tmpl_var address2>
City: <tmpl_var city>
State: <tmpl_var state>
Country: <tmpl_var country>
ZIP Code: <tmpl_var zip>
Employer: <tmpl_var employer>
Occupation: <tmpl_var occupation>
Email Address: <tmpl_var email>
Phone: <tmpl_var phone>
Phone 2: <tmpl_var phone2>
Fax: <tmpl_var fax>
First contribution amount: <tmpl_var first_contrib_amount>
Last contribution amount: <tmpl_var last_contrib_amount>
Maximum contribution amount: <tmpl_var max_contrib_amount>
First contribution link: <tmpl_var first_contrib_link>
Last contribution link: <tmpl_var last_contrib_link>
Maximum contribution link: <tmpl_var max_contrib_link>
Maximum contribution time: <tmpl_var max_contrib_time>
First contribution time: <tmpl_var first_contrib_time>
Last contribution time: <tmpl_var last_contrib_time>
Maximum contribution time: <tmpl_var max_contrib_time>
Contributions made in current year: <tmpl_var contribution_current_year>
Contributions made in previous year: <tmpl_var contribution_previous_year>
Petitions signed in current year: <tmpl_var petition_current_year>
Petitions signed in previous year: <tmpl_var petition_previous_year>
Volunteered in current year: <tmpl_var volunteer_current_year>
Volunteered in previous year: <tmpl_var volunteer_previous_year>

The custom list fields -- variables specific to your organization -- that are available to you are those variables that appear on the List Fields screen. To use a custom list field variable in a mailing, just type: <tmpl_var variable_name>. For example, if you have custom list fields whose Names are birthday and congressional_district, you would refer to them in a mailing as <tmpl_var birthday> and <tmpl_var congressional_district>, respectively. Remember: The variables available to you in mailings are those that appear on the List Fields screen, and they can be used in mailings by typing <tmpl_var variable_name>. Make sure you are using the list field's Name, not its Display Name.

More information about these variables can be obtained by contacting Plus Three.

Tags You Can Use in Mailing Expressions

The supported tags are:

tmpl_var: Which is written as <tmpl_var variable_name>
tmpl_if: Which is written as <tmpl_if expr="true"> ... </tmpl_if>
tmpl_unless: Which is written as <tmpl_unless expr="true"> ... </tmpl_unless>
tmpl_else: Which is written as <tmpl_if expr="true"> ... <tmpl_else> ... </tmpl_if>

More information about these tags can be obtained by contacting Plus Three.

Operators You Can Use in Mailing Expressions

The supported numeric operators are:

+: Addition
-: Subtraction
*: Multiplication
/: Division
%: Remainder

The supported comparison operators are:

Numeric Comparisons

>: Greater than
<: Less than
==: Equal to
!=: Not equal to
>=: Greater than or equal to
<=: Less than or equal to

String Comparisons

gt: Greater than
lt: Less than
eq: Equal to
ne: Not equal to
ge: Greater than or equal to
le: Less than or equal to

More information about these operators can be obtained by contacting Plus Three.

Examples of Mailing Expressions

Below are some snippets of code that illustrate how to use mailing expressions and some cases where you might want to use them.

To start, a simple example would be to use a mailing expression at the start of your mailing to personalize the salutation as follows:

Dear <tmpl_if first_name><tmpl_var first_name escape=html>
<tmpl_else>Friend</tmpl_if>,

Translated into English, this basically says: If the recipient's first name is stored in ARCOS, start the letter "Dear (First Name),". If not, start the letter "Dear Friend,".

NOTE: Not everyone on your list will have a first_name! As a general rule, you should always make sure that the mailing expression "works" for recipients whose complete information you don't have. If you didn't include the "Friend" part of this example, some of your members would get emails addressed "Dear ,". That wouldn't be good!

A more complex example would be the one we discussed earlier -- sending everyone on your list their Senator's phone numbers. This example boils down to needing to customize the message text depending on what state the recipient lives in. Here is how you would do that:

Please contact your Senators today!

<tmpl_if expr="state eq 'AL'">
   Jeff Sessions (R-AL) (555) 555-5555
   Richard Shelby (R-AL) (555) 555-5555
   
<tmpl_else><tmpl_if expr="state eq 'AK'">

   Lisa Murkowski (555) 555-5555
   Ted Stevens (5555) 555-5555
   
<tmpl_else><tmpl_if expr="state eq 'AZ'">
   etc.
   
<tmpl_else><tmpl_if expr="state eq 'AR'">
   etc.
   
<tmpl_else>
   You can find out who your Senators are by 
   visiting http://www.senate.gov/. 
   
</tmpl_if></tmpl_if></tmpl_if></tmpl_if>

Translated into English, this basically says: If the recipient's state is Alabama, display the Alabama Senators' phone numbers; otherwise, if the recipient's state is Alaska, display the Alaska Senators' phone numbers; etc.

Note that as a very last option we have included a line to be displayed in cases where we don't know in which state the recipient lives.

A third example could be to ask for twice the person's last donation amount.

Thank you for your gift of $<tmpl_var last_contrib_amount>.

In order to continue our efforts, it would be great if you could 
donate an additional $<tmpl_var expr="last_contrib_amount * 2">.

Remember: The * serves as a multiply symbol. To ask for three times the amount you would enter * 3.

Again, one thing to remember is there may not be values for your variables so having an alternative is always a good idea. We could expand on the preceding example as follows in order to take into account the fact that some recipients may not have a last_contrib_amount.

<tmpl_if expr="last_contrib_amount == 0">
   Please consider making a contribution of $25 or more today.
  
<tmpl_else>

   Thank you for your gift of $<tmpl_var last_contrib_amount>.

   In order to continue our efforts, it would be great if you could 
   donate an additional $<tmpl_var expr="last_contrib_amount * 2">.

</tmpl_if>

Special Date/Time Expressions in Mailings

To print today's date in MM/DD/YYYY format (e.g., 12/23/2009):

<tmpl_var expr="today()">

To print today's date in MM-DD-YY format (e.g., 12-23-09):

<tmpl_var expr="today('%m-%d-%y')">

To print today's date and time in MM/DD/YYYY HH:MM:SS format (e.g., 12/23/2009 12:37 pm):

<tmpl_var expr="now()">

You may want to only show some content on certain dates or times. For example, to show certain content if today's date is the 23rd, you would insert the following:

<tmpl_if expr="today('%d') == 23">
   Your content here
</tmpl_if>

To show certain content if the hour is past 9, you would insert the following:

<tmpl_if expr="now('%H') > 9">
   Your content here
</tmpl_if>

Here's more information than you probably will ever need about the different formats you may want to use:

%a: The abbreviated weekday name
%A: The full weekday name
%b: The abbreviated month name
%B: The full month name
%C: The century number as a 2-digit integer
%d: The day of the month as a decimal number (range 01 to 31)
%D: Equivalent to %m/%d/%y
%e: Like %d, the day of the month as a decimal number, but a leading zero is replaced by a space
%F: Equivalent to %Y-%m-%d (the ISO 8601 date format)
%H: The hour as a decimal number using a 24-hour clock (range 00 to 23)
%I: The hour as a decimal number using a 12-hour clock (range 01 to 12)
%j: The day of the year as a decimal number (range 001 to 366)
%k: The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank. (See also %H.)
%l: The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. (See also %I.)
%m: The month as a decimal number (range 01 to 12)
%M: The minute as a decimal number (range 00 to 59)
%p: Either 'AM' or `PM' according to the given time value. Noon is treated as 'PM' and midnight as 'AM.'
%P: Like %p but in lowercase: 'am' or 'pm'
%r: The time in a.m. or p.m. notation.
%R: The time in 24-hour notation (%H:%M). (SU) For a version including the seconds, see %T below.
%S: The second as a decimal number (range 00 to 61)
%T: The time in 24-hour notation (%H:%M:%S)
%u: The day of the week as a decimal, range 1 to 7, Monday being 1. See also %w
%U: The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also %V and %W
%V: The week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week. See also %U and %W
%w: The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u
%W: The week number of the current year as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01
%y: The year as a decimal number without a century (range 00 to 99)
%Y: The year as a decimal number including the century
%z: The time zone as hour offset from UTC.
%Z: The time zone or name or abbreviation

For More Information

Mailing expressions can be used to craft some very targeted messages. For more information about how to use mailing expressions, please contact Plus Three.

ARCOS 7 Help