Sending Email from IIS

Use the SMTP service to send email messages from your Web server

Despite the explosion of Web sites available on the Internet, email is still the most widely used Internet service. You can easily configure your IIS machines to send email messages over the Internet or through intranets. To do so, you need the Microsoft SMTP Service. I show you how to configure the SMTP service, includ-ing some advanced parameters, and provide a few downloadable code samples that you can leverage in your environments.

Getting SMTP Up and Running
If you haven't used the SMTP service before, it must be running on your Web server. The SMTP service is part of the default IIS installation. If you performed a custom IIS 5.0 or IIS 4.0 installation and chose not to install the service, you can easily add it from the Control Panel Add/Remove Programs applet. To do so, open the Add/Remove Programs applet, click Add/Remove Windows Components, select the Internet Information Services check box, then click Details.

In a default IIS installation, one SMTP server is installed. You can verify that it's running by opening Internet Services Manager (ISM) and viewing the SMTP server. FTP sites appear first, followed by Web sites and SMTP sites. If the SMTP server isn't running, right-click it, then select Start.

Advanced Configuration
Now, let's look at a few of the advanced configuration options. Most large or enterprise companies place SMTP servers behind firewalls that block any direct outbound SMTP traffic through port 25. If such is the case in your shop, your email messages will end up in the Badmail folder with cryptic router error-message files. If a smart host is available on your network, you can use it to relay all SMTP messages to the Internet.

In most cases, a smart host is simply another SMTP server with permission to relay outgoing email messages from other internal SMTP servers directly to the Internet. Thus, a smart host should be able to connect simultaneously to both the internal network and the Internet to work as the email gateway. If this setup exists in your company, you can simply add the IP address of the smart host on your network and IIS will send its email messages to that SMTP server for relay to the Internet. To set up a relay to a smart host on an IIS 5.0 or IIS 4.0 machine, follow these steps:

In the Advanced Delivery dialog box, notice the Masquerade domain field. The masquerade domain makes an email message look as though it came from a point other than its true origin. You can easily fake return addresses on email messages. For example, if I enter

HuckabyIISParadise.com

in the Masquerade domain field, mail messages would appear to come from addresses such as tim@huckabyiis paradise.com. Obviously, the practical joke potential is spectacular here, but be forewarned: Configuring POP3 mail servers to check the domain before accepting an email message is equally easy.

Sending Mail Simply with CDONTS
With your SMTP server configured, you're ready for a simple test using Collaboration Data Objects for Windows NT Server. CDONTS is a set of COM components that's installed with IIS and exposes messaging objects to languages such as VBScript in Active Server Pages (ASP) applications. CDONTS has a simple object called NewMail that lets you send email messages from IIS with only a few lines of code. (I show you the inner workings of the CDONTS NewMail object in the next section.) In the simplest implementation of this object, you need only the few lines of code that Listing 1 shows.

Create a sample folder in your test IIS Web server's file system called inetpubwwwrootsmtp. Then, download smtp-cdonts.asp from the Code Library on the Windows Web Solutions Web site (http://www.windowswebsolutions.com) and place the file in the sample folder. Run your favorite editor (e.g., Microsoft Visual InterDev, Notepad) and edit the From, To, Subject, and Message Content parameters appropriately. (You'll probably want to send messages to yourself while testing.) Save the file. Next, open a browser and navigate to smtp-cdonts.asp. IIS will send an email message from your SMTP server.

To properly deliver email messages, you need Internet connectivity from your server. If you don't have Internet access, verifying that the SMTP server is sending email messages is easy because the email messages' file images are dropped into the queue in inetpubmailrootqueue. You can use any email client (e.g., Microsoft Outlook Express) to view these files. If anything is wrong in a message's addressing, the SMTP server moves the email message to inetpubmailrootbadmail.

The CDONTS NewMail Object
The power of the CDONTS NewMail object is its simplicity. I developed two simple Web applications—emailer.htm and emailer.asp—that leverage the CDONTS NewMail object to send email messages from the SMTP server. Download emailer.htm and emailer.asp from the Code Library and place them in the sample folder that you created earlier. Then, run the Emailer Web application by opening emailer.htm in your browser, as Figure 2 shows. Fill in the email fields appropriately to test the Web application. Be aware that this simple Web application is for testing purposes only. The application's logic has no data validation; if you fail to complete any mandatory field of an email message (e.g., To), the application won't warn you but simply fails to send the message.

When you've completed the required fields, click Submit. You'll receive a confirmation page similar to the one that Figure 3 shows. The confirmation page summarizes the parameters the ASP application used when it sent the email message with the CDONTS NewMail object.

Now let's take a peek at what's under the covers of the Emailer Web application. The sole purpose of emailer.htm is to gather the appropriate HTML form variables so that the file can submit them to emailer.asp. When emailer.htm has gathered the form elements, the file uses the simple HTML statement

to send the variables to emailer.asp.

Emailer.asp is the heavy lifter of the Emailer Web application. At the top of emailer.asp, you'll see a statement, such as

Dim objSendMail

Although not syntactically necessary, it's good practice for Web developers to specifically declare local variables with the Dim statement.

After declaring the local variables, each HTML form element is assigned to a local variable:

strFrom=request _.form("txtFrom")

Next, the application executes the Write function with each variable you entered in emailer.htm:

Write("strFrom = " & strFrom)

