LISTSERV Maestro 11.0-20 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, either open the workflow page of the job and then click on the Define Email Content section or select the Summary tab and click on the icon associated with the 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 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 Content tab. It is a best practice to also supply a plain text alternative with the HTML content, which is shown on a separate "Alt Text" tab which contains a plain text content, as explained in the next section. (The tabs to switch between "HTML Content", "Alt Text" and "Landing Pages" 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.

    A standard template can either be a predefined system template are a user-defined template. See here for more details on the respective HTML editor for each type: Standard system template or standard user-defined template.

  • 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.

    A click-and-fill template can either be a predefined system template are a user-defined template. See here for more details on the respective HTML editor for each type: Click-and-fill system template or click-and-fill user-defined template.

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

    See here for more details on the HTML content WYSIWYG editor.

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

    See here for more details on the HTML content source code editor.

  • HTML Content Created in External Editor (Uploaded): The HTML content was prepared outside of 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 Maestro.

    After the upload, the content can then be further edited, if desired, using the HTML content source code editor (see above).

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 Content tab. (The tabs to switch between "Text Content" and "Landing Pages" are shown as vertical side-tabs at the very left of the page.)

The plain text alternative for a HTML email uses a similar tab, called Alt Text.

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

See here for more details on the respective plain text editor for each type: Plain text content or alternative text for HTML content.

Landing Pages

In addition to the content itself, that is sent to the recipient in form of an email, you can also create one or more landing pages with additional content, that the email links to.

A landing page is used to add content to the message that is not supposed to be part of the original email, but that is nonetheless strongly associated with the message and shall therefore be available to the email's recipients, through links in the email. Where such features as mail merging and conditional content (to customize the content for each individual recipient), drop-ins, link tracking etc. are also available when crafting the landing page.

A landing page can either be a normal web page or a downloadable PDF file. Both types are automatically hosted by the Maestro server, without the need to manually configure or administrate it on a separate web server, so that your recipients can easily access the web page or PDF file online (and without having to log in or similar).

The landing pages (both web pages and PDF files) that are associated with a message exist as long as the corresponding mail job exists. Once the mail job is deleted (or archived), its landing page cease to work, i.e. the links to the landing pages will result in a "404 - Page not found" error message.

The landing pages are edited on the Landing Pages tab. (The tabs to switch between the mail content and "Landing Pages" are shown as vertical side-tabs at the very left of the page.)

On the landing pages, you can use merge fields, drop-ins, and conditional content to customize the page for each recipient.

See here for more details on the landing page editor and on the HTML support for PDF landing pages.

Examples:

A newsletter email could contain an article about a certain topic that is so long, that you do not want to include the whole article in the email itself. Instead, you could create the article on a separate landing page (complete with illustrations and of course a nice design) and only put the article header and a teaser image and a first teaser paragraph in the email itself, followed by a "Read More" link that links to the landing page with the full article.

Or you could want to send out an email promoting a certain service, where multiple options exist that require a thorough explanation. Instead of putting the full service explanation with all its options into the email itself, you could write them out in detail on a landing page, with tracked "Buy Now" links for each service option, and just add a "More Details" link to your service offer in the email.

Or imagine that you want to send out a promo coupon to your subscribers that is supposed to be a downloadable PDF file, but individually tailored with each recipient's name and customer number. This is not possible with a normal PDF file attachment, as the attachment would be the same for all recipients. But you can create a landing page in PDF file format and use merge fields for the recipient's name and customer number in that PDF.

Tracked Links in HTML or Plain Text

Links in mail content can appear in various forms and on various locations:

  • HTML or plain text link directly in the message
  • HTML link or plain text link in the content supplied via a drop-in
  • HTML link on a landing page, in HTML or PDF format

If an HTML link is coded in the usual way, then it is automatically recognized as tracked link:

<a href="https://www.example.com/someURL">This link is tracked</a>

If you want an HTML link to be exempt from tracking (i.e. you don't want Maestro to replace the link with its associated tracking URL), then you code the link as follows:

<a data-lsoft-do-not-track="true" href="https://www.example.com/someURL">This link is not tracked</a>

Note: Using the data-lsoft-do-not-track attribute in the link code tells Maestro to ignore this link when finding tracked links in the message source code.

Note: The description above also applies to area tags, which can also be augmented with the data-lsoft-do-not-track attribute to declare the link as not tracked.

If you add or edit a link with the Maestro WYSIWYG HTML content editor, then you can check or uncheck the option "Track This Link" in the link's settings editor (available via right-clicking or double-clicking the link on the "Design" tab of the editor). Both methods, via the WYSIWYG editor and directly in the source code, have the same effect: The data-lsoft-do-not-track attribute is included in the source code of the link, which Maestro later recognizes during delivery and includes or ignores the link when defining tracked links in HTML.

If you write a plain text link in quotes, then Maestro recognizes this link as tracked:

Plain text link, tracked: "https://www.example.com/someURL"

Contrary to this, if you write a plain text link without quotes, then Maestro does not track this link:

Plain text link, not tracked: https://www.example.com/someURL

By seeing quotes surrounding a URL in the plain text, Maestro knows whether this URL is supposed to be a tracked link or not when looking for tracked in links in plain text.

Note: This method of declaring tracked or non-tracked links via appropriate decoration in the HTML or plain text message source has the huge advantage that you can decide about a link being tracked or not directly at the place where the link was originally defined, be it the message itself, a landing page, a content template, uploaded HTML or the value of a user drop-in that may even be provided by an external source.

Tracking Aliases: When defining the replacement URL for a tracked link, Maestro not only considers the original URL itself but also the URL Alias. This way, the same URL (i.e. appearing on several locations in the message) can trigger separate sets of tracking events and can thus be reported over separately. By default, Maestro assigns aliases to each URL according to the following logic:

  • If a link occurs in the message itself (regardless of whether the message was defined via a content template or not), then Maestro assigns a unique alias html[NUM] or text[NUM], depending on whether the link appears in HTML or plain text. ([NUM] is replaced with a number that is unique within the message, not necessarily indicating the visual order since this is based on scanning the source code.)
  • If a link occurs in a landing page, then Maestro assigns the same alias to all links that are on this landing page.
  • If a link occurs in the content of a drop-in, then Maestro assigns the same alias to all links that are in the content of this drop-in.

If you want to have a custom alias assigned to a link (in plain text or HTML), then you can do so by suffixing the link URL like so:

https://www.example.com/someURL|myCustomAlias

Mail Merging

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

It is possible to use merge fields in the subject line, the HTML body, the plain text body or any landing page 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.

Drop-Ins are marked by enclosing them in special opening and closing tags. These tags are defined in the "Drop-In Tags" subsection of the "Content Options" section in the panel on the right. 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 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. Maestro will then look up the list of available drop-ins for a drop-in with this name. If the name is not found while processing the email content itself, delivery of the email fails with an error message like "Drop-In with name 'XYZ' not found". If the name is not found while processing a landing page for display or download, the drop-in is simply not replaced, without generating an error.

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.

Unsubscribes and the {{*UnsubscribeURL}} System Drop-In

Almost all legal jurisdictions require that commercial email messages include clear and concise instructions about how to unsubscribe from receiving these messages from the sender.

The best method to comply with such regulations is to include the {{*UnsubscribeURL}} system drop-in in each of your messages. This drop-in is closely integrated with the Unsubscribe Action Links that are configured for your account or group. To select the unsubscribe action link that is appropriate for your message, open the Unsubscribe Action section in the panel on the right of the screen and click the [Change] link. In the dialog that opens, select the desired link.

By default, Maestro requires that you use {{*UnsubscribeURL}} in all messages that are sent with your account or group.

In some cases, however, the message that you are sending does not qualify as commercial in the sense of the law. The decision whether your message is commercial or not is not easy to make (and Maestro can not detect this automatically for you), but you may for example be sending the message to an internal employee notifications list and the membership for this list is maintained by your HR department, and therefore a fully functional unsubscribe link would be undesirable.

In cases like this, you have the following options:

  • Follow the requirement imposed by {{*UnsubscribeURL}} being mandatory and include it in your message. Then, configure an unsubscribe action link that forwards subscribers (in this example: your employees) to an on-premises page that explains why unsubscribing is not possible. This method (of explicitly telling your employees why unsubscribing is not possible) is recommended.

  • If you do not want to see any traces of an unsubscribe link in your message even with {{*UnsubscribeURL}} being mandatory, you can use HTML layout to hide the link visually (which is of course not possible in your plain alternative text).

  • Contact your Maestro administrator and discuss if {{*UnsubscribeURL}} can be made optional for your account or group. With this configuration change in place, you can send messages that do not include {{*UnsubscribeURL}} but you are exposed to the risk of not complying with legal requirements, so you should consider this option carefully.

With {{*UnsubscribeURL}} in your message, the unsubscribe action link selected as described above defines the URL replacement for the drop-in. Two types of unsubscribe action are available:

  • Standard Subscriber List Unsubscribe: If you are sending your message to a Subscriber List in the Maestro Subscriber Warehouse, the unsubscribe action link is pre-selected to forward the user to the standard Subscriber List unsubscribe action, which (after confirmation) removes the subscriber from the Maestro Subscriber List and counts this under the Unsubscribe Rate metric.

  • Custom Unsubscribe Action: If you are sending your message to recipients imported from an external source (i.e. by uploading a file or selecting from a database), then the Standard Subscriber List Unsubscribe action is not available and you first must configure at least one Custom Unsubscribe Action Link. Then you can select such a pre-configured link during the definition of your message.

Note: Even if you send your message to a Subscriber List, you may still want to select a custom unsubscribe action link. This can be useful if your Subscriber List is populated from an external system via an importer and you want unsubscribes to physically occur through an Unsubscribe Page that your on-premises CRM offers (many commercial CRM systems have such a page). In this case, however, be aware of the fact that these unsubscribes are not counted by Maestro and that therefore the Unsubscribe Rate metric is not available in reports on your mail job.

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 or the landing pages 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 and are the only supported method for landing pages. While conditional blocks (see below) are also supported in HTML messages (but not landing pages), they are more complicated to use in a HTML context, as they need to be specified in code mode and can disrupt the preview in design mode.

  • Conditional blocks are available both in HTML content and in plain text content, but are not supported on landing pages.

    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 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 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 Maestro now shows.

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