List and Direct Mail Management Programming Concepts

Article
01/18/2011

In Commerce Server Core Systems, the generic Commerce Server 2002 List Manager is replaced with a simplified mailing list management system that is part of Direct Mailer.

Manage Direct Mail-Specific Methods

You can use the Marketing Manager to create and manage direct e-mail advertising campaigns. Direct mail is a campaign item that you can target toward specific users by using mailing lists in the mailing list management system. You can create new direct mail items, personalize messages, add attachments to direct mail messages, and modify properties of direct mails. You can also test direct mails before you send them to production.

The following workflow shows a sample scenario for creating and managing a direct mail campaign:

Import a mailing list (for example, a list of top users).
Create a direct mail item targeting the mailing list of top users.
Enter the name of an HTML page that contains personalized content.
Add an attachment to the direct mail campaign.
Schedule the start times and end times for the direct mail item, and specify how frequently the direct mail job is to be sent.
Test the direct mail you sent against a test list, and view your personalization pages.

Direct Mail List Types

You can use the Direct Mail module to create and manage mailing lists. A mailing list is a list that contains a column of e-mail addresses, and can contain other optional columns. Direct Mailer uses mailing lists to send e-mail messages to selected recipients in the list. Mailing lists can be a static list of user e-mail addresses entered manually by using the Marketing Manager or imported from a file, or built dynamically by using an expression. You obtain expression list user information from the Profiles System.

Static Lists

You can create static mailing lists by using a text editor, SQL Server, Excel, and so on. After you have created mailing lists, you can import them, save them, and send them by using the List Management API. After you import the lists into the mailing list management system, you can use them to run Direct Mailer jobs and target users.

The mailing list management system recognizes the following input text file format; values must be separated by commas, one line per user:

Email Address, User ID, Message Format, Character Set, URL, Culture Code

You build static lists by using the properties listed in the following table.

Property	Comments
Email Address	Required. Format is name@domain.
User ID	Optional. A GUID that you use to provide content in a personalized e-mail message.
Message Format	Optional. Format that the Collaboration Data Object (CDO) translates the results into. The supported values are as follows: Text (1) MIME (2) MHTML (3) HTML (4) Note: The HTML format is new for Commerce Server 2009.
Character Set	Optional. The character set values that are used in direct mails, such as US-ASCII or ISO-8859-1.
URL	Optional. Individual URLs for each user to pass to the CDO.
Culture Code	Optional. Culture code, also know as Language Code—for example, "en-US".

When you specify properties, be aware of the following:

The only required field is Email Address. Commerce Server Core Systems strips any double quotation marks that enclose a field.
If you do not specify a property, but other optional properties follow, leave a comma placeholder for the property that you exclude.
You can add attachments to direct mail. An attachment can be any file that contains information.

Expression Lists

You can also build direct mail lists by using expression lists. Expressions are conditional statements that relate to profile properties.

You build expressions by using the properties listed in the following table.

Property	Data Type	Comments
List Name	String	Required.
Expression	ExpressionRef	Required. For example, all males with a street address in California. The ExpressionRef object evaluates to a list of user IDs (GUIDs). The Direct Mailer service uses the user IDs to fetch details for each user from the Profiles System, such as e-mail address, URL, message format, or language.

List Name

String

Required.

Expression

ExpressionRef

Required. For example, all males with a street address in California.

The ExpressionRef object evaluates to a list of user IDs (GUIDs). The Direct Mailer service uses the user IDs to fetch details for each user from the Profiles System, such as e-mail address, URL, message format, or language.

Importing Coupons and Mailing Lists

This section describes the system process used to import coupons and mailing lists. The process is the same for mailing lists and coupons.

In remote mode (through the Web service), import is a two-part process—upload and import. In the upload stage, the file that you want to import is transferred from the client to the Marketing database. The upload system divides the file into logical chunks and performs the transfer. The maximum size of a chunk stored in the Marketing database is determined by the maxUploadChunkSize (in kilobytes) setting in the Web.config file. The client must be online (connected to the Marketing Web service) for the duration of the upload phase of the import process.

After the upload is complete, the upload system then calls the appropriate import method (either on the mailing list management system or on the Coupon Generator service). At this point, all the information that the import process needs is available on the server. Therefore, if the client goes offline, the import can continue.

The following are Marketing resource properties that control import behavior:

