Section 5
Defining and Editing Content for a E-mail Job

Defining the e-mail message to be sent to the recipient list is the next phase of creating a new e-mail job. LISTSERV^® Maestro will copy content from a previously defined e-mail job, or original content can be uploaded or entered as plain text, as HTML, or both. It is possible to include attachments to messages as well as select the language character set used to encode the message.

Figure 18 Define Content

5.1 Creating Text Messages

To add a plain text message to LISTSERV^® Maestro, select the "Plain Text" option button next to "Body:" Type in the box or click Upload Plain Text to upload a text file. Uploading a file composed in a word processing program can be advantageous because it is possible to use spelling and grammar checks. Just be sure to save the file as text, not in the word processor format. Maestro offers neither a spell check nor a grammar check. Click OK when finished composing the message.

Important Note: In order to track links inside of text messages, it is necessary to enclose the URL within of quotation marks ("http://www.lsoft.com"). These quotation marks will be removed from the recipient’s copy of the message, and serve only to let the system know that there is a trackable link in the message.

5.2 Creating HTML Messages

There are several ways to compose HTML messages in LISTSERV^® Maestro:

• Upload an HTML file from a local drive.
• Copy and paste HTML source code from another application.
• Type in HTML source code.

LISTSERV^® Maestro does not contain a WYSIWYG HTML editor. HTML messages can be created locally in any HTML editing program and uploaded to LISTSERV^® Maestro.

In order for any links to be tracked in an HTML message, they must be enclosed within quotation marks. Generally speaking, most good HTML editors will do this automatically, but it is possible to create a link without quotation marks that will be read in Internet Explorer (because this browser is very forgiving of HTML coding errors). If in doubt, or if there is trouble selecting a tracking definition for a seemingly good link, double check the HTML coding of the links. An example of correct coding appears below:

<a href="http://www.lsoft.com">Link text goes here</a>

Omitting the quotation marks would result in incompatible coding for LISTSERV^® Maestro tracking, as in the example below:

<a href=http://www.lsoft.com>Link text goes here</a>

In order to upload HTML files into LISTSERV^® Maestro, it is necessary to have the Microsoft^® Java Virtual Machine (MS JVM) installed. This ensures that any accompanying image files for backgrounds, banners, icons, diagrams and pictures will be automatically uploaded with the source code. Most systems already have MS JVM already installed, but if a system does not, download Microsoft Virtual Machine from: http://www.microsoft.com/java/vm/dl_vm40.html

The first time a file is uploaded after the Microsoft Virtual Machine is installed, a Security Warning dialogue box will appear asking for permission to use the L-Soft applet to upload HTML. Grant permission and check the box "Always trust content from L-Soft International" so that the grant dialog box will not reappear. If this box is not checked, it will be necessary to grant permission to use the applet every time HTML files are uploaded in a new instance of Internet Explorer. Another dialogue box will appear to browse for the file. Select the file to upload and click OK. If there are any image files that are linked remotely or embedded from local files, a dialogue box will appear listing each and asking whether to proceed with the upload. Click Yes. The HTML message will then appear in the HTML box.

• Upload HTML from the Define Content screen.
• Grant permission to install and run HTML Upload Applet (for the first time only).

Figure 19 Grant Permission to Install Applet

• Browse a local drive for the file and then click OK.

Figure 20 Browse for File

• Review Load Properties and then click Yes to continue.

Figure 21 Load Results

The LISTSERV^® Maestro applet will also check to ensure internal and external references to linked or embedded image files are valid. Linked files are not sent with the message; embedded files are sent with the message. One advantage of using linked files is that the message will be smaller in size. However, a live Internet connection is necessary to view linked files. If the image server is down, they will not be visible. Also, some firewalls strip HTML messages that contain links to outside sources thus rendering the image invisible. Embedded files, on the other hand, will be visible without a live Internet connection and if the image server is down. They will make the message larger, but they will not, in most cases, be stripped from the message by a firewall. Consider the use of images, linked or embedded, carefully to avoid complications for the recipients.

