LISTSERV Maestro 9.0-10 Help

Table Of Contents

System Drop-Ins

A system drop-in acts very similarly to a normal user-defined drop-in in that the system drop-in place holder is replaced with specific content within the email body just before the message is sent. The difference is that its name and content are not defined by the user. The name of the drop-in is pre-defined, and the content is determined by the system at delivery time, based on the logic within the drop-in.

System drop-in names all start with an asterisk *. They need to be enclosed in the drop-in opening and closing tags just like normal drop-ins. Drop-in usage also needs to be enabled for the email content, otherwise the system drop-ins are ignored and will not be replaced. This is the same behavior as normal drop-ins, if drop-ins were not enabled.

For readability purposes, you may write system drop-ins to extend over several lines. Any line breaks and additional whitespace (at locations without syntactical impact) are ignored, as long as the drop-in correctly starts and ends with the drop-in opening and closing tags.

The following sub-sections deal with the currently available system drop-ins:


System Drop-In: "From:" Address

This system drop-in is always available.

The drop-in name is:

*FromAddress

This name is case-sensitive and requires this exact spelling as well as the correct drop-in enclosing tags (for example {{*FromAddress}}).

It is replaced with the value that was entered into the Supply Sender Information: Email Address field on the Define Sender page of the mail job and can thus be used to merge into the email content the same address that will appear in the "From:" header of the email.


System Drop-In: "Reply-To:" Address

This system drop-in is always available.

The drop-in name is:

*ReplyToAddress

This name is case-sensitive and requires this exact spelling as well as the correct drop-in enclosing tags (for example {{*ReplyToAddress}}).

It is replaced with the value that was entered into the optional Supply Sender Information: Reply-To Address field on the Define Sender page of the mail job. If no value was supplied for this field, then the system drop-in will instead be replaced with the value of the Email Address field from the same page. So this system drop-in can be used to merge into the email content the same address that will appear in the "Reply-To:" header of the email (if any), defaulting to the address of the "From:" header if no "Reply-To:" address was supplied.


System Drop-In: View in Browser URL

The drop-in name is:

*ViewInBrowserURL

This name is case-sensitive and requires this exact spelling as well as the correct drop-in enclosing tags (for example {{*ViewInBrowserURL}}).

It is replaced with a http:// URL that points to a special page which displays the HTML part of the message, so that a recipient who for some reason can not view the HTML message in his email client, can view it in a separate browser window instead.

In a HTML message which also contains a text alternative part, you can use this system drop-in both in the HTML part and in the text alternative: By including the system drop-in also in the text alternative, you will give those recipients which normally only view the text alternative, the option of using the URL to display the full HTML message in a separate browser window.

The special page will display the HTML message with the same personalized merge values of the recipient as the original email. These merge values are coded into the URL. Therefore, in a mailing with a very large number of merge values (per recipient) and/or values with a very long text, this mechanism of coding the merge values into the URL may not work correctly. Consequently, you should limit the usage of this system drop-in to mailings with a normal number of merge fields, where also the individual merge values are of a normal length.

The URL will have roughly the following format (with different individual values, depending on your LISTSERV Maestro installation and the mail job in question):

http://YOUR.SERVER/list/elex3jha/080102A/84c4b3.vib?...

Note: This system drop-in can not be used together with LISTSERV's conditional blocks (of the style .BB ... .EB), and also not together with the special LISTSERV merge placeholders that begin with an "*", of the type &*XYZ;. Except for &*TO;, &*URLENCODE(...); and &*INDEX;, which are allowed together with this system drop-in.


System Drop-In: Social Media Sharing Links

The drop-in name is:

*SocialMedia

This name is case-sensitive and requires this exact spelling as well as the correct drop-in enclosing tags (for example {{*SocialMedia}}).

It is replaced with a list of links to various social media applications that allow the recipient to share the email content via these applications. The list of links will consist of text links, with the applications names, or icon links, if icons are configured. The exact composition of the list depends on which social media applications are enabled on the Social Media Settings page at the moment of delivery, and in which order, and if icons are defined at that moment or not.

If the "Forward-to-a-Friend" feature is enabled for the mail job, then the list of social media application icons will also include an icon for "forward via email". So if the *SocialMedia system drop-in is already included, then it is not necessary to also include the *ForwardToFriendURL system drop-in, for the "Forward-to-a-Friend" feature to work properly (see below).

Note: This system drop-in cannot be used together with LISTSERV's conditional blocks (of the style .BB ... .EB), and also not together with the special LISTSERV merge placeholders that begin with an "*", of the type &*XYZ;. Except for &*TO;, &*URLENCODE(...); and &*INDEX;, which are allowed together with this system drop-in.