This step isn't strictly necessary, but I include it for two reasons. First, it's useful in debugging the code. Second, it's good practice in UIs to give users some form of screen I/O.

At this point, the most important step occurs: The code sends the email message. First, the CDONTS NewMail object is instantiated:

Set objSendMail = CreateObject _("CDONTS.NewMail")

Next, each property of the email message is assigned the appropriate value from the information you entered in the HTML form, as the code in Listing 2, page 14, shows. Finally, the application uses the NewMail object's Send method to execute email delivery:

objSendMail.Send

At the end of emailer.asp, the code uses the Set statement to assign each local variable to the Nothing keyword with code such as

Set objSendMail = Nothing

Setting a local variable to the Nothing keyword releases the association between the local variable and the object it represents. Now that you've learned the basics of using the SMTP service and sending email messages, let's look at a more practical application that you can use daily in your job as an IIS administrator.

Sending Email from the Command Line
You don't need to build or run Web pages to send email messages. You can just as easily build Windows Script Host (WSH) scripts to leverage the power of the SMTP service to send email messages. With code similar to that in emailer.asp, you can send messages from the command line. When you couple WSH technology with the Windows NT Task Scheduler (on Windows 2000 or NT machines), you have a powerful tool for automatically sending email messages on a scheduled basis. This functionality is useful for sending the results of unattended tasks by email.

To help you begin sending messages from the command line, I've created a WSH script called SendEmail.vbs, which you can download from the Code Library. You can copy SendEmail.vbs to any folder on your IIS server to which you have rights. Like the Emailer ASP application, this WSH script uses the CDONTS NewMail object to send mail, as the code in Listing 3 shows.

In WSH scripts, displaying help about how to run those scripts is always good practice. In SendEmail.vbs, a simple subroutine called DisplayUsage provides this help, as the code in Listing 4 shows. By default, wscript.exe is the interpreter for VBScript files. You can easily change to another script interpreter, such as cscript.exe, or you can turn the interpreter off completely. (Many IIS administrators turn off the interpreter as a security measure.) The point is that, depending on how you've configured your OS, you might be able to run SendEmail.vbs as a standalone script, or you might have to specifically state a script interpreter to run it. I designed SendEmail.vbs to run with the CScript interpreter, which has a much less obtrusive UI. Generally, if you want to run WSH scripts without user intervention, you use the CScript interpreter. If your WSH script requires user interaction, you use the WScript interpreter. You can run the script with any of the switches you see in Web Figure 1 (InstantDoc ID 23811).

The functionality of SendEmail.vbs is simple. First, the script parses the parameters' local variables. If anything is wrong with the parameters, the script calls the DisplayUsage function. Then, the script uses the CDONTS NewMail object to send the email message. Now I show you how to automate this process.

Sending Email Messages Automatically
Task Scheduler can run any executable at a scheduled time. To run Task Scheduler on a Win2K machine, open the Control Panel Scheduled Tasks applet, then double-click Add Scheduled Task to start the Scheduled Task Wizard. Click Next on the first screen. Then, choose the executable (i.e., program) that you want to run. (Script interpreters aren't registered as programs, so they won't appear in the list.) Click Browse, then navigate to winntsystem32. Choose cscript.exe. Type a descriptive name for your task, then select the frequency with which you want the task to execute. You can always change the frequency later, so I suggest that you select the One time only option while you're testing, then schedule the task for repetitive frequency when in production. Click Next, then set the appropriate time and date on which you want the task to execute. Click Next, then enter the security credentials (i.e., username and password) under which you want the task to run. Click Next. On the wizard's last screen, select the Open advanced properties for this task when I click Finish check box. You must select this check box because you'll need to format the call of your WSH script through the scheduled job's advanced properties. Click Finish. The scheduled job's advanced properties dialog box, which Figure 4 shows, appears.

The format of the Run command that I used in testing was

C:winntsystem32cscript.exe"SendEmail.vbs"-t [email protected] [email protected] "Test Message"-b "This is the body of the _Test Message".

Notice that I changed the Start in field to show the location of SendEmail.vbs, which in my case is C:inetpubwwwrootsmtp. You might also want to consider a strategy in which the message subject and body are hard-coded within the WSH script so that the script isn't dependent on parameters.

You can dynamically create SendEmail.vbs with hard-coded information by using another WSH script that employs the FileScriptingObject object. I've created a hard-coded version of SendEmail.vbs called HardCodedSendEmail.vbs, which you can download from the Code Library. Set the scheduled time to a minute in advance to test the scheduled email message. Or you can simply right-click the scheduled task and choose the run option to run the scheduled tasks immediately.

You can also use the At command from the command line to schedule tasks, but you have significantly less control with this method than you do with Task Scheduler. Here's an example of an At call from the command line:

At 9:37:00 "C:winntsystem32  cscript.exe SendEmail.vbs  -t [email protected]  -f [email protected]  -s Test -b Test"

Note that the At command has severe limitations. First and most important, you must set the entire command string that follows the At command in double quotes. This limitation prevents you from having multiple words in the message subject line or text body. Also, the command string is limited to 259 characters and must be one continuous string.

A Foundation for the SMTP Service
Using the CDONTS NewMail object to send email messages through the SMTP service is one of the most powerful yet simplest technologies in IIS. The code examples that I've provided illustrate how you can use the SMTP service to send automated email messages easily. You now have a foundation for getting your SMTP server up and running and scheduling the sending of automated email messages. Next month, I'll explain the inner workings of global.asa.