i_MaxPromocodeImportFileSizeKB

i_PromocodeImportTimeOutHours

i_MaxMailingListImportFileSizeKB

i_ListImportTimeOutHours

In local mode import, there is no upload phase because the file is already available to the Marketing System.

Exporting Mailing Lists

In remote mode, you export mailing lists by writing the output to a special page of the Marketing Web service—ExportMailingList.aspx.

The Page_Load handler for these pages takes the export parameters as Web request query string arguments and streams the contents of the exported file as the body of this page.
The client side of the Marketing System accesses the page from the Web service and gets the response stream for this page.
The response stream is read and written to the file requested.

In local mode, you export mailing lists by directly writing the output to the export file.

Note

This process is the same for coupons, except the special page written is ExportPromocodes.aspx instead of ExportMailingList.aspx.

Maintaining Opt-out Lists

Commerce Server Core Systems supports a per-job opt-out list and a global opt-out list.

All opt-out lists are in the list database that can be accessed from the Management server and from the Production server. Lists and direct mails are not staged because direct mailings do not have to be run on the run-time server. However, the list database must be available from the run-time side (the ability to add and remove users in a list is required at run time) and from the management side.

When the Direct Mailer runs, it subtracts the per-job opt-out list and the global opt-out list. (There is an option to subtract the global opt-out list.) It considers the resulting mailing list and sends e-mail messages to the people on this list.

Registered users can add or remove themselves to or from the per-job mailing lists. For example, if a company offers two classes of mailings (mail direct from the company and mail from affiliates), the user can opt out of affiliate mailings but not from the company's mailings.

Personalizing a Direct Mail Message

You can personalize e-mail messages to users by using an ASP.NET page that has been designed for personalization. For example, you can include the first name of the user in a personal greeting. You can add special text to the ASP.NET page for delivery, and you can use information from the profile store for personalization.

If you do not specify personalization, Commerce Server Core Systems delivers the direct mail message as a plain HTML page.

A sample ASP.NET template for direct mail personalization is available in the /Microsoft Commerce Server 2009/SDK/Marketing directory.

Personalized ASP.NET Web pages are specified in the Message Body Source of the Direct Mail Properties within a Marketing Manager Direct Mail definition, or programmatically in the SourceLocation property of the DirectMail object. For example, use https://localhost/startersite/DirectMailPage.aspx as a source location.

Copying the List Database to a Different Tier

If you need to copy the List database from the Marketing Management database to another database in the management tier or production tier, do the following:

Create a Pup file for all marketing tables. (List data is not packaged in the Pup package.)
Make a copy of the original list database .ldf and .mdf files. You might need to temporarily detach the database in order to do this. Otherwise the files might be unavailable while they are being used.
Unpack the package you created into a different database or tier. A new list database (for example, site_marketing_lists) is created on this tier.
Detach the newly created list database (site_marketing_lists) and attach the copies of the .ldf and .mdf files from step 2.

Auth Module

Direct Mailer uses the Commerce Server Core Systems Authentication resource to obtain the encryption key that Commerce Server Core Systems uses to encrypt profile tickets. The HTTP Auth module has access to the same key in order to decrypt the tickets. Therefore, both the direct mailer service that connects to the personalized Web page and the site that hosts the personalized Web page (the Direct Mailer Auth module runs as part of the site) have a dependency on the Commerce Authentication resource. This is true even though the site might not be using Commerce authentication and might be using ASP.NET authentication instead. Therefore, you should associate an Authentication resource with the site if you create personalized direct mails by using Direct Mailer.

Asynchronous Mode

The mailing list management system enables you to run time-consuming operations asynchronously. When it is run asynchronously, the operation returns immediately after the process has started. An application that starts an operation asynchronously has the following additional methods that you can use:

WaitOnOperation method returns when the operation is finished or a timeout has occurred.
GetOperationInfo method returns all details of the operation including its current status.
CancelOperation method signals the operation to stop. If the operation does not stop in two minutes, the operation is stopped.

List Pup Packaging

The Site Packager treats the Marketing resource in a special way. Mailing list definitions are packaged; including List Name, ID, and Description, but not the mailing list content. For static lists, the mailing list content is not packaged because this might be a very large amount of data. Use the Export method of the MailingListManager class to preserve this data. For expression lists, the whole definition is packaged. But the profiles that the expression operates on must be packaged separately.