There also is a second, more specific system drop-in to generate a specific sharing URL. The name of this drop-in is:

*ShareURLForNAME

where the NAME part is replaced with name of the social media application for which the URL is to be generated (only names for registered social media applications can be specified).

This system drop-in is replaced with the sharing URL for the specified social media application.

Note, that this is a raw URL. If you want to make this into a clickable link in HTML, you need to enclose it into a suitable link tag, for example like this:

<a href="{{*ShareURLForTwitter}}">Share on Twitter</a>

System Drop-In: Forward-to-a-Friend URL

The drop-in name is:

*ForwardToFriendURL

This name is case-sensitive and requires this exact spelling as well as the correct drop-in enclosing tags (for example {{*ForwardToFriendURL}}).

It is replaced with a http:// URL that points to a special page which allows the recipient to enter one or several email addresses to which he wants to forward the same email as the one in which he found the forward link. This allows your recipients to share the messages that they receive with other people.

Usage of this system drop-in requires the "Forward-to-a-Friend" feature to be enabled and configured for the mail job. It is not enough to only include this system drop-in in the content.

Note: This system drop-in can not be used together with LISTSERV's conditional blocks (of the style .BB ... .EB), and also not together with the special LISTSERV merge placeholders that begin with an "*", of the type &*XYZ;. Except for &*TO;, &*URLENCODE(...); and &*INDEX;, which are allowed together with this system drop-in.


System Drop-In: Personalized Contact Data

This is a group of system drop-ins that allow to you merge your predefined personalized contact data into the email content, as defined via the menu option Utility -> Personalized Contact Data, Logo and Colors.

The drop-in names are:

*MyAddress
*MyColor
*MyEmail
*MyLegal
*MyPhone
*MyWebsiteURL

These names are case-sensitive and require this exact spelling as well as the correct drop-in enclosing tags (for example {{*MyAddress}}).

Each of these system drop-ins is replaced with the corresponding value from your personalized contact data.

In addition, the *MyWebsiteURL system drop-in supports the following usage:

  • You can either simply write the drop-in name with the enclosing tags, i.e. {{*MyWebsiteURL}}. In this case, the drop-in is replaced with the URL that you specified in your personalized contact data.

  • Or you can use this drop-in to generate a HTML link tag (an <a> tag) for you:

    {{*MyWebsiteURL aTagOpen}} is replaced with the following HTML code: <a href="YOUR_WEBSITE_URL_HERE" target="_blank">, or an empty string, if you have not specified a website URL

    {{*MyWebsiteURL aTagClose}} is replaced with the following HTML code: </a>, or an empty string, if you have not specified a website URL

    This is especially useful when designing templates. For example, you can put an image of your company logo into the template and surround this with the {{*MyWebsiteURL}} drop-in, like this:

    {{*MyWebsiteURL aTagOpen}}<img src="..." border="0">{{*MyWebsiteURL aTagClose}}

    If this template is used by a user who has not supplied a website URL in his contact data, then the two system drop-in occurrences is replaced with empty strings so that only the <img> tag remains, i.e. the result will be a non-clickable logo image.

    But if the same template is used by a user who has supplied a website URL, then the two system drop-ins will automatically be replaced with the correct HTML code to make the logo image into a clickable link that points to the user's website: <a href="URL_HERE" target="_blank"><img src="..." border="0"></a>


System Drop-In: List Name

This system drop-in is only available if the recipient type of the mail job is somehow based on a subscriber list or group.

The drop-in name is:

*ListName

This name is case-sensitive and requires this exact spelling as well as the correct drop-in enclosing tags (for example {{*ListName}}).

It is replaced with the name of the subscriber list or group that is used in the job's recipients (which is also the reason why this only works with the recipient types listed above).


System Drop-In: List Description

This system drop-in is only available if the recipient type of the mail job is somehow based on a subscriber list or group.

The drop-in name is:

*ListDescription

This name is case-sensitive and requires this exact spelling as well as the correct drop-in enclosing tags (for example {{*ListName}}).

It is replaced with the public description of the subscriber list or group that is used in the job's recipients (which is also the reason why this only works with the recipient types listed above).


System Drop-In: Subscriber Website URL

This system drop-in is only available if the recipient type of the mail job is somehow based on a subscriber list or group.

The drop-in name is:

*SubscriberWebsiteURL

This name is case-sensitive and requires this exact spelling as well as the correct drop-in enclosing tags (for example {{*SubscriberWebsiteURL}}).

