LISTSERV at Work

LISTSERV Tech Tip

Q: How can I add a custom bottom banner to all of the messages posted to a list?

For a long time LISTSERV has had the capability to automatically add special text at the bottom of messages posted to a list. This is typically used for unsubscribe instructions but can be any text that you want to include. On some commercial lists, the bottom text (or the top text) can even be an advertisement. This special added text is called a "banner" and is configured in the aptly named BOTTOM_BANNER mail template.

List-Level Banners

Typically, the BOTTOM_BANNER is configured at the list-level by choosing List Management > Customization > Mail Templates in the main navigation bar.

Then use the pull-down menu and select Top and Bottom Banners to find the banner templates.

Finally, use the pull-down menu to select the BOTTOM_BANNER mail template and click Edit Template.

This allows you to customize the banner text for the selected list only. No other lists are affected. The template text will be stored in the listname.MAILTPL file on the server. If you want to use the same banner text for another list, you would need to copy the banner text, then select a new list and repeat this process. Note that when using the pull-down menu to select the BOTTOM_BANNER template, you may also see a DEFAULT_BOTTOM_BANNER template. Please ignore this as it has no applicability at the list-level.

Site-Level Banners

If you have many lists on your server, the above process will be tedious to repeat for all lists. And if you later need to make a change to the BOTTOM_BANNER template, you would need to repeat this edit for as many lists as you have. However, it is also possible to define a BOTTOM_BANNER template at the site-level, which will automatically apply to all existing and future lists on the server. To define a site-wide bottom banner, choose Server Administration > Customization > Mail Templates in the main navigation bar.

Then use the pull-down menu to select Top and Bottom Banners. Finally, use the next pull-down menu to select the BOTTOM_BANNER template and click Edit Template. This will save the banner text in the site-wide SITE.MAILTPL file on the server where it will be used for all current and future lists, unless a list has a higher priority template to apply (defined in the listname.MAILTPL file). Again, you may see a DEFAULT_BOTTOM_BANNER template in the pull-down menu, but please ignore this for now. It will be explained later.

LISTSERV applies templates in the following priority order. The highest priority are templates stored in listname.MAILTPL, followed by language.MAILTPL (optional), then SITE.MAILTPL, and finally DEFAULT.MAILTPL. No BOTTOM_BANNER template is defined in DEFAULT.MAILTPL, so the default behavior is to add no bottom text to messages.

Default Banners

With the introduction of LISTSERV 16.0, there were a number of significant changes to default settings for list message behavior. For one thing, mail-merge was turned on by default for all lists. Also, for the first time, two new templates were added to DEFAULT.MAILTPL. These new templates are DEFAULT_BOTTOM_BANNER and DEFAULT_BOTTOM_BANNER_HTML. Most people assume, from their names, that these templates function as the actual default text for the BOTTOM_BANNER template for all lists. But, in fact, that is not how these templates are used.

Instead, another new feature in LISTSERV 16.0 is that when you create a new list using the LISTSERV web interface, at the moment of list creation, LISTSERV also creates a new listname.MAILTPL file for that list containing a BOTTOM_BANNER template and a BOTTOM_BANNER_HTML template borrowing the appropriate text from the DEFAULT_BOTTOM_BANNER and DEFAULT_BOTTOM_BANNER_HTML templates in DEFAULT.MAILTPL. Thus, while these DEFAULT_* templates are used as a model for the templates written to the listname.MAILTPL file for the new list, these DEFAULT_* templates do not themselves appear at the bottom of any messages. So editing them at the list-level will have no visible effect whatsoever. You may edit these special DEFAULT_* templates at the site-level if you want to change the supplied default text.

LISTSERV announces that it has created these new list-specific BOTTOM_BANNER templates with an on-screen message following the creation of a new list.

You may be asking yourself, why does LISTSERV go to all of this trouble? Well, the answer lies in the text of the new template:

>>> DEFAULT_BOTTOM_BANNER Default bottom banner
##################################################################
To unsubscribe from the &LISTNAME list, click the following link:
.BB (&LITEFE = 0) and (&KWD(MAIL-MERGE,1) = YES)
&*TICKET_URL(&LISTNAME_ENCODED,SIGNOFF);
.ELSE
&WA_URL;?SUBED1=&LISTNAME_ENCODED&A=1
.EB

