May 1999

Sending Email via ASP and CDO for NT Server

by Scot Johnson

Email has become an essential communication tool in today's information-centric world. With an email client on virtually every desktop, this electronic notification mechanism is extending beyond person-to-person messaging capabilities and is playing a critical role in application notification, broadcast, and alert systems. Stand-alone processes and applications use email to automatically notify individuals, such as network administrators, backup operators, or system attendants, that disk space is getting low, broadcast status updates, or a process is complete. This article discusses how to use Internet mail capabilities and Collaboration Data Object (CDO) for NT Server to provide real-time messaging capabilities. After reading this article, you won't be a messaging expert, but you will be able to work with your messaging specialist to add email capabilities to your applications. Let's get started!

Covering the basics of messaging and CDO

In order to facilitate sending Internet email from the Internet Information Server (IIS), Microsoft created CDO to act as an interface into a messaging service based on standards set forth in Microsoft's Messaging Application Program Interfaces (MAPI). MAPI is a messaging architecture created to standardize messaging communications across different hardware and software platforms. In addition, MAPI provides a transport layer into the final messaging service that's ultimately responsible for housing and/or delivering the message. Therefore, by creating a simpler interface layer, CDO makes developing email-enabled applications easier by reducing the complexity of having to code directly to MAPI-compliant services. One reason the CDO is powerful is because it exposes the groupware functionality and message stores found in the Microsoft Exchange Server and Microsoft Outlook. These services allow you to send and receive Internet email, access calendar and scheduling information, and access public folders and threaded discussion databases. You may have already used CDO without knowing it. If you've used the Outlook Web Access (OWA) for Microsoft Exchange 5.5, then you've used CDO. In a technology evolution, there are different versions of CDO, each with its own capabilities.

CDO was initially released as OLE Messaging (OLEMSG.DLL) with Exchange 4.0. With the release of Exchange 5.0, Active Messaging was upgraded to CDO version 1.1 and then upgraded to version 1.2, with the rollout of Exchange 5.5. CDO 1.2 actually consists of two libraries: the CDO Library (CDO.DLL) and the CDO Rendering Library (CDOHTML.DLL). The CDO Library enabled a connection into a MAPI mailbox and the CDO Rendering Object allowed content of Exchange folder to be rendered in HTML format.

Just when you thought it was safe, CDO for NTS (CDONTS.DLL) was released with IIS 4.0. CDONTS is a scaled back version of the full-blown CDO library--everything but the Exchange Server specific functional, such as calendaring and scheduling. CDO for NTS is designed primarily to quickly enable Internet mail capabilities via the SMTP Server and IIS4, enabling anonymous messaging without SMTP login.

SMTP server configuration

In order to set up our example, we need to ensure the SMTP server is configured properly to reach your SMTP server. Let's review the steps needed in our SMTP process flow:

Message information is collected via an HTML page.
The message is converted to a file via CDO for NTS via ASP.
The local SMTP Server delivers the message itself--or you can use another SMTP Server that acts as an Internet mail gateway.

After creating an HTML page to gather input from the user, we're going to use ASP and CDONTS to send a message request to a local SMTP Server. This SMTP Server is installed on the same machine on the IIS Server. Assuming that you have a DNS server to resolve the MX and A records, the SMTP server will deliver the mail. If you don't have a local DNS server, don't fear--you can route the messages to a remote SMTP server that's configured to send messages to the Internet. This is often the case in most organizations where you have to use a corporate mail server for all outbound email.

In order to route your message to a remote SMTP server, you must configure your SmartHost and Fully Qualified Domain Name in the Delivery tab of the local SMTP server. The SmartHost property tells what server to route your messages to. The SmartHost property can be either a string domain name or an IP address. The Fully Qualified Domain Name (FQDN) allows you to specify the host.domain name for the SMTP server. Without changing this string, the SMTP Server will use the name specified in DNS settings in the TCP/IP property sheet. In this example, our FQDN is mail.northamerica.i3solutions01 and our SmartHost is pointed to smtpmail.northamerica.i3solutions.com, as seen
in Figure A.