Any invalid links will be counted as errors and will be reported in the "Load Results" dialog box. If Yes is clicked, Maestro will continue uploading the HTML file even if it contains link errors. The error report is only a warning to remind the user that there are currently problems but the upload is not suspended. The reason that uploads are not halted when the HTML contains errors is that the linked files simply may not be available yet. Sometimes referenced Web sites are under development or are being updated as the e-mail message is being created. Once the linked site is complete, the message will be valid and can be sent out.

If an alternative text file is desired to accompany an HTML message for those who cannot receive HTML e-mail, it will have to be uploaded or copied/pasted into the screen for "Alternative Text". Any trackable links in the alternative text message must be enclosed within quotation marks the same way as the plain text message trackable links are enclosed.

Files downloaded after completion of this process are downloaded as .ZIP files.

5.3 Adding Attachments

Any type of file can be included as an attachment to an e-mail message. There is no limit to the number of files that can be attached to a message, but there may be a limit to the size of each attachment set by the system administrator. Large attachments or numerous attachments can slow down the delivery of the message and use up bandwidth. Consider using a link to the information, if possible, instead of an attachment. That way, processing time is faster, less bandwidth is used, and the link can be tracked.

To attach a file to a message, click the "Attachments" tab on the Define Content screen. Click Add Attachment to browse for a file from a local drive. Attachments are copied as part of the message content when content from one job is copied to another job.

Figure 22 Define Content Attachments

5.4 Setting the Language Character Set

A character set (also called charset, character encoding, code page or character page) is simply a table that matches numbers (the digital information sent by computers over the Internet) to letters, or more precisely, characters. Due to the nature of digital information and e-mail, (all data is reduced to numeric code), there is a finite number of "positions" in this table to correspond to letters and other symbols of a language. Therefore different charsets have been developed to correspond to the different letters and symbols for different languages. A charset will not translate one language to another; it only encodes data to match positions in the table to specific characters. For example, in the charset ISO-8859-1 (matching an alphabet suitable for West-European languages), the position number 196 represents the umlaut Ä. The same position, 196, using the charset ISO-8859-7 (the Greek alphabet), matches the Greek letter Δ. As a result, the same position number in the table will result in different characters being displayed, depending on the charset used for the encoding. For more information on this subject, see Appendix B in this guide.

LISTSERV Maestro defaults to the ISO-8859-1 (Latin 1) character set for encoding e-mail messages (unless a different default setting has been preset by the system administrator). LISTSERV Maestro does supports other charsets, and if users are given the right to use other character sets, an active link will appear at the end of the sentence "Language: Mail will be sent with language charset for..." on the screen. The link will be different depending on whether a different selection has previously been made. The default link is West European (Latin 1 charset ISO-8859-1).

To choose a different charset, click the active link after "Language:" The Language Charset Setting screen will open. Select a charset from the drop-down menu and then click OK.

Figure 18a Language Charset Settings

If LISTSERV Maestro is being used in a single language environment, either with plain English or with one of the common (West) European languages, the safest choice for a character set (charset) is always ISO-8859-1 (Latin 1) charset. It contains all 26 common characters (both in upper and lower-case), all the common punctuation characters and the more common special characters like '@', '+', '*', and others. In addition, it contains the more uncommon characters required for most West European languages, like 'ö', 'å', 'ç' and others.

It is not always necessary or possible to change the charset for e-mail messages. Using other charsets can become quite complex, especially when merged data is involved. Each charset has advantages and disadvantages that are described in greater detail in the online help and in Appendix B of this guide.

5.5 Merging Fields and Conditional Blocks

LISTSERV^® provides the ability to customize mail messages for each recipient by merging in values uploaded with the recipient data or conditionally including blocks of text based on the preferences indicated in the recipient data. These values are taken from columns that are present in the recipient data.

To merge a field into the message, simply enter the field name (or header name in the case of an uploaded file), used in the recipient definition and precede it with an ampersand ("&") and follow it with a semi-colon (";").If the recipients data is derived from a LISTSERV^® list, then the only merge substitution fields available are &*TO; for the e-mail address and &*NAME; for the name.

The following example demonstrates how overdue book notices can be customized using specific recipient data in the form of the fields EMAIL, NAME, IDNUM, BRANCH, BOOK1, BOOK2, BOOK3. A text message merging the fields might look like this:

