Editing Mail Templates

The mail template editor allows site administrators and list owners to customize administrative messages sent out by LISTSERV. When you first enter the template editor, the most frequently updated mail templates are listed alphabetically in a table. You can click on the column headers to change your sorting preferences. The case-insensitive filter row allows you to filter the templates that are displayed in the table. For example, if you want to see unsubscribe-related templates, type SIGNOFF in the filter box. To open a template for editing, simply click on its name. A new screen will open with a large text area, allowing you to make the desired changes to the template. Click "Update" to save the template. If you make a mistake, click "Revert" to restore the default version of the template.

Mail templates fall into three different types:

• Mail Templates: These templates control the content of email messages sent by LISTSERV. A mail template is a complete email message. Formatting commands are available, and substitutions that make sense in the context of the specific message are available.
• Message Templates: These templates supply text that will ultimately be shown to the user. These messages may be included in a mail template, or they may be returned to the web interface in response to commands. Limited formatting is available.
• Message Fragments: These templates are the lowest level of mail templates. Fragments are pieces of text produced by LISTSERV as parts of other messages or emails. Formatting commands are generally not available in fragments.

Template Categories

This pulldown menu allows you to narrow the templates shown in the table. For example, if you only want to see the most frequently modified templates or digest and index-related templates, choose the relevant option from the menu and click "Select". Use the Only Display Modified Templates option to narrow the list down to templates that have already been edited.

Search Templates

This field allows you to search the content of the mail templates. Simply type the desired query in the text box and click "Search".

Create New Template

To create a new web template, click on "Create New Template", enter the template name and a short description and click "Create". Note that the template name cannot contain spaces or special characters.

Template Style

LISTSERV can send out mail templates either in plain text or as HTML messages. Use the pulldown menu to select the template style of your choice and click "Select". To create new HTML template styles, go to the Newsletter Templates section. Whenever you create a new HTML newsletter template, the system also generates a simplified HTML mail template equivalent.

All frequently used mail templates support HTML. When you change the mail template style, the following mail templates are affected:

• WELCOME
• FAREWELL
• ADD1
• ADD2
• ADDMOD2
• ADDREQ1
• AUTODEL1
• AUTODEL2
• CHANGE1
• CONFIRM1
• CONFIRM2
• DELETE1
• INFO
• PROBE1
• PROBE2
• RENEW1
• RENEW2
• REQACK1
• SETINFO
• SIGNOFF1
• SIGNOFF2
• SIGNUP1

Note: As of LISTSERV 16.0, the old *WELCOME* and *FAREWELL* templates are obsolete. You can continue using any existing *WELCOME* and *FAREWELL* templates, but if you want to take advantage of the new HTML mail template styles, you should copy the existing content to the new WELCOME and FAREWELL templates.

If you have existing customized templates and would like to add HTML support to them, simply click "Enable HTML Template Styles" and LISTSERV will automatically insert the required code to the relevant templates.

Mail Template Commands and Conditions

The mail templates are not pure HTML code. They consist of HTML code interspersed with template commands and conditions. Commands and conditions in mail templates always begin with a . in the first character position of a line. Each command must be on a line by itself. The following list contains some examples of common commands and conditions:

Global Variables

List Variables

Content Filter

The CONTENT_FILTER mail template, if present, contains filtering rules, one rule per line. Each rule has the following format:

The prefix, if present, can be a mail header tag (for example "Subject:"); "Header:" to check the whole header; or "Text:" to search the message text. The latter is the default if no prefix is supplied. A text search will search every line of the first text/plain part in the message. If there is no text/plain part, there is no match.

Regular comparisons such as those described above are not case sensitive. Patterns are standard LISTSERV patterns. The asterisk is the wildcard character. If there is no asterisk in the pattern, it is replaced with "*pattern*".

The content filter also supports "exact match" comparisons, which are triggered by a double colon. For instance:

There are two significant differences between exact and regular match:

• You must supply your own wildcard characters in an exact match (if you want to use wildcards). A regular match will insert leading and trailing wildcards if none are found. Thus, an exact match is the only way to make a comparison without wildcards.
• You can make an exact match for the empty string. Empty regular matches are ignored. This also makes it possible to apply an exact match to a message that does not contain a specified header.

One of the most handy uses for the exact match syntax is to be able to write a rule to reject messages with blank subject lines. For instance:

Every rule can, optionally, be followed by an action rule. This has the following format:

The available actions are the same for both regular and exact comparisons. For instance:

The default is "Action: REJECT" with no specified reason.

• REJECT means that the message is rejected. The text of the rejection is fetched from the BAD_CONTENT mail template form, with the reason supplied as a variable called &COMMENT.
• MODERATE means that the message is to be forwarded to the list editor to be manually approved or rejected.
• DISCARD means that the message is to be discarded without further processing; any text following DISCARD is echoed to the LISTSERV log file.
• ALLOW means that the message is allowed and all remaining rules are ignored. This could be used in moderated lists to allow certain posters to bypass certain filters, for instance:

In the example above, messages with subject lines containing "Out of office" are rejected. Messages containing the text "Click here to be removed" are also rejected unless it came from joe@example.com.

Note: The CONTENT_FILTER is a data template. None of the usual mail template substitutions or commands are valid.

Using &DAYSEQ()

The DAYSEQ(n) function is quite powerful. This function allows the list owner to code templates like bottom banners that change or "rotate" automatically.

The DAYSEQ(n) function is invoked in a .BB .EB conditional block, and n corresponds to the number of days in the rotation period, in other words, the number of variations that you want to make to the text of the message. &DAYSEQ(n) returns a number from 1 to n which increases by 1 every day, with no special regard for weekends. If the rotation period should last for a week, you code DAYSEQ(7). If the rotation period is 15 days, you code DAYSEQ(15).

To create a rotating bottom banner, follow this example. A list has three commercial sponsors, each of whom are provided with an advertisement every three days. (Note that this doesn't take weekends into account; in this example, if company A is featured in the banner on Monday, it will be featured again on Thursday and then again on Sunday. However, in the following week it will be featured on Wednesday, Saturday and Tuesday). Our BOTTOM_BANNER template would look like this:

If a company needs to get a higher percentage of "air time" than another, you can simply assign it more than one of the possible n values of &DAYSEQ(n). For instance, if you have two companies but one should get twice as many days of air time, you might code something like this:

This would cause Company A's message to appear on days 1 and 3 of the rotation period and Company B's message to appear on day 2 only.