The key line is a feature that has been dormant for several previous versions:

&*TICKET_URL(&LISTNAME_ENCODED,SIGNOFF);

This TICKET command instructs LISTSERV to generate a safe, pre-authenticated URL, unique to each recipient that, when clicked, executes a true one-click unsubscribe, subscribe or SET action.

To unsubscribe from the EXAMPLE list, click the following link:
http://listserv.example.com/scripts/wa.exe?
TICKET=NzM1NTgxIGJwYXJrZXJAQkVTVEVGRk9SVC5DT00gTkpBUE0tR0VORVJBTNgdeiGDS9Zi&c=SIGNOFF

It was not until mail-merge was turned on by default in version 16.0 that LISTSERV was able to generate such unique tickets for ordinary list messages. The new DEFAULT_BOTTOM_BANNER text also uses conditional blocks to ensure that even if mail-merge is not enabled, a valid URL will be produced.

http://listserv.example.com/scripts/wa.exe?SUBED1=EXAMPLE&A=1

However, this URL will take the user to a page where they must enter their own email address in the unsubscribe form, and also causes a separate confirmation email to be sent, which must be confirmed before the unsubscribe action is complete. While eventually effective, this is by no means a one-click operation like the TICKET method.

Modifying the Default Banners

Depending on your needs, this automatic BOTTOM_BANNER template creation can also pose a challenge. Since the template is automatically created in the listname.MAILTPL file for new lists, it also has the highest priority. If you have many lists, or create lists often, then you will have a large number of listname.MAILTPL files that you may need to modify if you want to make changes to the banner later. And because they are already at the highest priority, you cannot override them by simply editing the SITE.MAILTPL file at the site-wide level.

So if you wish to modify the supplied default banner text, you should edit the DEFAULT_* templates in the SITE.MAILTPL file as soon as possible before you create very many lists so that you have fewer lists to manually change later.

Disabling Automatic Banner Creation

If you wish to disable this automatic listname.MAILTPL file creation altogether, you need to do more.

This must be done at the site-wide level. Select Server Administration > Customization > Web Templates in the main navigation bar, then use the Search Templates box at the right side to search for the template named HDREDIT-MAIN.

Look for this section near the top of the template.

Edit the template and remove the four lines highlighted above and replace them with three lines as shown below. Note that you cannot simply comment out the commands &+COPYBOTTOMBANNER*, you must remove them entirely.

+* Set content templates
+SE HELP-TEMPLATE HELP-HDREDIT
+SE BODY-GLOBAL-LISTSELECTOR BODY-HDREDIT-LISTSELECTOR
+SE BODY-MESSAGE BODY-GLOBAL-MESSAGE
+SE BODY-OPTIONS BODY-HDREDIT-OPTIONS
+SE BODY-CONTENTS BODY-HDREDIT
+BB &+CREATE-SUCCESS;
+SE TITLEICON &+LISTCRICON;
+SE ADMN_GROUP 1
+* removed auto-copy of bottom_banner
+* banners were not copied so set to 0
+SE BOTTOMBANNERSCOPIED 0
+BB &+BOTTOMBANNERSCOPIED;
+SE MSG &+T-NEWLIST_SUCCESSBANNER;
+ELSE
+SE MSG &+T-NEWLIST_SUCCESS;
+EB
...

Save the template (it will be saved in the SITE.WWWTPL file). After you have done this, the listname.MAILTPL file will no longer be automatically generated when creating new lists. This allows you to control your bottom text in one place by editing the SITE.MAILTPL file at the site-wide level. Note that if you do this, the DEFAULT_* templates will no longer have any use at either the list- or site-level.

Although we have talked only about the plain-text BOTTOM_BANNER template up to now, for the sake of simplicity, there is also a companion BOTTOM_BANNER_HTML template with the banner text in HTML format so that this can be safely added to the bottom of an HTML-formatted message while maintaining the integrity of the full HTML message. Similarly, there is also a DEFAULT_BOTTOM_BANNER_HTML template, which is meant to serve as the model to be copied into the listname.MAILTPL file when a new list is created.

We hope that this helps clear up some confusion about which templates you should modify to accomplish any changes that you might wish to make for your own LISTSERV site.


Subscribe to LISTSERV at Work.

© L-Soft 2014. All Rights Reserved.