Figure 23 Merge Fields Example

In an HTML message, the HTML source should be altered to include the merge fields, being careful to respect the HTML code.

In an HTML message with alternative text, remember to put the merge fields in both the HTML source and the alternative text.

Conditional blocks are coded by using the ".BB", ".ELSE", and ".EB" directives. These directives must each be on a line by itself. The ".BB" directive begins the conditional block, and "condition" follows ".BB" on the same line. The ".ELSE" directive is optional and starts a text block to be used for the opposite condition as was used for the ".BB". The ".EB" directive ends the conditional block. Fields used in a conditional block should be preceded by the ampersand, but should not be followed by a semicolon. Lines that start with dot asterisk ".*" are used as comments and do not appear in the final message to the recipients.

For example:

If conditional blocks are used in an HTML message, first create the basic HTML message, then go into the HTML source code and correctly insert the conditional statements, making sure to maintain proper HTML syntax once the directives are followed. The HTML page will now look incorrect because the directives are interpreted as part of the HTML source. It is important to test all possible conditional values in the testing stage (see Section 7.2), to make sure that the HTML code works correctly in all cases.

Mail-merge substitutions and conditional blocks are explained in more detail in the LISTSERV^® Developer's Guide.

5.6 Using Merged Parameters within URLs

URL parameters are specially constructed parts of a Web address (URL) that allow that single URL to initiate various specific operations by passing particular instructions and data to the Web server. Parameters are text based instructions and data that are passed to a Web server, which passes them on to a script, (for example a Java, Perl, C/C++, or a UNIX shell script). The script then executes the corresponding parameter as instructed by the URL, and passes the results back to the Web server. The Web server then returns the results to the client. In essence, parameters can be used to select a certain page or part of a page to display, or tell the server which page to display to a specific user or type of user.

A URL-parameter is a pair like "name=value" which appears after the path-part of the URL, separated from the path by a question mark "?", like the example below:

http://host.domain/path?param=value

If there are several parameters in one URL, then the individual parameters are separated by ampersand characters "&":

http://host.domain/path?param1=value1&param2=value2

• Constant URL-parameters are parameters that are the same for all URL visitors. A typical use of a constant parameter is to select a certain page, or part of a page. The following imaginary URL would tell the server to show the "electronics" page and the 15^th item on that page:

http://host.domain/path?page=electronics&item=15

• Individual URL-parameters are different for each individual URL. A typical use of an individual parameter is to tell the server about the identity of the visitor. The following imaginary URL would tell the server that the user with the ID "usr18" is visiting the page. The URL also contains a constant parameter that tells the server that it is supposed to show the "home" page:

http://host.domain/path?visitorID=usr15&page=home

Different visitors would have different values of the "visitorID" parameter. For example, the following URL would tell the server that this time the visitor has the ID "usr217":

http://host.domain/path?visitorID=usr217&page=home

LISTSERV^® Maestro allows the user to track URLs with or without parameters as well as URLs with constant or individual parameters. Since URLs with individual parameters need to have a different value for the parameter for each recipient, how can such a URL be written in the text of the message?

By using field merging, it is possible to create unique URL parameters based on the fields of a database. For example, assume there is a merge field named "ID" for each recipient that contains the visitor ID of that recipient, then the sample URL of above would be written as:

http://host.domain/path?visitorID=&ID;&page=home

Let us dissect the different parts of this example:

The URL begins as the usual protocol header, the host name and the URL-path:

http://host.domain/path?visitorID=&ID;&page=home

Next follows the the question mark, signaling the end of the path-part and the beginning of the parameter-part:

http://host.domain/path ?visitorID=&ID;&page=home

The first parameter is the parameter "visitorID" with the value "&ID;":

http://host.domain/path?visitorID=&ID;&page=home

Between the first and second parameter is the ampersand as a separator:

http://host.domain/path?visitorID=&ID;&page=home page

Thesecond parameter is the parameter "page" with the value "home":

http://host.domain/path?visitorID=&ID;&page=home

