Section 1
Introduction

Section 2
The Maestro Interface

Section 3
Defining a Job

Section 4
Defining Recipients

Section 5
Defining Content

5.3 HTML Messages

5.4 Attachments

5.5 Langauage Character Set

5.6 Merge Fields and Conditional Blocks

5.7 Merged Parameters within URLs

Section 6
Defining Tracking

Section 7
Sender and Delivery Options

Section 8
Outbox

Section 9
Delivered Jobs

Section 10
Reporting and Statistics

Section 11
User Settings

Appendix A
24 Hour Clock

Appendix B
International Character Sets

Appendix C
 Comma Separated Files

Appendix D
 AOL Rich Text

5.7 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 15th 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.7.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