LISTSERV Maestro 10.1-6 Help Table Of Contents

Define Email Content

To access the define email content page for a given mail job from the open job details pane, select the Summary tab and click on the Edit link in the Email Content section. If you are already on the workflow page of the mail job, simply click on the Define Email Content section.

Define the email content of your message on this page.

Important: Any changes that you make on this page are only saved when you leave the page by clicking the [Save & Close] button. The changes are not saved if you leave the page in any other way (for example via the menu). However, the Recovery Copy feature automatically saves your current work at regular intervals. If you leave this page without saving and later re-enter it, you can restore your unsaved changes from the previous edit session by restoring them from the recovery copy.

The following general subjects apply to all mail jobs:

There are various different editor types, depending on the selected content and template type, as explained here:

Email Subject

Enter the subject line for the email into the Subject edit field at the very top of the page.

As part of the subject line, you can specify merge fields and drop-ins for a personalized subject line that is custom tailored for each recipient. But remember to only use merge fields and drop-ins that make sense in a single line, text only subject.

Template Gallery

The template gallery can be accessed via the [Select Template] button at the top left corner of the page. The gallery allows you to pick the template that the message content shall be based on.

You can either pick one of the available templates, or chose to create your message for scratch, without basing it on a template, either by starting with an empty content or by uploading a HTML file that you have created outside of LISTSERV Maestro. You can also copy the content from another mail job.

HTML Content

An email can either be a HTML email (optionally with a plain text alternative) or a simple plain text email.

To create a HTML email, you need to pick a HTML enabled template from the template gallery (see below for details).

Then you need to provide the message body in HTML format, on the HTML tab. (The tabs to switch between "HTML" and "Text" are shown as vertical side-tabs at the very left of the page.)

In the HTML content, you can use merge fields, drop-ins, and conditional content to customize the content for each recipient.

The HTML content of a mail job can be based on several different template types. The template that the content is based on can be changed by clicking on the [Select Template] button. This allows you to start over with a new template or uploaded content.

Working with the different available template types is slightly different for each:

  • Standard Template: The HTML content is based on an existing standard template. A standard template has a predefined layout and design, with predefined editable blocks. To fill out a standard template, you provide content for these editable blocks.

  • Click-and-Fill Template: The HTML content is based on an existing click-and-fill template. A click-and-fill template has a predefined layout and design, similar to a standard template. But instead of the larger editable blocks, a click-and-fill template has more fine grained editable fields with predefined semantics, akin to the blanks in a form. To fill out a click-and-fill template, you provide content for these editable fields.

  • HTML Content, WYSIWYG Editor: The HTML content is created from scratch, without any template, using the built-in visual HTML editor (WYSIWYG editor) of LISTSERV Maestro.

  • HTML Content, Source Code Editor: The HTML content is created from scratch, without any template, using the built-in HTML source code editor of LISTSERV Maestro.

  • HTML Content Created in External Editor (Uploaded): The HTML content was prepared outside of LISTSERV Maestro, for example with the help of a 3rd party HTML editor, and was then uploaded as a HTML file (possibly with associated image files) into LISTSERV Maestro.

In the main menu there is a "Download HTML" item which allows you to download the current HTML content.

Plain Text Content

An email can either be a HTML email (optionally with a plain text alternative) or a simple plain text email.

To create a plain text email, you need to select the No Template -> Plain Text Content, Text Editor choice from the template gallery. If you have a user-defined click-and-fill template that defines a simple plain text email, then you can also select this template.

Then you need to provide the message body in text format, on the Text tab.

The same Text tab is also used for the plain text alternative for a HTML email. (The tabs to switch between "HTML" and "Text" are shown as vertical side-tabs at the very left of the page.) It is possible to have a HTML email without a text alternative, but this is not recommended. It is a best practice to always include a text alternative with a HTML email.

In the plain content, you can use merge fields, drop-ins, and conditional content to customize the content for each recipient.

Mail Merging

LISTSERV Maestro supports mail-merging. Mail-merging is the processes of replacing special placeholder tags in the email body or subject with individual values that may be different for each recipient.

It is possible to use merge fields in the subject line, the HTML body, or the plain text body of your message.

A merge field always has the form "&NAME;", where "NAME" is the name of the field. Merge fields are not case sensitive.

To include a merge field, either type it directly into the desired location in the content, or put the editor cursor at this location and then click the desired merge field among the list of available fields in the Merge Fields section in the panel on the right (you may have to scroll the panel to see the section, and you may have to open the section by clicking its section header).

The available merge fields depend on the type of recipients you use and your LISTSERV setup:

  • If the recipients are based on a subscriber list or list group, then the profile field of that list/group define the available merge fields.

  • If you upload the recipients from a file, then this file may contain a number of columns, where each column has a certain header name. You can use each header name (with the surrounding "&" and ";") as a merge field in your message.

  • If the recipients are selected from a database, then the names of the selected columns (with the surrounding "&" and ";") can be used as merge fields in your message.

  • If you specify your recipients by using an existing LISTSERV list, and this list is DBMS-backed, then you may have additional columns for each recipient in your database. You can use the names of those columns as merge fields.

