Mailing lists - University of Auckland

What is MailMerge?

MailMerge, or Personalisation, is a feature of the Sympa mailing list system that allows you to personalise messages sent to a list, so that each recipient receives a different message.

You could use this to simply insert the recipient's name into the message, or to include a clickable link to unsubscribe. You could define custom data for the list and include that. You could even perform calculations, and switch sections of the message on or off depending on other data.

How do I make a MailMerge list?

To enable MailMerge on a list, you need to be the List Owner. Then, in the List Admin pages, you can edit the list Send/Receive Configuration and set the MailMerge Feature to be 'on'. This will result in all future postings to the list being processed by the 'TT2 Template Processor' before distribution to each subscriber. It is this processor that performas the merge function.

Points to note are:

• S/MIME Signatures: You cannot use an S/MIME signature if you have MailMerge enabled. This is because S/MIME verifies that the message content has not been modified, and MailMerge modifies the content -- this results in the mail recipient seeing an invalid digital signature. To prevent this, a special posting Scenario exists that prevents S/MIME signed messages from being sent to the list. You can select this from the list configuration screen.
• HTML and Alternative Part emails: MailMerge works with HTML emails. However, you need to be aware that the TT2 commands must not contain any HTML. In particular, TT2 code that includes a '>' or '<' symbol, or an '&' symbol may be invisibly modified by your mail reader resulting in an template error.
• Template errors: An error in the template code will usually result in a completely blank email being distributed. No error message will be displayed.
• Template format: Templates must be in TT2 format. You can use a range of commands, but not embedded Perl code.
• Template variables: Certain template variables are available for use. See here for details on the variables and their usage.

There is a List Creation Template available for making Mail-Merge lists with the recommended settings.

The recommended way to use a MailMerge list is to first build a template for your mailouts in your mail client, probably including any common headers and footers, and maybe tracking informatrion (see the later section on tracking). Then, you can use this template to build your mailouts.

How do I run a test mailout?

If you are using one of the 'mailmerge' Send Scenari, then you can run a test mailout by having the string "SYMPA-TEST" (all in capitals) in the message subject line. If this is present, then then message will only be sent to yourself (make sure you are a list member, though, if you want to have any metadata merging taking place!).

Alternatively, you can create a separate mailmerge list for testing purposes that only includes yourself as a member (and possibly other test users if you wish).

Note that the Tracking module does not work on Test mailouts.

What are Custom Variables?

In the list definition, you can define additional custom variables associated with either individual subscribers, or with the list itself. For example, you could add a field 'colour' to hold the subscribers' favourite colours, and then refer to this field as user.custom_attribute.colour.value in your template.

Custom variables can have different types, and are set manually by the subscriber at subscription time or when they edit their subscription settings via the wbe interface. You can make variables mandatory if you wish, so that people cannot subscribe to the list without giving the information.

Which data are available to me in the merge?

You can dump the available 'stash' (the variables namespace) by using the UOA module. This will inject some HTML to show you the current variables and their values.

[% Use UOA %] [% UOA.stash(html=1) %]

How about tracking?

The MailMerge system allows you to track who has viewed messages, and also count the clickthrough on the embedded links. To enable this, see the documentation on the Tracking Page.

Where can I read about this?

There are several places you can read more on the use of TT2 mail templates.

• The TT2 website documentation
• The Sympa MailMerge documentation

Common Mistakes

There are a number of things that might go wrong in your merge.

• Invalid tag definitions. If you generate invalid tags, you can end up with a blank or unmerged message. ALWAYS run a test first to either a dummy list, or using the SYMPA-TEST subject tag.
• HTML tags inside TT2 tags. If you generate your email using an HTML editor (such as Outlook), then you may accidentally have HTML tags inside your TT2 control tags. This can happen if you make half your tag in bold, for example.
• Missing Metadata. Make sure you use the correct syntax to include any custom metadata from the list.
• Invalid unsubscribe URLs. It is usually best to use the Tracking.unsubscribe function rather than make the whole URL yourself, as this will display correctly in non-HTML clients.
• Formatting. If you are in an HTML editor, remember that the TT2 control tags will not display in the final message. This might alter the layout of your message when it is finally received.
• Invalid TT2 due to HTML escapes. An HTML editor will replace the '>' character with '&gt;' to escape it. Unfortunately, this will break any TT2 tests which rely on it, such as 'IF field.length > 0'. If you editor cannot be configured to suppress this behaviour, then you should modify your TT2 code to avoid using escaped characters: '>', '<', '&'.

How about an example?

Here is an example of a MailMerge message, and an example of what might actually be received by the end user. The user Sid Bloggs (sidb@foo.com) is a subscriber of the fubar@sympa.auckland.ac.nz mailing list. The mailing list defines a custom metadata field, 'colour', for which Sid has chosen 'red'.

[% IF user.gecos -%]
[% SET names = user.gecos.split(' ') -%]
[% SET firstname = names.0 -%]
[% IF firstname.length == 1 -%]
Dear Sir,
[% ELSE -%]
Dear [ % firstname %],
[% END -%]
[% ELSE -%]
Dear Sir,
[% END -%]
I know you like the colour [% user.custom_attributes.colour.value %]. Blah, blah, blah.
To unsubscribe, click here: [% wwsympa_url %]/auto_signoff/[% listname %]/[% user.escaped_email %]

The user receives this:

Dead Sid,
I know you like the colour red. Blah, blah, blah.
To unsubscribe, click here: https://sympa.auckland.ac.nz/sympa/auto_signoff/fubar/sidb%40foo.com

If the user's name were 'S Bloggs' then you'd get 'Dear Sir,', as the length of the first part of the name is only 1. Sinilarly, if there were no name defined, you would also get 'Dear Sir,'.