It is replaced with a http:// URL that points to the public subscriber website of the subscriber list or group that is used for the job's recipients (which is also the reason why this only works with the recipient types listed above).

The URL will have roughly the following format:

http://YOUR.SERVER/list/area.html?...

System Drop-In: Subscribe URL

This system drop-in is only available if the recipient type of the mail job is somehow based on a subscriber list or group.

The drop-in name is:

*SubscribeURL

This name is case-sensitive and requires this exact spelling as well as the correct drop-in enclosing tags (for example {{*SubscribeURL}}).

It is replaced with a http:// URL that points to the subscribe page for the public subscriber website of the subscriber list or group that is used in the job's recipients (which is also the reason why this only works with the recipient types listed above).

The URL will have roughly the following format:

http://YOUR.SERVER/list/subscribe.html?...

System Drop-In: Unsubscribe URL

This system drop-in is only available if the recipient type of the mail job is somehow based on a subscriber list or group.

The drop-in name is:

*UnsubscribeURL

This name is case-sensitive and requires this exact spelling as well as the correct drop-in enclosing tags (for example {{*UnsubscribeURL}}).

It is replaced with a http:// URL that points to the unsubscribe page for the public subscriber website of the subscriber list or group that is used in the job's recipients (which is also the reason why this only works with the recipient types listed above).

The URL will have roughly the following format:

http://YOUR.SERVER/list/unsubscribe.html?...

System Drop-In: Profile Edit Page URL

This system drop-in is only available if the recipient type of the mail job is somehow based on a subscriber list or group.

The drop-in name is:

*ProfileEditPageURL

This name is case-sensitive and requires this exact spelling as well as the correct drop-in enclosing tags. In addition, inside of the enclosing tags the drop-in name must be followed by a comma-separated list of field names, for example:

{{*ProfileEditPageURL field1,field2,field3}}

Each name in this list must refer to a profile field of the subscriber list or group that the recipients definition of the mail job is based on. The field names are case-insensitive.

The drop-in is replaced with a http:// URL that points to the external profile edit page of the public subscriber website of the subscriber list or group that that the job's recipients are based on (which is also the reason why this only works with the recipient types listed above).

The content of this page (i.e. which fields appear on the page and which do not) is defined dynamically by the field list in the drop-in, so the page for the example above would contain only the fields FIELD1, FIELD2 and FIELD3, all other profile fields would be hidden. The email field or any fields that are hidden or read-only must not be included in the field list.

The URL will have roughly the following format:

http://YOUR.SERVER/list/editProfileExternally.html?...

System Drop-In: Job ID

The drop-in name is:

*JobID

This name is case-sensitive and requires this exact spelling as well as the correct drop-in enclosing tags.

It is replaced with the ID of the mail job in which the drop-in is used.


Formula Calculation

This system drop-in allows for the combining of merge fields from subscriber data with other merge fields, number-, text- or boolean-constants, sets of values or even predefined functions, into a formula that will then be calculated individually for each recipient to determine an individual drop-in replacement text for that recipient.

Example: A supermarket chain has a customer-card bonus-point system where customers are awarded points for every purchase. After collecting a certain number of points customers can swap points for bonus items, where the more interesting items require more points. If the recipient data contains a column CURRENT_POINTS that contains the currently collected points for each subscriber, normally only the value &CURRENT_POINTS; could be merged into the content, and then probably give a table of what bonus items are available for how many points. Now, with a calculation formula, more dynamic content can be merged like "You currently have X many points, which means that you only need Y points more to get the free widget or only Z points more to get the free trinket!".

The "name" of this drop-in is a directive with the following syntax:

*Calc FORMULA

The directive is case-sensitive and requires this exact syntax as well as the correct drop-in enclosing tags.

It is replaced with the result of the formula. If the formula contains merge-fields, this result will be calculated individually for each recipient and may therefore differ from recipient to recipient.

  • Replace FORMULA with a formula that follows the rules for calculation formulas.

See here for a detailed description of formulas and their rules.

Important: A formula that is used in a *Calc system drop-in must return a result of type Number or Text (it must not return a result of type Boolean, Text Set or Number Set). Also, in case of a return value of type Text, this text must not exceed 900 characters.
If the formula returns a wrong type or a text that is longer than 900 characters, then this will cause a delivery error of the mail job.

Example:

It is beyond the scope of this page to give all the possible examples for which formulas can be used. Here is just one simple example where a merge-field value (a number) is used in subtraction formulas with constant numbers to calculate the replacement values.

