DevGuru Tutorials

Quick References

Features

Partners

A Beginner's Guide to Sending Email from an ASP Page

In this tutorial, we will learn how to send email from an Active Server Page using CDONTS (Microsoft Collaboration Data Objects for Windows NT Server). Although there are other CDONTS objects, we will focus solely on the NewMail object in this tutorial. We will cover most of the properties and methods of the NewMail object, and will develop, step by step, a complete and thorough example.

It is assumed that the reader has some familiarity with creating ASP pages using VBScript. (Note: If you are viewing this tutorial from a downloaded zip file, the links will not work.)

We begin by declaring an object of type NewMail.

We then use the From property of the NewMail object to indicate the sender of the message. The From property is required, and multiple senders are not permitted. The type of this property is String.

Analogously, we use the To property of the NewMail object to identify the recipients of the message. This property is also of type String. At least one of the To, Cc or Bcc properties (Cc and Bcc properties discussed subsequently) must be nonempty. Each recipient must be addressed in full, with multiple recipients separated by semicolons.

The Cc property (for indicating recipients of copies of the message) and Bcc property (for indicating recipients of blind copies) work exactly like the To property. Neither of these properties is required, however, and both are of String type.

It is important to include a subject line in our email messages, so we do that next using the Subject property, which is of type String. This property is not required, however, and could be set to an empty string.

The BodyFormat property sets the text format of the NewMail object. It is of type Long, and has two possible values: 0, which indicates that the body of the message includes Hypertext Markup Language (HTML); or 1, which indicates that the body of the message is exclusively plain text. The default value for the BodyFormat property is 1, so this property does not need to be set for plain text messages. Our example message will be in plain text, but, for demonstration purposes, we will explicitly set the BodyFormat property.

The MailFormat property sets the encoding for the NewMail object. It is of type Long, and has two possible values: 0, which indicates that the object is to be in MIME (Multipurpose Internet Mail Extension) format; or 1, which indicates that the object is to be in uninterrupted plain text. This property is optional, and its default value is 1. This property determines the default value for the EncodingMethod parameter in the AttachFile method (to be discussed later). Since we will be including an image attachment (later), we will set the MailFormat property to 0 now.

The Importance property (optional) allows us to set the importance associated with the NewMail object. Its type is Long, and the possible values are: 0, indicating low importance; 1, indicating normal importance (default); and 2, indicating high importance. Our message is very important, so we will set the Importance property accordingly.

To set the text of the NewMail object, we use the Body property, which can consist of plain text only, or can contain HTML (as described in the discussion of the BodyFormat property). The Body property is either of type String or Istream object (C/C++/Java only). The Body property is not required, so it is possible to send a message with no body text at all. In fact, if you really want to be mysterious, you can send a message with no subject and no body! We, however, have an important message to send, so we will provide text for the Body property.

If we wish to include an attachment with our mail message, we use the AttachFile method of the NewMail object. This method has three parameters.

The first parameter is Source, of type String or Istream object. This parameter is required, and must contain the full path and file name of the attachment. Only C/C++ and Java programs can use an Istream object.

The second (optional) parameter is FileName, of type String. This provides a file name to appear in the attachment's placeholder in the message. If not specified, the file name from the Source parameter is used.

The third (optional) parameter is EncodingMethod, of type Long, which indicates the encoding of the attachment. There are two possible values: 0, meaning the attachment is in UUEncode format; and 1, indicating the attachment is in Base64 format. (Base64 is the encoding scheme defined by MIME; UUEncode is an older format that you should use if you suspect your recipient(s) may not have a MIME-compliant system.) The default value of this parameter depends upon the MailFormat property. If the MailFormat property is set to 1, the default value of EncodingMethod is 0. If the MailFormat property is set to 0, the default value of EncodingMethod is 1.

In our example, we have already set the MailFormat property to 0, but we will still explicitly assign a value of 1 to the EncodingMethod parameter, for demonstration purposes.

At last, we are ready to use the NewMail object's Send method to send our email. After the Send method executes, the NewMail object becomes invalid and cannot be used for another message. Therefore, being conscientious programmers, we set that object to Nothing to release the memory. (We also do this because an accidental access of any kind to the NewMail object after Send executes will raise an embarrassing error!)

That should do it!

We conclude by mentioning that the Send method has optional parameters for From, To, Subject, Body and Importance (in that order). Therefore, we can include values for these properties when calling the Send method, rather than explicitly assigning values to the corresponding properties of the NewMail object. If the To property has already been given a value, and is also supplied as a parameter to the Send method, the message is sent to all recipients in both lists. If the other properties have been given values previously, and specified again in the Send parameters, the prior values are overwritten.

In our example code segment, if we reached the point of calling the Send method and decided to add a recipient to our mailing list, and also change the text of the subject line, this could be done as shown below. The original recipients specified in the To property would receive the message, in addition to the new recipient. The Subject property would be changed, but the From, Body, and Importance properties would retain their earlier values, as would the other NewMail properties. Note that a comma appears after the call to Send, but before the string intended for the To property. This is because we are not modifying the From property, which is the first parameter to the Send method. Without the comma, "youtoo@youraddress.com" would become the From property value, and "new subject" would be appended to the To property value. Delineating commas are not required after the last explicitly-provided parameter.

Now that you know all about the CDONTS NewMail object, let's look at how to put this all together in a working user interface. We offer two ways to do this. (Note: If you are viewing this tutorial from a downloaded zip file, the links will not work.)

You can see an example of an cdonts email submission form.

Or you can download a zip copy of this tutorial and its supporting form-handling pages to see how they work. Further you can easily customize these email forms for your own needs.

Note, however, that our sample user interface does not provide a means for the client to specify an attachment. This is because the Request.Form method used to process the form is limited in that it only allows plain text upload, and users often wish to include attachments in alternative formats. If you wish to add attachment capability and support it fully, the Request.Form method must be augmented with additional software, e.g. dgFileUpload.

[NOTE]
If you are using CDOSYS for Windows 2000 or Windows XP, the code will be be slightly different, as shown below:

[END NOTE]

We hope our CDONTS NewMail tutorial has been helpful. Thanks for browsing by, and, as usual, make sure to visit the Guru often for our hottest tips and tutorials!