Figure A: Use the SmartHost to route SMTP requests to an additional SMTP Server.

[ Figure A ]

Now that we're properly sending SMTP messages, there's only one more catch, depending on the location installation of the IIS and SMTP servers. If the SMTP Server and IIS Server are installed on the same machine with the same IP address, the local SMTP service will automatically send the outbound email without having to set any special user permissions. If your SMTP Server is located on a separate machine from your IIS machine, you have to give the Web server operator's Internet anonymous user account rights to the remote SMTP server. Do this by selecting this account under the Operator tab in the Local SMTP Site properties sheet, as seen in Figure B.

Figure B: Assign operator permissions for a remote SMTP Server.

[ Figure B ]

File summary

Once your system is properly configured, we're going to use two sets of pages that will demonstrate how to use the CDONTS object. These pages will demonstrate how to send a message, attach documents, control formatting and encoding properties, enable HTML within message body, and add custom message headers. In this article, we'll use files with the .htm extensions as the data input pages, and pages with the .asp extensions to process the CDONTS objects. Table A illustrates the page names and descriptions in this month's Zip file.

Table A: File Listing

Page name Description

cdonts_simpleInput.htm Basic CDO for NTS Input page

cdonts_simpleInput.asp Basic CDO for NTS processing page

Using the CDONTS NewMail object Let's get started by discussing the CDO for NTS object model. The CDO for NTS Object Model consists of multiple objects. The NewMail object allows you to create and send new mail messages. For the purposes of this article, we're only concerned with creating new messages, and we're only going to focus on using the NewMail object. If you've ever used an Internet mail program, you'll notice similar properties when creating a new mail message as in the NewMail object. The NewMail property descriptions are shown in Table B.

Table B: CDONTS properties and descriptions

Property Description

Bcc Sends a blind copy of the message to this semicolon-separated list
Body Contains the content of your message in text of HTML format

BodyFormat Sets the text format of the message

Cc Sends a copy of the message to the semicolon-separated list
ContentBase Sets the base property for URLs in the body of the message
ContentLocation Sets the absolute or relative paths for URLs contained in the message's body
From Sets the sender's address
Importance Sets the level of importance of the sent message

MailFormat Sets the mail encoding format to MIME or text format

Subject Sets the subject of the message
To Sends the message to this semicolon-separated list
Value Sets additional header information for the message

Version Retrieves the version of the CDONTS.DLL

After setting the NewMail properties, you can use the NewMail methods, shown in Table C, to perform actions on a message. These actions include adding attachments and URLs, sending messages, and setting local IDs.

Table C: CDONTS method descriptions

Method Description

AttachFile Adds an attachment to the current message

AttachURL Adds a URL as an attachment
Send Sends the message to the TO, CC, BCC recipient list

SetLocaleIDs Sets the user's local messaging environment variables

Using basic CDONTS techniques

Consider the following situation: we want to automatically send a message to notify the network administrator that a specific amount of concurrent HTTP connections was reached. Granted, in most situations when you're building messaging systems that allow applications to alert or notify external processes, you won't build a user input page. However, for the sake of this demonstration, we've created a user input screen, named cdonts_simpleInput.htm. This Web page, shown in Figure C, enables the user to specify whom to send the message to, from whom the message is sent, the subject matter, and set the Importance level and enter the message text.

Figure C: cdonts_simpleinput.htm as viewed in the browser.

[ Figure C ]

After the message is sent, the network administrator would receive the notification in his email via Outlook 2000, as shown in Figure D.

Figure D: Here's the alert message delivered by CDONTS.

[ Figure D ]

Now, let's take a closer look at the individual pages that make this email processing possible. First, let's review the HTML code that's used to collect the data cdonts_simpleInput.htm. Upon review, you'll notice that this page contains HTML Form elements with FrontPage validation and posts its results to cdonts_simpleInput.asp for processing, as seen in Listing A.

