Section 4 Defining Recipients of an E-mail Job

The next step in creating an e-mail job is to define or select the recipients of the message. Recipients can be selected from a past job or a new recipient definition can be created. LISTSERV^® Maestro also gives the user the option of eliminating duplicate recipients based on e-mail address or other unique column identifiers. Generating a new recipient definition is a multi-step process:

• Options – Deciding where the recipient data will come from.
• Source - Selecting the source information and/or uploading a source file from which the recipient data will be generated.
• Source Details – Interpreting the recipient data file into labeled columns such as name and e-mail address.
• Recipient Details – Adding or editing header information (labels for columns).
• Summary – Displaying the interpretation of the recipient data in a table for review.

4.1 Options

The first screen that opens in the define recipients process is the "Options" screen. There are five options that can be selected to define the source for a recipient list:

• Use Recipient Definition from Job – Selection of recipient data is generated from a previous job. Simply select the job using a pull-down menu listing the jobs available.
• New Recipient Definition – Creates an original recipient list for the job from data generated from:
• A text file that is uploaded into the system.
• A LISTSERV^® Maestro defined database that is connected to by a plugin installed and configured by the LISTSERV^® Maestro system administrator.
• A LISTSERV^® list owned by the e-mail address registered for the LISTSERV^® Maestro account.
• A database that has been configured to be accessed directly by LISTSERV^®.

Select either "Use Recipient Definition from Job:" (and choose a job from the pull down menu) or "New Recipient Definition" and click the option button next to where the recipient list will be generated. Click Next -> to continue.

The <- Back and Next -> buttons navigate to the previous and following pages, automatically saving any changes on the current page. Click on any active link to skip that screen. Click Cancel to close the wizard without saving changes and return to the Workflow or Summary diagram page.

Caution: Do not use the browser’s back button to navigate within the program because entries may not be automatically saved.

Figure 8 Define Recipients Options Screens

4.2 Source

The next step is to define or upload a "Source" for the recipient data. Depending on the Options selected in the previous screen, different prompts will appear as the Sourcescreen, requesting different information in order to create the recipients list.

4.2.1 Uploading a Recipient Text File

By choosing the option "Upload a recipient text file", the Source screen that opens contains a clickable link, Upload a recipients file, to upload a text file from a local drive. Browse for the file on a local drive and choose the encoding for the file if necessary. For more information on encoding, see Appendix B E-mail and International Character Sets.

Figure 9 Define Recipients from an Uploaded File

Once a file had been uploaded to LISTSERV^® Maestro, the information about that file will appear on the screen. The link to upload a file will change to Upload a different file after one file has successfully been uploaded to the system. Click Next -> to continue or <- Back to return to the previous page.

4.2.2 Selecting Recipients From a Database

Choosing the option "Select recipients from a database" opens a Source screen that requires the selection of a database plugin and entering a SQL statement. The SQL statement is entered in the text box at the bottom. SQL statements can be copied and pasted into this text box from another source.

Database plugins are available from L-Soft and should be installed by the system administrator when LISTSERV^® Maestro is first installed. These plugins allow LISTSERV^® Maestro to communicate with many different types of databases. If there is any uncertainty about the selection of database plugins, contact the system administrator, the database administrator, or see Section 9 in the LISTSERV^® Maestro Administrators Guide.

The database administrator will furnish other information, such as username, password, host name and port number that are needed for LISTSERV^® Maestro to get information from the database. The database administrator can also create the SQL statement that tells the database what fields and what criteria to incorporate into the recipient list.

 Although initially it may take some assistance from the system administrator or database administrator, selecting recipients from a database is a much faster method of defining recipients for a job when compared to uploading a text file. Because recipient data comes directly from a database, it becomes unnecessary to export the data, upload a large text file, and parse the file, therefore saving time.

Figure 10 Define Recipients from a Database

Click Execute SQL to continue.

4.2.3 Sending to an Existing LISTSERV^® List