It should be noted, though, that formulas offer many more features, for example all the standard operators like +, -, *, / and % (modulo), which can be used in any combination and even be nested with parenthesis. Formulas can also work on text strings and there are a number of pre-defined functions, such as Abs, Min, Max, Random, Substring, etc.

Looking back to the example given above, with the supermarket bonus-points, assume that the number of required points for "widget" is 300 and the number of required points for "trinket" is 500. Depending on the value of CURRENT_POINTS there are four groups of customers:

  • those not eligible for either "widget" or "trinket" (0-299)
  • those eligible only for "widget" (300-499)
  • those eligible for "widget" or "trinket" (500-799)
  • and those eligible for both (800+)

In combination with LISTSERV's conditional blocks, the following personalized content can be created (indentations for readability only):

	.BB (&CURRENT_POINTS >= 800)
	.* Content for recipients eligible for both goodies

	Wow! You have already collected &CURRENT_POINTS; points!
	This means you are already eligible to get both Widget and
	Trinket! Get them while they are hot!
	After getting your goodies, you'll still have
	{{*Calc &CURRENT_POINTS; - 800}} points left!

	.ELSE
	.BB (&CURRENT_POINTS; >= 500)
	.* Content for recipients eligible for widget or trinket

	Congratulations! With your &CURRENT_POINTS; collected points
	you are eligible to get either widget (after which you will have
	{{*Calc &CURRENT_POINTS; - 300}} points left) or trinket
	(which will leave you with {{*Calc &CURRENT_POINTS; - 500}}
	points).

	.ELSE
	.BB (&CURRENT_POINTS; >= 300)
	.* Content for recipients eligible for widget only

	You are on track! For your &CURRENT_POINTS; you can already
	get Widget (which will leave you {{*Calc &CURRENT_POINTS; - 300}}
	points or you can collect {{*Calc 500 - &CURRENT_POINTS;}} more
	points to get Trinket!

	.ELSE
	.* Content for recipients eligible for no goodies yet

	Keep going! You already have &CURRENT_POINTS; collected!
	Only another {{*Calc 300 - &CURRENT_POINTS;}} points to go and
	you can get your own free Widget!
	Or {{*Calc 500 - CURRENT_POINTS;}} more points and you can
	get the free Trinket!!!

	.EB
	.EB
	.EB

Check if User Drop-In Has Content

This system drop-in allows you to check if a given user drop-in actually has a non-empty content or not. The system drop-in itself will always be replaced either by the text "true" or "false" (without the quotes), depending on if the referenced user drop-in has a non-empty content or not.
A non-empty content is a content with at least one non-whitespace character in it. I.e. all content which is either totally empty or which contains only whitespace characters (like space, tab, linebreaks, etc.) is interpreted as empty.

This system drop-in is usually used in a conditional block where its result (which is always either "true" or "false") is used in the condition to decide if a conditional block shall be included in the email or not. That way, it is for example possible to include a certain block only if a given user-drop is actually non-empty, or the other way round, include a certain block only if the user drop-in is empty.

The "name" of this drop-in is a directive with the following syntax:

*HasContent(NAME)

Where you replace NAME with the name of the user drop-in to check (do not specify the name of another system drop-in). The directive is case-sensitive and requires this exact syntax as well as the correct spelling of the user drop-in name and the correct drop-in enclosing tags.

Examples:

Assume that you have an auto-repeat job with a user drop-in called "DailyQuote" that pulls its content from a file. The job is sent on a daily basis and the content of the drop-in file is also updated daily, so that each day there is a different quote included. Only on some days there is actually no content at all for this drop-in. Now assume that in the part of the email where this drop-in is included, there is also some short intro-text, which is however only supposed to appear if the user drop-in is actually not empty. Also if the user drop-in is empty, a suitable replacement text should appear instead. For this a conditional block with the *HasContent system drop-in can be used (indentations for readability only):

	.BB {{*HasContent(DailyQuote)}} = true
	.* Included only if the "DailyQuote" user drop-in has content
	Here comes the daily quote:
	{{DailyQuote}}
	.ELSE
	.* Included if the "DailyQuote" user drop-in is empty
	Sorry, but we do not have a quote for you today.
	.EB

Assume that you have a job with a user drop-in called "Sample" that is included at some location in the mail job, where the drop-in also sometimes is empty. In case that it is empty, there is supposed to appear a certain alert text at another location in the same mail job. For this too a conditional block with the *HasContent system drop-in can be used (indentations for readability only):

	.BB {{*HasContent(Sample)}} = false
	.* Included only if the "Sample" user drop-in is empty
	Warning: The sample drop-in was empty!
	.EB
© 2002-2020 L-Soft Sweden AB. All rights reserved.