Listing A: cdonts_simpleInput.htm


<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Language" CONTENT="en-us">
<META NAME="GENERATOR" content="Microsoft FrontPage 4.0">
<META NAME="ProgId" content="FrontPage.Editor.Document">
<TITLE>CDO for NTS -Simple Input Page</TITLE>
</HEAD>

<BODY>
<FORM METHOD="post" ACTION="CDONTS_simpleInput.asp" 
ONSUBMIT="return FrontPage_Form1_Validator(this)" 
NAME="FrontPage_Form1">
<TABLE BORDER="0" width="100%">
<TR>
<TD VALIGN="top" ALIGN="left">From:</TD>
<TD VALIGN="top" ALIGN="left"> 
<P><!--WEBBOT BOT="Validation" STARTSPAN 
S-DISPLAY-NAME="From"
S-DATA-TYPE="String" B-ALLOW-LETTERS="TRUE" 
B-ALLOW-DIGITS="TRUE"
B-ALLOW-WHITESPACE="TRUE" S-ALLOW-OTHER-CHArs="@."
B-VALUE-REQUIRED="TRUE" I-MINIMUM-LENGTH="4" --><!--WEBBOT
BOT="Validation" endspan -->
<INPUT NAME="txtFrom" SIZE="45"></P>
</TD>
</TR>
<TR>
<TD VALIGN="top" ALIGN="left">To:</TD>
<TD VALIGN="top" ALIGN="left"><!-- WEBBOT BOT="Validation" 
STARTSPAN
S-DISPLAY-NAME="To" S-DATA-TYPE="String" 
B-ALLOW-LETTERS="TRUE"
B-ALLOW-DIGITS="TRUE" S-ALLOW-OTHER-CHARS="@." 
B-VALUE-REQUIRED="TRUE"
I-MINIMUM-LENGTH="7" --><!-- WEBBOT BOT="Validation" 
ENDSPAN --><INPUT NAME="txtTo" SIZE="45">
</TD>
</TR>

<TR>
<TD VALIGN="top" ALIGN="left">Subject:</TD>
<TD VALIGN="top" ALIGN="left">
<INPUT NAME="txtSubject" SIZE="45"></TD>
</TR>
<TR>
<TD VALIGN="top" ALIGN="left">Importance:</TD>
<TD VALIGN="top" ALIGN="left">
<INPUT TYPE="radio" 
NAME="optImportance" VALUE="2">High&nbsp;&nbsp;&nbsp;
<INPUT TYPE="radio" 
CHECKED NAME="optImportance" VALUE="1">
Normal&nbsp;&nbsp;&nbsp;
<INPUT TYPE="radio" NAME="optImportance" VALUE="0">Low</TD>
</TR>
<TR>
<TD VALIGN="top" ALIGN="left">Message:</TD>
<TD VALIGN="top" ALIGN="left"><TEXTAREA COLS=68 
NAME=TXTMESSAGE ROWS=9>Type your message here in text
format</TEXTAREA></TD>
</TR>
<TR>
<TD VALIGN="top" ALIGN="left" COLSPAN="2">
<P ALIGN="center"><INPUT TYPE="submit" 
VALUE="Send Message" NAME="btnSend" 
TABINDEX="1">&nbsp;&nbsp;&nbsp;
<INPUT TYPE="reset" VALUE="  CLEAR  " NAME="btnClear" 
TABINDEX="2"></P></TD>
</TR>
</TABLE>
</FORM>
</BODY>
</HTML>

The page cdonts_simpleInput.asp accepts the posted data and process the CDONTS messaging request. In addition, this page displays results back to the user, as seen in Figure E. A close review of cdonts_simpleInput.asp will expose the core CDONTS processing power, as shown in Listing B.

Figure E: This is the output from cdonts_simpleInput.asp after Internet email is sent.