The option "Send to an existing LISTSERV list" uses the identified list’s subscriber names and addresses to create the recipient list for the e-mail job. There are two options here: to send the message as a "standard list message" to subscribers (which will limit the tracking options), or as a "special list message" that allows for mail merging and more tracking options.

If the message is sent as a standard list message, the "From:" address field in "Define Sender" must be an authorized sender for that list. If the message is sent as a special list message, then the LISTSERV^® Maestro e-mail address must be an owner of the list. By choosing "Send job as special list message" an additional link, Special distribution options available here becomes active. Click this link to expand the screen and display conditions and options for the list. The screen needs to remain expanded in order to use the selections made in the expanded version.

Figure 11 Define Recipients from a LISTSERV^® List

Setting a "Condition" is a means of creating a subset of recipients from the selected LISTSERV^® list based on information in a database. For information on setting conditions for a LISTSERV^® list see the LISTSERV^® Developer’s Guide, available online at http://www.lsoft.com/manuals.html.

There are four "Options" for a LISTSERV^® list that can be set by checking the adjacent boxes. The options are standard LISTSERV^® settings that subscribers may have set for their subscriptions.

• MAIL – Will deliver the message to all normally subscribed users.
• DIGEST - Will deliver the message to users that receive only a digest.
• INDEX – Will deliver the message to users that receive only a topics index.
• NOMAIL - Will deliver the message to users that currently receive no mail.

Click Next -> to continue.

4.2.4 Letting LISTSERV^® Select Recipients From a Database

The option "Let LISTSERV select recipients from a database" relies on a pre-existing configuration of LISTSERV^® connected to a database or databases, whereas LISTSERV^® acts as the communicator between the database(s) and LISTSERV^® Maestro. This option may only be used if LISTSERV^® has been set up to work with a database or databases. The site administrator should consult the LISTSERV^® Developer’s Manual for details.

If LISTSERV is connected to multiple databases, enter the "server name" defined in LISTSERV’s configuration in the "Database Server" textbox. Enter the SQL statement selecting the recipients in the "SQL Statement" textbox.

Figure 12 Define Recipients from LISTSERV^® Connected Database

Click Next -> to continue.

4.3 Source Details

The Source Details link will only become active if LISTSERV^® Maestro needs to interpret data that has been uploaded. If recipient data is taken from a database or a LISTSERV^® list, the data has already been interpreted. If a text file is uploaded, LISTSERV^® Maestro will have to attempt to understand the way the data is arranged.

LISTSERV^® Maestro will try to determine how the columns of data are separated, and how each column or field of data is labeled. In order to send out an e-mail job, Maestro must correctly interpret which column is the name of the recipient and which column is the e-mail address of the recipient. Other fields may be included and will appear in the results table located on the lower half of the screen.

Figure 13 Define Recipients Source Details Parse Recipients

Click the Next -> button to continue if the parsing is correct. If LISTSERV^® Maestro has not interpreted the data correctly, or an unconventional delimiter and/or quote symbol has been used, click on the link to Specify details manually to configure the data manually.

Use the Specify details manually link when the delimiter (separator character) or the quote character is used in some of the fields of the data. For example, if the NAME field contained Tom "the cool cat" Jones as an entry and double quotes was the quote character for the file, or if the LOCATION field contained the entry "Atlanta, GA" where the comma was the separator character. See About Comma Separated Format Recipients Files for more information.

Figure 14 Define Recipients Source Details Character Encoding

Maestro has four selections for choosing separator characters:

