Understanding and Using Mail Merge to Personalise Your Campaign – Mr Yum

Mail merge allows you to personalise the content of your campaign by inserting values related to the recipient. The most common mail merge is the first name. This allows you to say personally address the receiver of your email or sms campaign.

Every contact field can be used in a mail-merge and a fallback value is also supported.

Fallback values in mail merge denote text to display when the value of the specified field is empty.

For example, if you send an email containing " Hi {contact.firstName} " and you do not have the user's first name then, they will just see " Hi ".

A fallback value allows you to provide a value so that if the first name isn't available, the platform will use generic text (eg: "Hi there" or "Dear Member")

How to insert a mail merge in a campaign

When editing any text within the platform, if mail merge is supported, a button or a link will exist to allow you to select a mail-merge using a popup interface.

Mail-merge is supported in the following areas:

Email content & subject lines
SMS content
Automation notification emails & sms.
Form notification emails & sms.
Pushing webhooks to third-party systems.

Understanding Mail Merge Parsing

As well as using the "Insert A Mailmerge Tag" page, you can also type out any mail-merge you wish to use. Mail merge tags are all formatted in the same way:

{ module . field | fallback }

Any text within curly brackets { } will be interpreted as a mail-merge tag. The platform will then read and attempt to parse the text inside the curly brackets and display a value.

The modules available are based on your account package and settings. They can be one of:

contact - all data stored in your database
transaction - purchase and transaction data that has been captured from integrations (eg: from ePOS, ticketing platforms etc...)
visit - booking and reservation information captured from integrations
whitelabel - only available to white label account holders to display details of the platform settings.
offer - to display an offer barcode or value
campaign - for use in email campaigns to display personalised links (eg: unsubscribe, view online etc...)

Immediately after the module name, specify a full stop followed by the field name . Field names are dynamic based on the available fields that have been setup per that module.

If you wish to specify a fallback, you will need to add a pipe (|) character followed by your fallback text.

Here are some examples:

To display first name or "member" if no value: {contact.firstName | member}
To display the email address without a fall back value: {contact.email}
To display the date of the user's last transaction: {transaction.transactedAt}
To display the all time amount of money spent by the user: {transaction.allTimeTotal}

If a specified field does not exist within a module then, the full text will be displayed as-is. For example, if specifying a mail-merge as {contact.Age} and no such field called "Age" exists then, your campaign will display "{contact.Age}" rather than blank text.

Displaying Today's Date

A special mail merge {date.now} exists to display the current date and time. For email or sms campaigns, this will be the date & time that the campaign was sent to the recipient.

All date formatting and modifiers can be applied to the {date.now} mail merge.

Date and Time Formatting

By default, when specifying a date or time field, the platform will output the full value using the formats:

Date fields will be displayed as dd/mm/yyyy or mm/dd/yyyy based on your account locale.
Time fields will be displayed as hh:mm
Date & Time fields will be displayed as dd mmm yyyy hh:mm (month and day may be reversed based on locale).

However, in certain situations, you may wish to display only a portion of the date. In such cases, you are able to specify a full stop after the field name and then enter "day", "month" or "year" to display only that part of the date.

For example, if the Date of Birth is 20 December 1985, we can use the following mail-merge tags:

{contact.dob} will display 20/12/1985 (or 12/20/1985 based on locale)
{contact.dob.day} will display 20 .
{contact.dob.month} will display Dec.
{contact.dob.year} will display 1985.

As well as day/month/year, we also support the ability to provide very custom and specific formatting rules for date and time formatting. You can specify a string of tokens after your field name to specify the exact format of your date display. These can all be used together.

Supported Date formatting tags are:

Type	Token	Output	Type	Token	Output
Month	M	1 2 3 .... 11 12	Day of Week	dd	Su Mo Tu ... Fr Sa
Month	Mo	1st 2nd 3rd...11th 12th	Day of Week	ddd	Sun Mon Tue ... Fri Sat
Month	MM	01 02 03 .... 11 12	Day of Week	dddd	Sunday Monday....Saturday
Month	MMM	Jan Feb ... Nov Dec	Year	YY	70 71 72 ...29 30
Month	MMMM	January February...December	Year	YYYYY	1970 1971 ...2029 2030
Day of Month	D	1 2 3 .... 30 31	Day of Year	DDD	1 2 3 4 ....364 365
Day of Month	Do	1st 2nd 3rd ...30th 31st	Week of Year	w	1 2 3...52 53
Day of Month	DD	01 02 03 ... 30 31	Quarter	Qo	1st 2nd 3rd 4th

Supported Time formatting tags are:

Type	Token	Output
AM/PM	a	am pm
AM/PM	A	AM PM
Hour	H	0 1 2 3....22 23
Hour	HH	00 01 02 03 .... 22 23
Hour	h	1 2 3 ... 11 12
Hour	hh	01 02 03 .. 11 12
Hour	k	1 2 3 4 .... 23 24
Hour	kk	01 02 03 04 .... 23 24
Minute	m	1 2 3 4 ....58 59
Minute	mm	01 02 03 ... 58 59
Second	s	0 1 2 3 ...58 59
Second	ss	00 01 02 03 ... 58 59

Date and Time formats can be used together or separately.

For example: Assuming that we have a date/time contact field called "lastTransaction" with a value of June 11 2020 3.30pm.

We can use mail-merge to display it as follows:

Mail Merge specified in our campaign	What the user will see
{contact.lastTransaction}	11/06/2020 3.30pm (day & month will be reversed based on locale)
{contact.lastTransaction.day}	11
{contact.lastTransaction.month}	Jun
{contact.lastTransaction.year}	2020
{contact.lastTransaction.dddd}	Thursday
{contact.lastTransaction.MMMM}	June
{contact.lastTransaction.dddd Do MMMM}	Thursday 11th June
{contact.lastTransaction.MMM Do h:m a}	Jun 11th 3:30pm

Performing Date Calculations

Any date, date/time and {date.now} tag can have a date calculation performed at the time of send.

This can be great to use to display a value such as an expiry or renewal date that might be automatically calculated as 12 months from the join date.

There are two supported calculation operators: add (denoted as " + ") and subtract (denoted as " - "). Calculations can be performed using days, months and years.

The calculation needs to be placed immediately after the field name within the mail-merge tag. The format is " [+/-][ymd] "

Format Examples:

{date.now+1y} = add 1 year to the current date
{date.now-1y} = subtract 1 year from the current date
{date.now+1m} = add 1 month to the current date
{date.now-1m} = subtract 1 month from the current date
{date.now+1d} = add 1 day to the current date
{date.now-1d} = subtract 1 day from the current date

Let's put it all together.

Assuming we want to send out an email containing a voucher when a member has a birthday approaching. We would like this voucher to be valid from the day it was received until 14 days after the member's birthday.

Our campaign content might look something like:

   Hi {contact.firstName|there},
   We noticed that your birthday is coming up on the {contact.dob.Do} of {contact.dob.MMMM} and to help you celebrate, 
   we would like to offer you $20 off from our store.
   Simply use the code {voucher.offer20off.code} at checkout.
   This code is valid from {date.now.Do MMMM} until {contact.dob+14d. Do MMMM}

The above will render and display as:

   Hi Andy,
   We noticed that your birthday is coming up on the 10th of December and to help you celebrate, 
   we would like to offer you $20 off from our store.
   Simply use the code ABC321 at checkout.
   This code is valid from 10th December until 24th December.

Related articles