In all cases, you can also use the predefined merge field names from LISTSERV, like &*TO; and &*DATE;. See the LISTSERV documentation for more information.

Drop-In Content

See here for a general description of drop-in content elements.

To use drop-in content in your email message, it must be enabled in the Content Options section in the panel on the right.

When enabling drop-in content, you are also required to define an opening and a closing tag. These tags are used by LISTSERV Maestro to identify the names of the drop-in content. Opening and closing tags can be any characters you like that do not contain any spaces. "{{" and "}}" are suggested as defaults, but you may change them.

To include drop-in content in your message, simply enter the name of the drop-in at the appropriate location, enclosed in the tags you have defined. For example, if your drop-in is called "sample" and you are using the suggested default tags, then you would include the text "{{sample}}" in the location where you want the drop-in content to appear in the message.

Alternatively, put the editor cursor at this location and then click the desired drop-in among the list of available drop-ins in the Drop-Ins section in the panel on the right (you may have to scroll the panel to see the section, and you may have to open the section by clicking its section header). Or for one of the special social media sharing drop-ins, select it from the Social Media section.

Whenever LISTSERV Maestro finds the opening tag followed by the closing tag, it will interpret all the characters in between as the name of a drop-in. LISTSERV Maestro will then look up the list of available drop-ins for a drop-in with this name. If the name is not found, delivery of the email fails with an error message like "Drop-In with name 'XYZ' not found".

It is important to choose opening and closing tags with care, making sure that they do not otherwise appear in the message. For example, if you decide to use parentheses '(' and ')' for opening and closing tags, any text that appears between any set of parentheses will be interpreted as the name of a drop-in. Since parentheses have a high probability for use in the normal text of a message, using them as tags is not recommended because they may cause an error in drop-in name look up, leading to email delivery failure.

If drop-in content is disabled, any drop-in placeholder names that might appear in the message will not be replaced with the corresponding content. Instead, the placeholder names will appear verbatim in the body of the message.

Forward To Friend

If the mail job recipients are based on a subscriber list in the subscriber warehouse, then you have the option to use the Forward to a Friend feature. To do so, include the {{*ForwardToFriendURL}} system drop-in in your content (see above for more details about drop-ins).

With this feature, a special "Forward this email to a friend" link is embedded into the actual message. When a recipient clicks on this link, a special page opens that is used to enter the email addresses of any friends that the recipients wants to forward the message to. Optionally, a personal message may also be entered and will be included in the forwarded emails. Once the recipient triggers the forwarding, a copy of the same email that the recipient initially received will be delivered to the supplied friend-addresses.

The forwarded email contains the same "Forward this email to a friend" link that was in the original mail, giving the friend-recipient the opportunity to forward this message to more friends.

The system keeps a record of all forwards, with a detail level that corresponds to the selected tracking level, so that you can later view reports on how many forwards were triggered and how many conversions occurred, i.e. how many of the forward recipients subsequently subscribed to the list themselves.

Note: While the friends generally receive a message with the same content as the original message (plus the special preamble), there is a possibility that the original message and the forwarded message may differ slightly. If the original message used merge fields in profile field values of the original recipient, then these fields will be freshly merged during each forwarding. This means that if the original recipient's profile fields have changed since the original mailing, then the forwarded message will contain different merge field values than the original message. Also, the forwarding will only work while the original subscriber list still exists and the original recipient is still a subscriber of that list.

Conditional Content

Besides merge fields and drop-ins, conditional content is another powerful tool to customize the message differently for each recipient.

Conditional content is available in two flavors: Widget conditions and conditional blocks. Both flavors allow you to specify a condition in form of a calculation formula. The boolean result of the formula defines if the condition is true or false.

(If the formula does not result in a boolean value, then the result is converted to a boolean using the same rules as for the ToBool formula function, see here, with the exception that formulas that result in a Text Set or Number Set are not allowed at all).

  • Widget conditions are available for fluid design widgets when editing the HTML content of a mail job.

    With a widget condition, you can control if a certain widget (for example a content box or an image) is supposed to appear in the message or not. Which is most useful if the condition is based on one or more merge fields, so that some recipients will see the widget, while others will not, depending on their merge field values.

    To specify a widget condition in design mode, open the widget's properties dialog. Then go to the Condition tab and enter the condition formula.
    In code mode, specify the widget condition as part of the widget's custom tag. When doing so, keep in mind the issues explained below.

    Widget conditions are the recommended method of specifying conditional content in a HTML message. While conditional blocks are also available for HTML messages (see below), they are more complicated to use in a HTML context, as they need to be specified in code mode, disrupt the preview in design mode, and also do not work well together with social media sharing.

  • Conditional blocks are available both in HTML content and in plain text content.

    A conditional block is a section of content that is enclosed in an opening and closing block marker, where the opening marker specifies a condition. With this condition, you can control if the content inside of the block is supposed to appear in the message or not. Again, this is most useful if the condition is based on one or more merge fields.

    To specify a conditional block, you simply type the block markers with the condition into the message content, surrounding the desired content section with the markers (for HTML message you must do so in code mode, in the actual HTML code, you cannot specify a conditional block while in design mode).

    A conditional block is coded by using the .BB (begin block), the .EB (end block), and the .ELSE directives. Comments can be added without appearing in the final message by placing a .* before the text containing the comment. The directives are not case sensitive.

    Important: Each directive must be on a line by itself, starting as the first character of the line.

    The condition in the .BB (begin block) directive should normally be specified in form of a *Calc system drop-in with a formula. The condition is then fulfilled (=true) if the formula evaluates to the boolean value "true".

    With such a *Calc formula condition, the syntax for a basic conditional block looks like this:

    .BB {{*Calc FORMULA}}