• Tab (\t)
• Comma (,)
• Semicolon (;)
• Other – if this is chosen, type the character into the adjacent box. Columns can be defined as "not enclosed by a quote character" or select the quote character from three choices:
• Double Quotes (")
• Apostrophe (‘)
• Other  – if this is chosen, type the character into the adjacent box.

In addition to interpreting the separator character and the quote character, LISTSERV^® Maestro will select the encoding used to create the text file. If the original data file was created with a specific character set, such as Greek characters, the file encoding will have to be changed to match that character set. Use the pull down menu to select the encoding for the file if it is different than the default. For more information on encoding, see Appendix B E-mail and International Character Sets in this guide.

After separator and quote characters have been entered, and any encoding change made, click Refresh Preview to have LISTSERV^® Maestro attempt to parse the file again with the new settings. The new columns will then be displayed. If the columns are now separated correctly, proceed. If the columns are not correct, repeat the process and click Refresh Preview to see the new changes.

4.4 Recipients Details

Once Maestro can successfully separate the recipient data into columns, it becomes necessary to define the column that identifies the e-mail address. LISTSERV^® Maestro also needs to know if additional recipient data will be used for mail merging and tracking, or whether this information is to be ignored and the job sent as bulk e-mail. If LISTSERV^® Maestro has used a database or a LISTSERV^® defined database, it is necessary to identify the column for e-mail address.

If the "Use additional recipient data for mail merging and tracking" option button is selected, columns from the text file can be used in the e-mail message to create personalized messages. These columns can then also be used to identify recipients for more detailed tracking reports. For more information in this guide on using mail merging, see Section 5.5 Merge Fields and Conditional Blocks. If the "Ignore additional recipient data and send job as bulk e-mail" option button is selected, any additional columns that were uploaded with the file will be ignored by the system. It will not be possible to use mail merge. Tracking for the message will be limited to "blind" tracking, meaning that the tracking data available from the job will not be associated with identifiable individuals or other demographic information.

If a text file was uploaded, it is possible to add or edit the headers. Headers are specially defined rows in databases. Headers are used by database tables to label the columns of data so that the system and the user can correctly identify the columns. Recipient data files containing a header will be sorted or parsed by LISTSERV^® Maestro based on that header row, and the table reflected on the screen will have the columns labeled. If the recipient data file does not contain a header, it is possible to define a header within LISTSERV^® Maestro.

Figure 15 Recipients Details for Uploaded Text File

Remember: in order to process an e-mail job, LISTSERV^® Maestro needs to know which column represents the recipient’s e-mail address and optionally the recipient’s name. Other column labels can be added or edited within the "Header Definition" table.

Header labels are limited to upper and lower case letters, the numbers 0-9 and the underscore "_". Any illegal characters in the headers will have to be changed before proceeding. Before continuing to the next screen, specify the "E-mail Column" and the "Name Column" using the pull down menus.

Figure 16 Recipients Details from LISTSERV^® Selected Database

Click the Next -> button to continue.

4.5 Summary

A Summary of all the recipient list selections is shown on the last page of the define recipients function. LISTSERV^® Maestro will validate the recipient list data file, checking for errors in the e-mail addresses that would prevent the e-mail from being delivered. From this screen it is possible to download the validated recipient list and the list containing recipients who have been rejected. A sample of the recipient list will appear at the bottom of the screen.

LISTSERV^® Maestro can also eliminate duplicate recipients. Click on the Define duplicate elimination button to initiate this function. Duplicates can be removed based on one or more selected criteria. To select more than one criterion for removing duplicates, hold down the Shift key or the Ctrl key and click on the columns desired.

Removing duplicates from recipient data can be a useful way to ensure that multiple messages are not sent to the same recipient. It is common practice for one person to have more than one e-mail address, for example, a work e-mail address and a personal e-mail address. By creatively selecting one or more criteria to remove duplicates, it is possible to avoid sending multiple messages to same person with different e-mail addresses. Similarly, several recipients may use the same e-mail address, for example family members sharing an ISP may also share an e-mail address. In this case it might be desirable to send multiple messages to the same address shared by multiple recipients, but addressed to each individual using the e-mail account.

Figure 17 Recipient Summary and Duplicate Elimination

Click Finish to save all settings and return to the Job Details screen and to the Summary or Workflow diagram. The recipients can always be edited by selecting the Edit link from the Summary diagram or clicking on the icon Define Recipients from the Workflow diagram.