[ Figure E ]

Listing B: cdonts_simpleInput.asp


<%@ LANGUAGE="VBSCRIPT" %>
<% 
Option Explicit
On Error Resume Next

Sub WriteHTML(strInput)
	Response.Write(Server.HTMLEncode(strInput) & "<BR>")
End Sub
%>
	
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="Microsoft FrontPage 4.0">
<TITLE>Send CDONTS - Simple Input</TITLE>
</HEAD>
<BODY>

<%
Dim objMsg, strFrom, strTo, strSubject, strBody, 
lngImportance
strFrom = Trim(Request.Form("txtFrom"))
strTo = Trim(Request.Form("txtTo"))
strSubject = Trim(Request.Form("txtSubject"))
strBody = Trim(Request.Form("txtMessage"))
lngImportance = Trim(Request("optImportance"))	

Set objMsg = Server.CreateObject("CDONTS.NewMail")

objMsg.From = strFrom
objMsg.To = strTo
objMsg.Subject = strSubject
objMsg.Body = strBody
objMsg.Importance = lngImportance
objMsg.Send

'=== Alternatively you could have sent this in one line:
'objMsg.Send strFrom, strTo, strSubject, strBody, 
lngImportance
         
Set objMsg = Nothing

WriteHTML("The following message was sent via CDO for NTS:")
WriteHTML("From: " &strFrom)
WriteHTML("To: " &strTo)
WriteHTML("Subject: " &strSubject)
WriteHTML("Importance: "&lngImportance)
WriteHTML("Body: " &strBody)
%>
<HR>
Send another message with <A HREF = "cdonts_advInput.htm">
advanced features</A><BR>
Send another message with <A HREF = "cdonts_simpleInput.htm">
basic features</A>
</BODY>
</HTML>

If we sort through the code in Listing B, the core CDONTS processing takes place in the following code snippet:


<%
`=== Assign variables
Dim objMsg, strFrom, strTo, strSubject, _
	strBody, lngImportance
strFrom = (Request.Form("txtFrom"))
strTo = Trim(Request.Form("txtTo"))
strSubject = Trim(Request.Form _
	("txtSubject"))
strBody = Trim(Request.Formn _
	("txtMessage"))
lngImportance = Trim(Request _
	("optImportance"))

Set objMsg = Server.CreateObject _
	("CDONTS.NewMail")
objMsg.From = strFrom
objMsg.To = strTo
objMsg.Subject = strSubject
objMsg.Body = strBody
objMsg.Importance = lngImportance
objMsg.Send
     
Set objMsg = Nothing
%>

This code snippet uses the Request.Form object to assign variables into the To, From, Subject, Importance, and Body of the message. Next, the CDONTS object is instantiated with the Server.CreateObject method:


Set objMsg = Server.CreateObject _
	("CDONTS.NewMail")

Now that an instance of the object exists and the object's properties are set, the message is sent using the send method:


objMsg.Send

You could have also sent the message using just three lines of code:


Set objMsg = Server.CreateObject
=>("CDONTS.NewMail")
objMsg.Send strFrom, strTo, strSubject,
=>strBody, lngImportance
Set objMsg = nothing

Although the send method syntax allows all arguments to be optional, your message isn't much good if it isn't sent to a valid SMTP address (user@domain):


Send ([From] [, To] [, Subject] [, Body] 
=>[, Importance])

Conclusion

As you can see from our example, the CDONTS technology is straightforward, with one quirk to keep in mind: once the CDONTS object has sent the message, the object can't be used to send another message. If you find yourself in a situation where you have to send multiple messages within the same script, you'll need to create a process to serially creating unique CDONTS objects.

Copyright © 1999, ZD Inc. All rights reserved. ZD Journals and the ZD Journals logo are trademarks of ZD Inc. Reproduction in whole or in part in any form or medium without express written permission of ZD Inc. is prohibited. All other product names and logos are trademarks or registered trademarks of their respective owners.