The second part of the first parameter "visitorID=&ID;" uses the LISTSERV^® Maestro convention of denoting mail merge fields. Its value is not an actual user ID, but instead is the name of the merge field "ID", with the preceding ampersand and the trailing semicolon, (which are always used in LISTSERV^® Maestro to mark mail merge fields).

Although the ampersand usually has the reserved function of separating two parameters (like the second ampersand right before the "page" parameter), when it appears to denote the merge field "&ID;" it is acting as a token that will be replaced by the corresponding value of the recipient before the mail is sent out. Therefore, this string will not be present in the final e-mail that appears to the recipient; instead it will have been replaced by the merge value of that recipient.

http://host.domain/path?visitorID=usr15&page=home

or

http://host.domain/path?visitorID=usr317&page=home

By employing LISTSERV^® Maestro’s mail merging features, it is possible to insert URLs that contain constant and individual parameters for each recipient into e-mail messages.

LISTSERV^® Maestro is able to track all of these URLs if they are marked for tracking. As a result, if a URL that contains a merged parameter is selected for tracking, LISTSERV^® Maestro will count all clicks of all recipients on this URL, and each recipient will be directed to the actual URL using his or her own individual parameter.

http://host.domain/path?visitorID=&ID;&page=home

In the e-mail messages that are sent out, the URL is replaced by a special tracking URL, that points to the server running the Maestro Tracker component, so that LISTSERV^® Maestro can count each click on the URL and then redirect to the actual target URL.

http://maestro.domain/trk/click?ref=z4bx39x&visitorID=usr15&page=home

Each user that clicks on this tracking URL will be counted and will be redirected to the actual target URL, using the URL-parameters for that user. For example, the server at "host.domain" will receive the correct "visitorID=usr15" and "page=home" parameters (for other recipients, the "visitorID" would have different values).

5.6.1 URL-encoding of Parameters

URL-parameters may only contain characters that are safe to use in a URL. Some characters are not safe to use, other characters have a reserved meaning (such as, for example, the ampersand (&), which has the special meaning of separating two parameters). Therefore, all characters that are not valid for use in a URL parameter value must be "URL-encoded". URL-encoding is a standard that encodes unsafe characters into safe characters.

When using field merging in URL parameters, there are two options to ensure that all parameters are URL-safe:

• Make sure that the values of all merge fields that are used (of all recipients) are actually URL-safe. For example, if all recipient IDs only contain alphanumeric characters, the ID values are already URL-safe because alphanumeric characters are, by definition, URL-safe. It is important to know how recipient IDs are generated by a registration script, for example, in order to know if they are indeed URL-safe.
• If the possibility exists that all merge values are not be URL safe, then use the special LISTSERV^® function "&*URLENCODE()" to make them so. Simply enclose the merge field in the URL in the parenthesis of this function. In the example, if there were any doubt that the ID merge field’s values were URL safe, the sample URL could be written like this:

  http://host.domain/path?visitorID=&*URLENCODE(&ID;)&page=home

The function "&*URLENCODE(&ID;)" tells LISTSERV^® to retrieve the value of the "&ID;" merge field, then apply the "&*URLENCODE()" function to it, that is to encode all unsafe characters, and then merge in the result in place of the whole "&*URLENCODE(&ID;)" string.

Important Note: The parameter name "ref" is a reserved name that is used by LISTSERV^® Maestro to transfer the tracking information to the Maestro Tracker component (seen in the example above). Therefore"ref" cannot be used in any parameters if there are also merge fields in the same URL. If a URL looked like:

http://host.domain/path?ref=&ID;

http://maestro.domain/trk/click?ref=z4bx39x&ref=usr15

This URL contains two parameters with the name "ref". One comes from the original URL, while LISTSERV ^® Maestro added the other. These two parameters with the same name would confuse the Maestro Tracker component. Therefore, a parameter called " ref" must never be used if there are merge fields used in the URL.

http://host.domain/path?param1=value1&param2=value2&param3=value3

http://maestro.domain/trk/click?ref=z4bx39x&

Since the parameters are also replaced by the tracking URL, it does not matter whether the parameter list contains a parameter called "ref" or not. However, this is only true if no merge field is used in the parameter list, meaning that there are only constant parameters.

Back One Page | Forward One Page