Copyright (c) 1999 Persits Software, Inc.
All rights reserved.

Introduction

EmailAgent 1.2 is a Windows NT service which works together with the Persits Software AspEmail component to send queued email messages in the background. Your mail-sending ASP script no longer has to wait until a message is sent. Instead of sending a message, AspEmail places it in a message queue for EmailAgent to pick up and send out.

AspEmail 4.1+ has a new method, SendToQueue, which, unlike the Send method, does not attempt to send a message to the SMTP server. Instead, it packages the message into a file, places it in a message queue, and immediately returns control to the calling script. The EmailAgent service, a background process, constantly polls the message queue and retrieves messages in the order they were placed in the queue. EmailAgent unpackages a message file and attempts to send it out using the AspEmail component. The EmaiAgent service can run on the same machine as the Web server, or a different machine.

• Optional random access to queued messages is implemented to improve performance.

• Deferred message processing implemented.
• Minor bugs fixed.

Microsoft Windows NT 4.0+
Persits Software AspEmail 4.3 (downloadable from http://www.aspemail.com)
IIS 4.0+/ASP or VB 5.0+

Note: the AspEmail.exe setup downloadable from www.aspemail.com will offer to install EmailAgent on your machine automatically. If you choose to install it manually, make sure the AspEmail component has been installed and registered on your machine.

EmailAgent 1.2 consists of two files:

EmailAgent.exe - the actual EmailAgent service software.
EmailAgentCfg.cpl - a Control Panel applet which you can use to configure the EmailAgent service.

The installation procedure consists of the following three steps:

Step 1

EmailAgent.exe should be placed in a folder, say c:\EmailAgent. Register the service by executing the following command at your MS DOS prompt:

c:\EmailAgent>EmailAgent -service

Step 2

The EmailAgentCfg.cpl file must be copied to the c:\winnt\system32 system directory.

Step 3

A message queue folder must be created on your hard drive, for example d:\myqueue.

Make sure the EmailAgent service has been successfully registered by going to Start/Settings/Control Panels and clicking on the Services icon. The EmailAgent service should appear in the list of services under the name Persits Software Email Agent, as follows:

Before the EmailAgent can be started, it must be configured using the EmailAgent Control Panel applet. Once the file EmailAgentCfg.cpl has been copies to the c:\winnt\system32 directory, it should appear in the Control Panels window as follows:

Click on the EmailAgent icon. The Email Agent Configuration dialog box appears which allows you to set up four configuration parameters:

Message Queue Path

This is the most important parameter without which the EmailAgent cannot be started. It points to a directory where messages will be queued to be sent by EmailAgent. Point it to the folder you created in Step 3 of the installation procedure. Once EmailAgent is started, it will automatically create two sub-folders, \Sent and \Failed, underneath the queue folder to store sent and failed messages, respectively.

Poll messages every... seconds

This parameter specifies how often EmailAgent is to poll the message queue for new messages in case the queue is empty. The default value is 10 seconds.

Do not move sent messages to the \Sent folder

If this checkbox is checked, EmailAgent will delete messages that have been successfully sent. Otherwise, it will move the sent messages to the \Sent subfolder. In either case a sent message is deleted from the queue.

Retrieve messages from queue in random order to improve performance

By default, EmailAgent retrieves messages from the queue for delivery in the order they were placed there. Searching for the oldest message in the queue involves examining timestamp information of all messages which may be time-consuming if the number of queued messages is large ( 1000 or more). If this option is checked, EmailAgent will skip the search procedure which may improve performance significantly, but the messages will not necessarily be delivered in the order they were placed in the queue.

The EmailAgent Control Panel applet saves the four configuration parameters in the system registry under the key HKEY_LOCAL_MACHINE\SOFTWARE\Persits Software\AspEmail\EmailAgent (named values  Path, PollDelay, DeleteOnSuccess and RandomOrder, respectively).

Using the Services control panel, you can configure the EmailAgent service to start automatically at system startup. Select "Persits Software Email Agent" in the list of services, click the Startup button and select "Automatic".

Once the Message Queue Path is specified using the EmailAgent Control Panel applet, the EmailAgent service can be started by clicking the Go button in the configuration dialog box. If the service launch was successful, the streetlight on the dialog box turns green and the status string reads "EmailAgent is started." In case of a failure, an error message box pops up and the status string displays appropriate status information. EmailAgent may fail to start under these two conditions:

1. The AspEmail 4.1+ component is not installed on this machine. You must download the AspEmail component from http://www.aspemail.com and install it according to the AspEmail manual.

2. The message queue path is not found in the system registry. You must specify the message queue path using the EmailAgent Control Panel applet or manually using regedit.

The EmailAgent service can also be started using the standard Services control panel.

It is extremely simple to change your ASP or VB script from using AspEmail in the direct sending mode to EmailAgent-assisted queue mode. All you need to do is replace all the Mail.Send calls by Mail.SendToQueue. For example,
 

<% Set Mail = Server.CreateObject("Persits.MailSender") Mail.Host = "smtp.mycompany.com" Mail.From = "sales@mycompany.com" Mail.FromName = "Sales Department" Mail.AddAddress "jsmith@company1.com", "John Smith" Mail.Subject = "Sales Receipt" Mail.Body = "Dear John:" & chr(13) & chr(10) & "Thank you for your business." On Error Resume Next Mail.SendToQueue If Err <> 0 Then     Response.Write "An error occurred: " & Err.Description End If %>

When the SendToQueue method is called, a message is not sent directly to the SMTP server for delivery. Instead, it is packaged into a file with the extension .stg and placed into the message queue. The file name is constructed using the current date/time in the following format:

MMDDHHMMSSxxx.stg

The xxx suffix is simply a number from 000 to 999 which is appended to the file name to ensure uniqueness in the message queue.

The message files generated by the SendToQueue method are in the standard Microsoft Structured Storage Document format and can be viewed with the DocFile Viewer utility (DFVIEW.EXE) found under the Microsoft Visual Studio 6.0 Tools group.  These files contain message properties (host, body, subject, recipient addresses, etc).

The Mail.SendToQueue method has one optional argument: the message queue path. If the argument is omitted, SendToQueue attempts to use the Message Queue Path parameter from the registry (HKEY_LOCAL_MACHINE\SOFTWARE\Persits Software\AspEmail\EmailAgent). It is not necessary to specify this argument, unless the EmailAgent service and Web server are running on two different machines and AspEmail has no access to EmailAgent's configuration parameters in the registry.

The EmailAgent service retrieves messages from the message queue in the order they were placed there by AspEmail. It unpackages the next message and passes the message properties to an instance of AspEmail that it creates internally. If the message is successfully sent, EmailAgent moves it to the \Sent sub-folder and moves on to the next message in the queue (if the "Do not move sent messages to the \Sent folder" option is checked, EmailAgent simply removed the message from the queue without moving it). If the attempt to send a message fails EmailAgent moves it to the \Failed sub-folder and posts an error message to the Event log (see the next section).

AspEmail 4.2 has a new property, Timestampof the type Date, which you can use to defer message processing. For example, if you want a batch of messages to be sent out at midnight tonight, you can say:

...
Mail.Timestamp = Date + 1 ' set delivery time to 00:00:00 of the next day
' set other properties
Mail.SendToQueue

Notice that you cannot use the Timestamp to expedite the delivery of a message, only to defer it. If tis property is not set, messages will be sent out in the order they were placed in the queue. Notice also that the Timestamp property only affects the SendToQueue method, but not Send.

EmailAgent is an NT service and therefore it cannot report errors in the traditional way, via message boxes. Instead, every time an error occurs EmailAgent posts an error message to the Event Log which is part of the Windows NT operating system. The purpose of the Event Log is to provide a central reporting facility for all system components and applications. The contents of the Event Log can be viewed with the Event Viewer application found under the Administrative Tools group.

The event log is sub-divided into three sections: application, system and security. EmailAgent always writes to the application section of the log.

You should check the Event Log whenever one of the following conditions occurs:

1. The EmailAgent service won't start.
2. A message was moved from the message queue to the \Failed sub-folder.
3. The EmailAgent service unexpectedly terminated.

The two main reasons why EmailAgent would refuse to start are described in the section Starting EmailAgent Service above.

EmailAgent will move a message from the message queue to the \Failed folder either because the message file is in an invalid format, or an error occurs when attempting to send the message using the AspEmail component. To fnd out exactly what happened, fire up the Event Log and open an event entry generated by EmailAgent:

This screenshot shows a typical Event Log error entry generated by EmailAgent. It contains the name of the message file that causes a problem, and the description of the problem (in this case, AspEmail returning the error No route to host). Once you fix the problem which had caused a message to be moved to the \Failed sub-folder, you should either manually move the file(s) back to the message queue using the Windows File Explorer, or generate a new message file.

The main reason why EmailAgent would unexpectedly terminate is inability to remove a message file from the message queue. This can happen if EmailAgent cannot find the \Sent and/or \Failed sub-folders, or a message file being moved is locked by another application. You should be very careful when trying to manipulate or view files in the message queue as it may cause a message file to become locked which may result in EmailAgent's termination.

The EmailAgent can be stopped by clicking the Stop button on the EmailAgent configuration box, or using the standard Services control panel. If there are no messages in the message queue, EmailAgent should stop almost immediately. However, if EmailAgent is in the middle of sending a message, it will not stop until the message is sent. Therefore, if a large message is being sent over a slow connection, it may take several minutes to stop the EmailAgent service.

To remove the EmailAgent service from your system, do the following:

1. At your MS DOS prompt, execute the command

c:\EmailAgent>EmailAgent -UnregServer

2. Delete the file EmailAgentCfg.cpl from the c:\winnt\system32 system directory.

Pricing

The EmailAgent service itself is free. However, the SendToQueue method of AspEmail is a premium feature which requires a registration key after a 30-day evaluation period. For more information on the AspEmail premium features, and to purchase your registration key, visit the www.aspemail.com web site.

Getting Help

Before contacting Persits Software, Inc. for help, please check out the Frequently Asked Questions section at the www.aspemail.com web site. For technical support, please write to support@aspemail.com.