Text to be included if FORMULA evaluates to "true"
.EB

    The .ELSE directive is used to specify content that is to be included in case that the condition is false (the example below also illustrates the usage of .* comments):

    .BB {{*Calc FORMULA}}
.* This is included if FORMULA evaluates to "true"
Content for case "true" here
.ELSE
.* This is included if FORMULA evaluates to "false"
Content for case "false" here
.EB

    (Note: It is possible to specify a raw LISTSERV condition, using LISTSERV's own condition syntax, instead of the *Calc system drop-in. This however has the drawback, that conditional blocks that use such raw LISTSERV conditions cannot be combined with the View in Browser or Social Media system drop-ins in the same message content.)

Attention: If you set a widget condition on an Image/Video Box widget or an Image/Video and Content Box widget, or if you use a .BB conditional block to surround such a widget or a generic HTML image, and you combine this with the "Images are sent as attachments" content option (i.e. inline images), then all of these image attachments will always be included for all recipients.

This means that it is possible (and even likely) that some recipients will receive image attachments that are actually not used by their message content, i.e. the corresponding image is not displayed in the message because its content condition evaluated to false for the recipients. The attachment is however still included, which causes the email to be larger than necessary and in some email clients may have the effect that the otherwise unused image attachment is then shown as a normal attachment.

It is therefore strongly recommended to use the "Images are sent as URLs" option (i.e. linked images) when using conditional content. See here for more information.

Attention: Do not use the conditional content feature to include confidential information in your message that is supposed to be disclosed only to some of the recipients, but that should not be seen by other recipients.

The actual delivered emails will indeed only contain those content sections where the condition was true (except maybe for images, see warning above), and will not contain the sections where the condition was false. So, at first glance it might seem OK to use conditions to hide confidential information from some recipients. However, there are two caveats with this:

First of all, it is too easy to accidentally disclose information because a condition was (slightly) incorrect, thus evaluating to "true" in unexpected cases and accidentally including the confidential information in the email to a recipient that should not have received it.

Second, if you also use the *ViewInBrowser system drop-in, or any of the social sharing or publishing features, then it is trivial for the end user to manipulate the URL of that browser version of the email to also see the parts of the message that were not originally intended for him.

It is therefore strongly recommended to only include information in the message that would not be harmful if exposed in its entirety to all recipients, even when using conditional content.

A Word About Widget Conditions in Code Mode

In code mode, a widget condition is represented in form of the condition attribute of the corresponding <widget-XYZ> custom tag, with the condition formula as its value. For example:

<widget-contentBox condition="FORMULA HERE">

As such, the formula would normally have to adhere to the usual HTML attribute escaping rules. Here are some problematic examples:

  • Formulas containing double quotes need to be enclosed in apostrophe or the double quotes in the formula must be escaped:

    <widget-contentBox condition='&FIELD; = "sample"'>
    <widget-contentBox condition="&FIELD; = &quot;sample&quot;">

  • Formulas with merge fields that happen to be the same as a HTML entity name must escape the "&" of the merge field as "&amp;". For example the merge field name &COPY; is also a HTML entity that stands for the character ©, so it must be escaped:

    <widget-contentBox condition="&amp;COPY; = 10">

As you can see, these escaping rules make the formula rather difficult to read (and also difficult to write correctly in the first place).

So, to avoid these problems, the code mode editor shows the condition with a special formula placeholder that is not edited directly in the editor itself, but that you can click on, to then edit the condition in a popup dialog. In this dialog, you do not have to think about HTML escaping. You can simply specify the formula in its normal form and LISTSERV Maestro does all the necessary escaping for you. This formula placeholder looks like this:

<widget-contentBox condition="FORMULA HERE">

Only when specifying a condition attribute for the very first time (in code mode) do you have to type it as a normal attribute (adhering to the necessary escaping rules). But if you then save the content and re-enter the editor, or simply switch to design mode and back to code mode, then LISTSERV Maestro replaces the manually entered formula with the more convenient formula placeholder.

So, if you are unsure about the correct encoding, but need to specify a condition attribute in code mode for the first time, you can simply specify it as something like condition="todo" and then save the content and re-enter the editor (or switch to design mode and back to code mode) and then proceed to enter the actual formula by clicking on the formula placeholder that LISTSERV Maestro now shows.

© 2002-2022 L-Soft Sweden AB. All rights reserved.